基础篇
进阶篇
高频篇
精选篇
手写篇
面经篇
AI 篇
原理篇
每日一题
小程序题库
  • 知识卡片碎片时间过考点
  • 场景篇按分类整理的大前端场景考点
  • 历年面经按年份追踪真实考点
  • 算法题库NEW在线编码即时判题
  • 专项自测100 题快速查漏
  • 前端基础
    • HTTP从报文一路讲到 HTTPS
    • 浏览器渲染、事件循环、进程
    • 计算机基础Linux、网络、操作系统
  • 进阶专项
    • 设计模式23 种模式怎么用
    • 前端系统进阶学习大型项目工程化
    • 前端综合文章长期沉淀的实践文
  • 工程与工具
    • Node学习指南从环境搭建到服务端
    • NPM工作流script、依赖与发布
    • Docker容器化部署上手
    • Canvas图形与动画实战
  • 路线与导图
    • 思维导图知识点全景图
    • 学习路线按图索骥不跑偏
  • 动态
    • 公众号动态公众号历史文章
    • 博客动态站长的技术博客
    • 开发者导航常用工具与文档站
    • AI 热点每日 AI 资讯与动向
AI 工作台
旧版
AIHT
内容
精选全部 AI 动态热点榜AI 日报收藏
分类
模型行业编程产品技术观点开源
更多
Agent 接入
返回首页开发者导航
AIHT
精选 / 资讯详情
8.0
热点
AI SCORE
编程提效2026-11-21 04:00

让文档与代码同批更新,减少智能体误改

dev.to · AI#AI编程#文档维护#工程规范
Editor brief · 编辑速览

文章提出将文档同步纳入代码变更的完成标准,要求在同一 PR 更新受影响的文档、AGENTS.md 和技能说明。通过全仓搜索定位失效描述,避免后续 AI 编程会话把旧文档当成实现依据。

文章思维导图
Knowledge map
拖拽缩放
AI deep read

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 中重复的细节,为事实指定主要维护位置,再用阅读索引指过去;对标题、描述和结构化数据等确定性属性,则放进构建检查。
Original source

本文由 AI 通读原文后重新编写,观点部分为站内判断,细节以原文为准,来源 dev.to · AI,原文版权归原作者所有。

阅读原文
上一篇
AI 代码验收:用独立检查补足测试盲区
下一篇
63 次测试比较 Claude Code 三种记忆方案

资讯速览

dev.to · AI · 2026-11-21 04:00

AI 评分 8.0 / 10

相关标签

#AI编程#文档维护#工程规范

继续阅读

  • 用运行时拦截为 MCP 工具调用设闸
  • AI 代码验收:用独立检查补足测试盲区
  • 63 次测试比较 Claude Code 三种记忆方案
  • 代码没写模型名,也可能调用退役模型
  • 115 次合并背后的 AI 开源贡献流程