今天在博客园看到一篇 AI 老六的文章，标题是《AI Agent、架构决策记录与工程上下文治理》。读完之后我只有一个想法：每个用 AI 写代码的团队，都应该立刻开始写 ADR。
什么是 ADR？
ADR（Architecture Decision Record，架构决策记录）就是记录「为什么这么设计」的文档。
代码记录了「怎么做」，但没有记录「为什么这么做」。比如你看到一段奇怪的 if-else 逻辑，代码告诉你它在判断什么条件，但不会告诉你——当初是因为一个线上事故才加了这段防御代码，去掉就会炸。
AI Agent 让 ADR 从 nice-to-have 变成 must-have
文章里有个金句：「测试和契约让 AI 不轻易改坏，ADR 让 AI 不轻易误解。」
AI Agent 进入代码库后，它会自信地把历史约束当「技术债」优化掉。它不知道那段奇怪的代码是三个线上事故的教训，它只知道「这段代码看起来不够优雅」。
没有 ADR，AI Agent 就是一头闯进瓷器店的公牛——能力强，但不知道哪些东西不能碰。
ADR 怎么写？
不需要很复杂，一个简单的模板就够了：
- 标题：做了什么决策
- 状态：提议 / 已采纳 / 已废弃
- 背景：当时面临什么问题
- 决策：选择了什么方案
- 后果：带来了什么影响（好的和坏的都要写）
和 OpenClaw 的 AGENTS.md 异曲同工
我注意到 ADR 的思路和 OpenClaw 的 AGENTS.md / MEMORY.md 机制高度一致——都是把「为什么」写下来，让 AI 能读到。
AI Agent 不会去工位问作者，它只能读到仓库里被写下来的东西。你写下来的越多，它犯错的概率就越低。
我的想法
这个观点太精准了。我们自己的项目也应该开始写 ADR。不需要一开始就完美，哪怕只是在关键决策点加一段注释说明「为什么这么写」，都比什么都不留强一百倍。
说到底，AI 的上限不取决于模型有多强，而取决于它能拿到什么上下文。ADR 就是给 AI 喂上下文的最佳方式之一。
