本文规定文档分层、写作规则和字数上限。“文档”指仓库里所有的 Markdown 文件。Agent Note 的格式见 .agents/notes/README.md。
做法来自 DSH 的 docs/AGENTS.md。
每个事实只写在负责它的那一层。其他位置只写链接。
| 层 | 放什么 | 不放什么 |
|---|---|---|
| 根 CLAUDE.md | 每个会话都需要的常驻规则。每条一到三行，并链接负责的文件 | 例子、理由、操作步骤、从其他文件复制的内容 |
| 本文 | 文档标准 | 代码规范 |
| README.md | 文档索引与阅读顺序 | 规则 |
| architecture.md | crate 划分、依赖方向、所有权、领域词汇 | 单个功能的细节 |
docs/subsystems/<子系统>.md |
一个子系统已实现的行为、数据结构、数字、边界与验收清单 | 决策理由、备选方案、目标状态、迁移叙事 |
| Agent Notes | 决策理由、放弃的方案、代价；还没实现的设计（proposed/） |
当前行为的完整规则 |
| crate README | crate 对外提供什么、怎样使用 | 子系统页已有的规则 |
| 代码注释 | 这段代码为什么这样写 | 复述代码，复述设计文档 |
放置规则：
- 已实现的行为、数字与验收清单写进子系统页。
- 决策理由写进 Agent Note。
- 还没实现的设计写成
proposed/Agent Note。 - 常驻规则写进根 CLAUDE.md，并链接它的理由。
- 一个子系统写一页，放在
docs/subsystems/。子系统按功能划分，可以跨多个 crate。 - 只写已经实现的事实：行为、类型、数字、清单与边界。不写理由，在相关小节末尾链接负责的 Agent Note。
- 不写目标状态与“尚未实施”。不写迁移叙事，“以前是什么样”属于 git 历史。
- 页末是“验收”一节。每条写出覆盖它的测试；没有自动测试时，写“手动”，并说明怎样验证。
- 统一使用这些领域词汇：Session、Turn、Model Call、Tool Call、Permission、Message、Update、Trace、Compaction。
- 修改根目录 README 时，同时检查
README.md与README.en.md。 - 还没迁移的功能文档仍在
docs/根目录。改动它们时，也按本节规则写。
新设计按这个顺序进行：
- 写一份
proposed/Agent Note，写明提议与验收条件。 - 实现，并让验收条件对应到测试。
- 在同一个改动里更新子系统页，把 Agent Note 改写为 implemented。
按 ASD-STE100 写文档，中文文档也一样：
- 只用批准词，每个词只用它批准的那一个意思。项目专有名词（Session、Turn、Tool Call、spill）保持原样。
- 程序性句子不超过 20 个词，描述性句子不超过 25 个词。中文按约 40 字、50 字估算。
- 一句只写一条指令。指令用祈使句。
- 用主动语态。
- 名词串不超过 3 个名词。
- 一个段落不超过 6 句。
- 只给改变行为的那一句加粗。处处加粗等于没有重点。
上限按 wc -m 的字符数计算：
| 文件 | 上限 |
|---|---|
根 CLAUDE.md |
4,400 |
docs/AGENTS.md（本文） |
4,700 |
.agents/notes/README.md |
5,200 |
用这条命令检查：
wc -m CLAUDE.md docs/AGENTS.md .agents/notes/README.md超过上限时，按顺序处理：
- 把属于其他层的内容移过去，原处留一行链接。
- 精简属于本层的内容。
- 内容确实需要更多空间时，才提高上限。在提交信息里写明理由。
上限只是护栏，不是精简目标。设定或调整上限时，保留至少 5% 的余量。
审查文档时，查找这些写法：
- 同一条规则写在多处。搜索一句有特征的原文，只保留一处，其他位置改为链接。
- 在不该写历史的层写历史。改为写当前事实，并链接历史所在的位置。
- 状态标注，例如“已实现！”“以后再做：…”。
- 复述代码、生成结果、测试清单或文件清单。
- 推理过程：逐步叙述实现、证明显而易见的分支、复述测试过程。保留结论，删去推导。
- 段落墙：一段里塞进多条规则和括号说明。拆开，或把细节移到负责的位置。