[AI Generated][DOC] 注入写作要求与编码准则两节标准

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 记录。
+- 完整迁移：变更接口或行为时更新所有调用方、测试和文档。不保留无需求的兼容层。
+- 按根因修复：先复现并读完整错误信息。一次处理一个原因，不用吞异常或特判掩盖问题。
+- 验证行为：按影响范围运行相关检查。测试可观察行为、边界和错误路径，不测试实现细节。无法测试时说明原因并做可行的烟雾验证。
+- 审慎依赖：优先现有依赖和标准库。新增依赖前确认必要性、维护状态和成本，并说明理由。
+- 清楚沟通：说明做了什么、为什么、验证结果和已知风险。对不确定性给出具体事实，提交信息描述实际改动。