过期文档正在误导代码智能体
文章指出,仓库中的旧需求、废弃方案和探索记录可能被代码智能体检索并当作有效指令。作者主张区分历史资料与持续有效的工程知识,避免无差别堆积文档污染上下文。
AI 深度解读
仓库里留下的旧方案,正在从「以后可能用得上的资料」变成 AI 编程时可能读到的指令。作者的主张很明确:需求规格文档(spec)完成协调任务后,就该退出日常工作上下文,把位置留给当前规则、操作流程和关键决策记录。
这不是劝团队少写文档,而是要求文档有明确的职责和有效期。对已经使用 Codex、Claude Code 或 GitHub Copilot 的团队,这篇文章值得读的地方,是它把文档整理变成了一个工程问题:怎样避免 Agent 按过期计划修改今天的代码。
为什么旧文档会影响今天的代码
过去,工程师看到 docs/old/,通常知道里面的内容需要结合年代阅读。Agent 却可能在搜索、检索或总结仓库时拿到这些材料,并把其中的计划当作仍然有效的要求。
作者据此提出:仓库文本已经参与代码的实现过程。
原文列出了几种明确的入口:Codex 读取 AGENTS.md,Claude Code 读取 CLAUDE.md,Gemini 使用 GEMINI.md;GitHub Copilot 支持仓库级指令、路径级指令,以及供 Agent 使用的 AGENTS.md。原文特别指出,匹配路径同时存在仓库级和路径级 Copilot 指令时,两者都会被使用。
这些文件可以告诉 Agent 怎样安装依赖、运行局部测试、遵守安全边界,也可能引入互相冲突的要求。再加上检索得到的历史文档,模型要同时处理当前任务、代码、测试输出、工具结果和旧方案。
作者最担心的不是多花一点 token 费用,而是 Agent 读到一份 2024 年的上线计划,随后把团队在 2025 年已经推翻的决定恢复回来。
历史材料可以继续保存,但不该默认拥有指导当前实现的地位。
这里也要分清两种情况:指令文件有工具规定的加载机制,普通文档则可能通过搜索或检索进入上下文。原文没有证明所有 Markdown 都会自动加载;它指出的是,旧资料一旦进入上下文,就可能与当前要求争夺注意力。
spec 交付后,应该留下什么
spec 的任务,是帮助团队决定做什么、协调怎样完成变更。尤其当工作横跨产品、运维、安全和架构时,提前写清方案很有价值。
但功能上线之后,spec 描述的「准备实现什么」,未必等于系统「实际实现了什么」。开发中可能调整范围、改变接口,也可能放弃某条技术路线。把完整 spec 长期放在显眼位置,就会让计划与现实并排存在,却没有清楚说明谁更可信。
作者给出的分工是:运行中的系统体现现实,代码提供证据,测试表达团队愿意维护的行为,运行手册说明怎样操作系统,简短记录解释特殊取舍。
这套分工并不保证代码和测试永远正确,但它提醒团队:上线后不能继续只靠最初的计划描述系统。
作者将仓库文本拆成四种,各自承担不同工作。
第一种是稳定规则。它回答验证命令是什么、模块边界在哪里、哪些安全要求不能违反、PR 需要包含什么。这些内容适合放进简短的 AGENTS.md、CLAUDE.md 或路径级指令。作者认为,一条要求如果连一个季度都难以保持稳定,可能还不适合作为长期规则。
第二种是技能和操作流程。发布软件包、轮换凭证、排查不稳定的集成测试、创建迁移,都有步骤、前置条件和检查方法。它们适合独立成 playbook,在任务相关时加载。根指令文件塞进八段发布说明,再让 Agent 自己判断哪些段落适用,会增加无关信息。
第三种是架构决策记录(ADR)。它记录一个重要决定的背景、备选方案、结果和后果。例如,为什么选择某种数据库,为什么接受一致性上的取舍。它要保留的是决定背后的理由,而不是完整会议过程。决定改变时,旧记录指向替代它的新记录,避免把过去改写成仿佛从未发生。
第四种才是 spec、讨论串、会议记录和探索性提示词。它们是追溯历史的证据,适合归档、挂到关联 issue,或由 ADR 链接过去。
交付后需要压缩的,是未来工作真正依赖的知识;需要保留原貌的,是供人追查的历史材料。
清理上下文,关键是让当前意图容易识别
作者引用了上下文工程中的四种动作:write、select、compress、isolate,分别对应写入、选择、压缩和隔离信息。
playbook 就是隔离的例子:详细流程仍然存在,但只有执行相关任务时才进入上下文。ADR 则承担压缩历史的作用,把长篇讨论收敛成一个可以理解和追踪的决定。
原文用「读取 30,000 个无关 token 才找到模块并运行测试」说明糟糕体验。这个数字是情境举例,不是作者公布的实测结果。更核心的问题是信息冲突:当前测试、当前规则与旧实施计划同时出现,模型能否辨认哪份材料代表今天的系统?
作者建议,用一个问题审查面向 AI 的文档:没有人在旁解释限制条件时,我们是否愿意让 Agent 今天照着执行?
如果不愿意,就把它移出日常上下文,或者标注清楚,让检索有机会过滤。
具体保留的材料包括:说明项目用途和安全启动方式的 README、简短且有负责人的 Agent 指令、重复任务的 playbook、运行手册、ADR,以及测试和可执行配置。交付后的原始需求、废弃计划、生成的设计长文、重复架构说明,则应退出日常加载范围。
归档也要留路标。docs/archive/ 可以建立索引,说明哪些内容属于历史、为何归档;ADR 可以保留原始提案的入口。每份 AI 指令文件还应有负责人和复查节奏,可以并入依赖升级、运行手册复查或季度维护。
我的判断
我认同作者对「保存历史」和「持续指导工作」的区分。团队容易把这两件事混在一起:文件留下来了,却没人说明它是否仍然生效。Agent 只是让这个老问题更容易影响实际代码。
比起把全部文档塞进根指令,按路径拆规则、按任务加载流程,职责更清楚;比起直接删除旧 spec,归档并保留决策入口,也更方便追查原因。
不过,原文是一套经验性主张,没有提供清理前后的成功率、延迟、费用或错误数量对照。「更少且更准确的上下文更好」在这里是作者的工程判断,不能写成经过实验验证的收益。
还有一个实施前提:移到 docs/archive/,不等于检索工具就会自动忽略。实际效果取决于 Agent 怎么搜索、索引怎样配置,以及归档状态能否被识别。只改目录名,可能仍会搜到相同内容。
spec 也未必一次上线就结束使命。分阶段交付的需求仍可能需要持续协调。更稳妥的判断标准是:它还在指导哪项工作,哪些部分已经完成,遇到冲突时应以什么为准。作者提出的是默认策略,团队仍需要按文档的实际职责执行。
能拿来做什么
- 检查项目的
AGENTS.md或CLAUDE.md,保留当前可执行的安装、测试和构建命令,并明确前端与 Node 模块各自适用的规则。 - 将发布软件包、排查集成测试、创建迁移等重复流程拆成独立 playbook,在入口指令中说明何时读取,减少每次普通修改都要处理的流程细节。
- 对已交付的 spec 做一次状态核对,把仍然有效的约束放进当前文档,把重要取舍压缩成 ADR,再将原始讨论归档并保留入口。
- 用原文的审查问题定期复查 AI 指令:今天能否让 Agent 直接照做。发现过期内容时,同时检查检索是否仍会把它作为当前依据取回。