From fddf69b36d0106a1532622246a487b28095412aa Mon Sep 17 00:00:00 2001 From: ouyangjiahong Date: Mon, 5 Oct 2026 16:51:04 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E6=B3=A8=E5=85=A5=E5=86=99?= =?UTF-8?q?=E4=BD=9C=E8=A6=81=E6=B1=82=E4=B8=8E=E7=BC=96=E7=A0=81=E5=87=86?= =?UTF-8?q?=E5=88=99=E4=B8=A4=E8=8A=82=E6=A0=87=E5=87=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md 此前只有仓库工程契约，没有统一的写作与编码行为标准，各会话的输出风格依赖模型默认行为。本次通过 setup-ouyangjiahong-skills 技能的标准同步脚本，把写作要求与编码准则两节注入 AGENTS.md 末尾，两节内容与技能的 references/standards.md 逐字一致，后续标准更新仍以该源文件为准。同时把 H1 标题从 Repository Guidelines 改为 AGENTS.md，与文件名和同步脚本的完成条件一致。原有章节全部保留，新注入内容已通过 scripts/check_doc_quotes.py 引号门禁。 --- AGENTS.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d32a2c14..5ae5e431 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# Repository Guidelines +# AGENTS.md 本指南面向 AI 助手与贡献者，记录当前代码、构建和验证契约。先读本文件、`CONTEXT.md` 与相关 ADR，再改动；以源码和配置为准，不以旧文档中的工具数量或版本示例为准。 @@ -146,3 +146,29 @@ make clean-tests - 按物理定义、解析解、守恒量、对称性和文献公式验收；不把外部软件运行时输出当 oracle。文献数值区分定义性（论文采用的常数、系数、可复算表值，可断言并记录复现陷阱）与结果性（他人仿真输出，仅 docstring 人工对照，禁入断言）；oracle 类别词汇见 ADR 0055。协议字节、闭式公式等固定值可以验证，但不要用脆弱的实现细节或复制同一实现的断言替代行为测试。 - Python 覆盖率配置为 branch coverage、`fail_under = 55`，需显式运行 `uv run --no-sync python -m pytest --cov` 才启用；`make test` 本身不带 `--cov`。修改行为时先补最小真实调用或回归测试，并运行受影响测试、`make check`；跨层契约变化再扩大到 `make test`。 - `_meta` 测试守护主标记、层级相关契约、常量来源、Rust ABI、共享叶 re-export、原生符号门和测试残留。`make check` 不会自动运行 `_meta`，完整 pytest 收集时才会覆盖这些门禁。 + +## 写作要求 + +所有面向人读的文本（注释、CONTEXT.md、ADR、issue 评论、PR 描述、agent brief、分诊记录、文档、Agent 回复）应当： + +- 准确、清楚、简洁。先理解材料，再提炼结论。 +- 按逻辑组织，区分相近概念。不用空泛、夸大的修饰语。 +- 面向实际读者，从已知事实推到陌生结论。用分析说服，不装腔或堆砌。 +- 语言统一中文，不中英混用。命令、代码、路径、专有名词保留原文。 +- 概念不直译。没有通行译名的概念用功能描述，不生造译名。同一概念全文只用一个词：用“标准”不用“规范”，用“任务要求”不用“规格”，测试结果用“通过、失败”不用“红、绿”。 +- 标点符号：中文语境用全角中文标点（句号“。”、逗号“，”、顿号“、”）。纯英文句子用英文标点。行内代码、文件名、命令后的标点根据所在句子语境选择。引号：中文用弯引号“”，英文用直引号""。列举用顿号（“、”）分隔，最后一项前不加“和”或“与”。 +- 不用破折号（“——”、“—”）、分号、箭头（“→”）、markdown 加粗和表情符号。补充说明用括号，并列与分支写成独立句子，顺序与对应关系用文字表达。 +- 单位用国标：带单位的数值用 GB 3100～3102 的法定计量单位。写单位符号时，数值与符号之间留一个空格（`200 ms`、`5 min`、`64 MB`），不写 `200MS`、`64MB` 这类变体。中文行文里用汉字单位名称（30 秒、5 分钟）同样合规。 + +## 编码准则 + +- 先理解再改动：完整阅读目标文件、相似实现和相关测试。不确定 API 或惯例时查源码或文档，不猜。 +- 明确目标与决策：需求或验收条件不明确时先澄清。架构选择、假设和关键取舍要说明。 +- 保持简单：只实现当前需求。复用已有模式。不为单一用例过早抽象、配置化或引入依赖。 +- 精准修改：只改与任务直接相关的代码，贴合既有风格。删掉本次修改产生的废弃代码，不重格式化无关内容。 +- 注释不留历史：删掉只对读过旧版本的人有意义的注释（“原来是 X”“改成 Y 是为了修 Z”）。注释解释当前代码为什么这样写，变更过程由 git 记录。 +- 完整迁移：变更接口或行为时更新所有调用方、测试和文档。不保留无需求的兼容层。 +- 按根因修复：先复现并读完整错误信息。一次处理一个原因，不用吞异常或特判掩盖问题。 +- 验证行为：按影响范围运行相关检查。测试可观察行为、边界和错误路径，不测试实现细节。无法测试时说明原因并做可行的烟雾验证。 +- 审慎依赖：优先现有依赖和标准库。新增依赖前确认必要性、维护状态和成本，并说明理由。 +- 清楚沟通：说明做了什么、为什么、验证结果和已知风险。对不确定性给出具体事实，提交信息描述实际改动。