对抗AI代码腐化：规格、结果笔记与文件清单的实战方法

一位开发者用八个月时间，几乎完全通过编码智能体（先是 Claude Code，后来转向 Codex）构建了一款桌面应用。这个项目如今累积了约 650 次提交、4.3 万行 JavaScript 代码。他亲自审阅并批准每一次变更，但代码几乎全由智能体编写。

他在 Reddit 上分享的这套工作流之所以值得关注，不是因为智能体写出了糟糕的代码——恰恰相反，它们写的代码质量不错。真正崩坏的是连续性（continuity）。这个问题在项目变大后浮现，且和大多数人的预期都不一样。

智能体协作中真正崩坏的东西

随着代码库膨胀，几类典型故障反复出现：

• 全新的会话会自信地重新提出几周前已经试过并否决的方案；
• 一个号称"小修复"的改动，悄悄触碰了五个文件，其中两个毫不相关；
• 规则文件里写着正确的约定，但智能体恰恰在这些规则该生效的时刻忽略了它们；
• 当他同时运行两个智能体时，它们会互相踩踏对方正在编辑的文件。

这些问题的共同点是：它们都不是"代码能力"问题，而是"记忆与纪律"问题。智能体没有跨会话的可靠记忆，也没有遵守约定的内在机制。

把注意力从收尾挪到开头

作者给出的核心转变是：把审查重心从工作的末端移到开端。任何有分量的任务，都不会在没有一份简短规格（spec）的情况下启动。这份规格包含三件事——问题是什么、约束是什么、以及"完成"意味着什么。

关键细节在于分工：智能体可以起草规格，但作者会亲自重写其中的范围和验收标准。他给出的理由很尖锐——"在工作开始前写下的标准是用来评判结果的，而在工作之后写下的标准只是描述结果。"这句话点破了很多人写验收标准时的自欺：事后补的标准永远是通过的。

规格之后是计划（plan）。计划有一条硬性要求：它必须对照真实代码来核实自己的每一项断言，而不是依赖智能体对代码的"记忆"。计划要记录采用的方案、被否决的备选方案及原因，以及预期会触碰的文件清单。

结果笔记：填补意图与结果之间的鸿沟

真正的工作被拆成小任务，每个任务都是一次"同事可以独立评审"的提交。而作者认为整个流程中最有价值的习惯，是每完成一个任务后，智能体要写下两三句话：发布了什么、哪里偏离了计划、还剩什么没做。

他的洞察是：计划描述意图，代码描述结果，但两者都不解释二者之间的鸿沟，而那些可疑的改动恰恰就藏在这道鸿沟里。所以他审查时会先读这些结果笔记，再把 diff 和计划里的文件清单对比。任何清单之外的改动，要么给出解释，要么被回滚。

用"陈旧标记"管理过期的历史决策

最花时间打磨的部分是历史。Git 只告诉你改了什么，从不告诉你为什么，而且没有智能体会在编辑文件前去读 git log。

作者的解法是：每一份过往规格都按它触碰过的文件建立索引。当智能体准备编辑某个文件时，一个钩子（hook）会把相关的历史决策摆到它面前，并标注状态——当前有效（current）、已陈旧（stale，因为文件后来又变了），或仍在别处进行中（in progress）。他项目里有一个文件累积了来自 19 份规格的 26 条记录。

其中"陈旧"这个标记的重要性远超预期。他的原话是："一个七月正确、九月错误的决策，比完全没有记录还危险，因为它读起来像是权威。"这一点对任何维护长期项目的团队都成立——过时的"最佳实践"往往比空白更有破坏力。

Git worktree 是 Git 的一项内置功能，允许同一个仓库在文件系统上同时检出多个工作目录，每个目录对应一个独立分支。与克隆多份仓库相比，worktree 共享同一份 .git 对象数据库，节省磁盘空间，同时分支间完全隔离，互不干扰。在并行运行多个 AI 智能体的场景下，这一特性尤为关键：如果两个智能体共享同一个工作目录，它们会同时修改同一批文件，造成冲突甚至静默覆盖。通过为每个智能体分配独立的 worktree 和分支，文件级别的竞争条件被从根本上消除——每个智能体只能"看到"并操作自己分支上的文件副本，合并冲突被推迟到人工审查的 code review 阶段，而不是在生成过程中随机爆发。

