让文档与代码同批更新,减少智能体误改
文章提出将文档同步纳入代码变更的完成标准,要求在同一 PR 更新受影响的文档、AGENTS.md 和技能说明。通过全仓搜索定位失效描述,避免后续 AI 编程会话把旧文档当成实现依据。
AI 深度解读
AI 编程代理会把文档当作下一轮开发的输入。新会话从零开始,读到一句过期说明,就可能带着错误前提继续改代码。文档失真因此不只是让人查错资料,还会影响后续实现。
Yonto Player 的做法很直接:代码和相关文档必须在同一个 PR 里修改,否则工作就没完成。文章的价值在于,它把这条规则拆成了可执行的搜索习惯、历史记录处理方式,以及能让测试和构建失败的检查。
为什么文档必须和代码一起交付
作者把规则放在 AGENTS.md 顶部:docs/、AGENTS.md 和 skills/ 都是下一次代理会话要读的内容,只要代码改动对应的文档还没写,任务就没有结束。
这里最关键的是对「完成」的定义。
「之后补文档」只是承诺,构建系统不会因为这个承诺没兑现而报错。把两者放进同一个 PR,审查者才能同时看到行为变化和说明变化,判断它们是否一致。
文档同步应该是完成条件,而不是交付后的待办。
这也不要求每次改代码都整理一遍文档。作者限定了范围:只更新被这次改动推翻的说明。比如一个限制从本地配置改成服务端读取,需要检查所有描述该限制来源的地方,不必顺手重写整份开发指南。
对依赖代理连续开发的仓库,这条规则尤其有用。人的记忆可能暂时弥补文档缺口,新会话却未必知道上个会话发生了什么。
怎么找到被一次改动推翻的所有说明
仓库的 PR 技能 skills/open-a-pr 要求,在写 PR 描述之前,先用一句话回答:这次改动让哪句话不再成立?
这一步把模糊的「检查文档」变成了具体任务。接下来搜索的是这句话涉及的主题,而不是原句。相同事实可能被写成不同表达,按字面搜索很容易漏掉。
原文用下面这段简化清单说明流程,它并非仓库规则的逐字摘录:
Before opening the PR
1. Write one sentence: "This change makes ___ false."
2. Pick the SUBJECT of that sentence (a feature, a name, a limit),
not its wording.
3. grep -rn "<subject>" docs/ AGENTS.md skills/ README.md site/ <source dirs>
4. Read every hit. Start with the file you edited.
5. Update each copy in place. Then search for what your new text asserts.
6. Ask: is there a sentence anywhere this change contradicts?
要看第 3 行的搜索范围:它覆盖文档、技能、站点和源码目录,不能只检查 docs/。源码注释和 README.md 同样可能藏着过期承诺。
作者还强调两个容易省略的动作。
首先,搜索后要读完每个命中位置,从自己刚编辑的文件开始。搜索结果只是候选,不能靠批量替换判断语义。其次,修正后的句子也需要核对。删掉一句错误描述,不代表新写的描述就一定准确。
对于描述当前行为的页面,旧句应当直接重写,避免在旁边追加一句新规则,留下两个互相冲突的答案。AGENTS.md 则尽量只承担简报作用,包含布局、构建命令、规则,以及指向 docs/agents/ 深入说明的「何时阅读」索引。
每个事实少复制一次,未来就少一个需要同步的位置。
哪些内容该重写,哪些该保留历史
作者把文档分成两类,处理方式不同。
AGENTS.md、文档注释和站点页面描述当前状态,需要原地更新。带日期的设计记录保存当时的决定和理由,不能为了符合今天的实现,把过去的决策过程改写掉。
仓库的 docs/design/ 下有接近 60 份按日期命名的记录。后续变化通过带日期的补注说明,并指出什么取代了原来的结论。原文示例保留了 2026-10-24, #NNNN 的原始决定,再以 2026-10-29 (#MMMM) 补充变化;这些编号是示意占位符。
另一条路线是让机器检查可验证的部分。
开发者站点有一个小型插件教程,代码块来自 CLI 中的插件模板。测试会逐一对比页面各语言版本和模板,任意一边单独变化,测试就会失败。这解决的是教程代码和实际脚手架逐渐分叉的问题。
站点还会在 npm run build 中检查页面元数据:标题或描述缺失、标题重复、语言替代版本不完整、未进入 sitemap、结构化数据无法解析,都会导致构建失败。
但这些检查只覆盖已经写成规则的属性。页面把一个按钮叫错名字,构建未必知道。作者对此采用的是另一条协作约定:站点文档沿用应用自己的文字,并和界面字符串在同一个 PR 中修改,例如保持「Add source」这样的名称一致。
能自动验证的交给测试,语义是否真实仍需要审查。
我的判断
我赞成把文档纳入完成条件,也赞成按主题搜索。这套方法成本不高,而且适合会读取仓库说明的 AI 编程流程:它直接约束代理获取上下文的入口。
不过,文章展示的是仓库实践,没有给出实施前后的文档错误率、代理返工次数或审查耗时对照。它的收益有合理解释,效果大小仍是经验判断。
搜索也不能证明没有遗漏。一个功能可能同时有产品名、内部模块名和历史叫法,只选一个主题词仍会漏检。大仓库还可能产生大量无关命中,执行质量依赖维护者是否了解这些别名,以及是否认真阅读结果。
相比定期集中清理,同一 PR 更新更容易利用改动者尚未散失的上下文;集中清理仍能发现历史欠账。相比单纯扩充 AGENTS.md,把细节留在所属文档、入口只保留索引,也更容易控制重复。但前提是代理和审查者真的会沿着索引读取。
能拿来做什么
- 在仓库现有的 PR 流程中加入一句检查:这次修改让哪条说明失效?前端页面名称、Node 配置来源或功能限制变化时,据此搜索相关主题,并在同一 PR 更新命中的有效说明。
- 如果维护 CLI 模板和接入教程,可以仿照原文比较教程代码与模板内容;有多个语言版本时,逐个纳入检查,避免只更新其中一份。
- 将描述当前行为的文档与带日期的设计记录分开维护。前者直接修正,后者追加日期和替代关系,让代理既能找到现行规则,也能理解旧决定。
- 精简 AGENTS.md 中重复的细节,为事实指定主要维护位置,再用阅读索引指过去;对标题、描述和结构化数据等确定性属性,则放进构建检查。