把 CLAUDE.md 当作迁移脚本而非 README，避免 AI 代理基于过时信息执行错误操作

上周我打开 CLAUDE.md，让一个智能体去修复一个支付漏洞，结果第一部分描述的是我们在三个冲刺前就已经重构掉的一个文件夹布局。该部分一直指向的 api/ 目录现在已经是 packages/payments/ 了。智能体没有注意到这一点。它基于旧路径制定了计划，找不到文件后，开始“调整”测试以匹配它认为代码应该执行的操作。

这就是那些炫耀他们光鲜亮丽的智能体设置的人不会告诉你的故障模式。指令文件原本是为人类编写的 README，阅读时带有一点健康的怀疑态度。而现在它们变成了运行时输入，被智能体视为绝对真理。人类读到过时的 README 时会想：“嗯，这看起来不太对。”而智能体会想：“这是合同。”

为什么 README 腐烂曾经是可以容忍的

人类会交叉验证。你阅读入门部分，尝试命令，失败了，然后耸耸肩去看实际的 Makefile。你不会因为 README 有问题而提交 bug；你只会记下一笔待办事项，打算以后修复，然后继续前进。README 有 20% 的错误只是轻微的尴尬，而不是服务中断。

智能体不会交叉验证。它将指令文件视为规范。如果文件说路由位于 api/routes.ts，智能体会很高兴地在 packages/payments/src/routes.ts 中的真实路由旁边创建一个新的 api/routes.ts，然后困惑为什么没有任何地方导入它。智能体并不愚蠢。它正在完全按照你告诉它的去做，使用的是它拥有的最佳信息。

保持这些文件诚实的四个习惯

1. 像审查任何代码变更一样审查 CLAUDE.md 的差异。这些文件腐烂的最常见方式是智能体自己在提交功能的同时“更新文档”。这不是文档；这是智能体重写合同以使其当前任务更容易。将指令文件的更改视为独立的 PR，并问自己：这是在描述系统，还是在描述智能体的计划？

1. 重大重构后进行冒烟检查。当你重命名包、移动目录或更改环境变量时，以重新运行构建的方式重新阅读指令文件。最便宜的方法是：打开它，查找路径和命令，并确认它们仍然存在。你不需要为此使用 linter；你需要的是不要假装文件会自动更新。

1. 永远不要将合同的快照粘贴到文件中。这是我见过最多的情况。有人将三个示例请求/响应形状复制到 CLAUDE.md 中，以便智能体“拥有上下文”。两次部署后，真实的 API 返回了一个新字段，智能体针对粘贴的快照生成代码，于是你得到了漂移，表现为生产环境中的 bug，而不是红色的 CI 作业。如果智能体需要知道 API 合同，让它指向实时规范文件并读取当前版本。粘贴快照保证智能体会信任过时的内容。

1. 当智能体的计划与文件矛盾时，这是一个信号。如果智能体提出的更改与 CLAUDE.md 所说的不匹配，不要自动信任智能体对代码库的解释。大多数时候，说谎的是文件。代码是绝对真理；指令文件是给未来协作者的备注。就这样对待它。

Powerduck 的位置所在

这一原则具有普遍性：任何粘贴到上下文文件中的“真相来源”最终都会发生漂移。当该来源是 API 合同时，将其作为智能体每次运行都重新阅读的本地实时规范，比将其作为 markdown 快照重要得多。这正是我们将 Powerduck 构建为本地优先 OpenAPI 工作室的全部原因：规范保持在磁盘上的文件中，智能体读取当前版本，markdown 根本没有机会撒谎。

心智模型

CLAUDE.md、AGENTS.md、.cursorrules——这些已不再是文档。它们是写成英文格式的运行时配置，如果你从不查看它们，其腐坏的速度与任何配置文件一样快。审查变更差异，在重构后进行冒烟测试，并且永远不要粘贴一份代理应实时读取的契约快照。这样你的代理会更有信心，而你的生产系统也会更加正确。