最大的教训：指令是建议，机制才能存活

那个钩子还教会了作者整套方法里最重要的一课。他的规则文件要求智能体在搜索代码前先查一个模块索引。但当他翻看自己的会话记录时发现：在 937 次搜索中，智能体只照做了 18 次。

指令本身没错，它只是从未在正确的时刻抵达。一旦把这条同样的规则改造成"在搜索时自动触发的钩子"，它就真正生效了。作者由此总结出一句可以贴在墙上的判断：

"指令是建议，机制才是能在漫长会话中存活下来的东西。"（Instructions are advice, and mechanisms are what survive a long session.）

这对所有用规则文件（如 CLAUDE.md、rules 文件）约束智能体的人是个警醒：写进 prompt 的规则更接近"祈祷"，只有变成会在恰当时机强制触发的机制，才靠得住。

钩子（hook） 在这里指的是 Git 钩子（Git Hooks）或更广义的"事件触发脚本"——一种在特定操作发生时自动执行的程序。Git 原生支持 pre-commit、post-commit、pre-push 等钩子，开发者可以在这些节点插入自定义逻辑。在 AI 编程工作流中，"钩子"被扩展为更广泛的自动拦截机制：当智能体即将执行某类操作（如搜索代码、编辑特定文件），系统自动将相关上下文或约束注入到它的输入流中，而无需依赖智能体主动"记得"去查询。这与 CLAUDE.md 或 rules 文件的本质区别在于：规则文件依赖智能体在任务开始时读取并在整个会话中保持记忆，而钩子在行为发生的瞬间强制介入，不依赖任何形式的记忆持久性。937 次搜索中只有 18 次遵守规则这一数据，揭示了纯粹依赖指令的根本性脆弱：上下文窗口的注意力分布、会话长度增加导致的"遗忘"，都会让规则文件逐渐失效。

并行协作与那些行不通的做法

对于并行工作，作者的规则简洁明确：

• 每个智能体拥有自己独立的 git worktree 和分支；
• 文件清单有重叠的规格，绝不同时运行；
• 任何东西未经他批准都不能进入 main 分支。

他也坦诚列出了对自己行不通的做法，这部分同样有参考价值：

• 一个巨大的上下文文件（context file）；
• 把完整的会话记录喂给下一个会话；
• 让智能体自己决定任务范围；
• 信任与代码在同一会话中写出的测试——因为它们可能共享同一个错误假设。

最后一点尤其值得玩味：同源生成的测试很难成为独立的正确性检验，这是 AI 辅助开发中一个容易被忽视的陷阱。

"同源测试"陷阱 是 AI 辅助开发中一个尚未被广泛讨论的系统性风险。当测试代码与被测代码在同一个会话、由同一个智能体连续生成时，两者可能共享相同的错误前提——智能体对某个边界条件的误解会同时体现在实现和测试中，导致测试"通过"但逻辑仍然错误。这本质上是一种确认偏误的自动化：智能体用自己的理解来验证自己的理解。传统软件工程通过"测试先行（TDD）"或"不同人写测试"来对抗这一问题，其背后的假设是测试者与实现者拥有独立的心智模型。在 AI 编程流水线中，复现这种独立性需要有意识地设计隔离：例如在不同会话中生成测试、使用专门的测试智能体、或在编写实现之前锁定测试用例，而非允许智能体在同一上下文中同时生成两者。

留给社区的开放问题

作者在帖尾抛出一个问题：当一个旧约束不再成立时，你的工作流如何让智能体去重新审视它，而不是把它当成永久规则？

这个问题触及了 AI 编程的深层难题——如何让智能体系统既保有历史记忆，又不被过时的历史所绑架。他的"陈旧标记 + 触发式钩子"是一种答案，但显然还有很大的探索空间。对于任何正在用智能体维护长期代码库的开发者，这套以规格、结果笔记和文件清单为核心的方法，都提供了一份务实的起点。