03 · 一事实一归属

一事实一归属

关键文件docs/AGENTS.mdscripts/doc-budgets.manifest.jsonscripts/verify-doc-budgets.tsscripts/verify-md-wrap.tsscripts/verify-type-equiv.ts

AI 写文档最常见的问题是同一件事在三个地方各讲一遍，之后只改了其中一处。docs/AGENTS.md 的应对办法是给每类信息指定唯一的归属；其他地方只放链接。

每条信息只有一个家。按信息回答的问题决定它的归属，其他地方只放链接。生成的参考文档（工具目录、配置目录、CLI 帮助等）由源码生成，并用 --check 防止过期，不允许手改。

写作规则

• 写当前状态。历史放在 commit、PR、Agent Note 和复盘里，正文只描述现在怎样运作。
• 一段一行。每个段落占一个物理行，换行交给编辑器软折行。verify-md-wrap 基于 Markdown AST 检查，这样 diff 只显示真正改动的段落。
• 文档里的 ts 代码块必须能编译（doc-typecheck）。照抄的类型声明标记为 ts type-equiv，由 verify-type-equiv 与源码逐字比对。
• 直接命名。写出具体的检查、类型、API 或操作，不用比喻性的 "gate"、"vocabulary"、"surface"。

字数预算

scripts/doc-budgets.manifest.json 给常驻文档设上限：根 AGENTS.md 2,080 词、docs/AGENTS.md 1,430、docs/architecture.md 2,410、packages/AGENTS.md 810、docs/testing.md 1,350。超限时按顺序处理：

1. 迁移：属于别的层的内容移过去，原处留一行链接。
2. 精简：属于这里但能写得更短的内容，压缩它。
3. 提高上限：只有内容确实需要更多空间时才提高，并在 PR 里说明理由。

上限是护栏，不是删减目标。删字数时不能丢掉失败行为、所有权、限制这些契约信息。

Slop 清单（原文九项）

症状	处理
重复的规则	搜一句有辨识度的原文，只留一处，其余改成链接
历史写在不该写的地方	改成现状描述，链接到历史的归属
实现状态标注："implemented!"、"future: …"	删除；状态由目录结构和包清单表达
手抄的目录、JSDoc、测试清单	源码或生成器是权威时，不手抄
推理过程转录	保留结论性契约，删掉推导路径
理由在兄弟方法旁重复	只在拥有它的能力或辅助函数处写一次
段落墙	拆开，或把细节降级到它的归属
强调泛滥	加粗只留给改变行为的那一句
已实现 Note 里的 "should"、迁移计划、验收清单	已实现的 Note 用现在时描述现状