AI Agent 一次能改十几个文件,但提交后通常只剩 commit message 和 diff。它能说明“改了什么”,却很难回答:为什么选这个方案?模型哪里没把握?现在重跑,会不会得到相同结果?
Git 记录代码事实,不记录完整决策。ADRs for AI 试图补上这段空白:把模型的决策依据写进 Git,并用 ORRCF 要求 Agent 暴露疑虑。
真正的缺口不是代码,而是决策记录
假设我让 Agent 把同步任务改成异步队列。
最终 diff 可能只有几行:新增 producer、consumer 和 retry policy,再删掉原来的阻塞调用。
代码审查能检查竞态、消息丢失、重复消费。但审查者看不到完整决策链:
- 为什么不用 Redis Streams,而不是 Kafka?
- 为什么保留现有数据库作为 source of truth?
- 是否评估过任务延迟和运维复杂度?
- 出现什么现象,说明这次选择错了?
Agent 参与后,这些问题更容易被压缩成一句“已按最佳实践优化”。
普通 ADR 原本就是为这类问题准备的。它是一种轻量决策记录。Nygard 的经典形式通常包括背景、选项、决定和后果。团队留下为什么选择某条技术路线。后来的人即使没参加讨论,也能理解代码为何长成现在这样。
ADRs for AI 做了两个调整。
第一,把 ADR 扩展到人机协作场景。AI Agent 可以是决策提案的作者,也可以读取后续决策记录。
第二,用 Git 保存这些 Architectural Deliberation Records。记录不再随聊天窗口消失,而是进入版本控制,和代码一起评审、提交、回滚。
自然语言解释只留在聊天窗口里,最多算日志。放进 Git 后,它才可能成为可协作的工程上下文。
ORRCF:让模型先交出五份作业
ADRs for AI 使用 ORRCF 组织模型给出的决策提案:
- Options:有哪些可行选项,包括维持现状。
- Recommendation:模型推荐哪一个。
- Rationale:为什么推荐它,放弃了什么。
- Confidence:模型对推荐结果的信心。
- Falsifier:什么证据会证明这个推荐不成立。
它看起来像解释模板,但不只是为了让输出更完整。
ORRCF 要求模型暴露疑虑,并把建议交给人类批准或覆盖。模型不能提交代码后只附一段礼貌总结。它需要先交出可供审查的决策提案。
例如,异步队列任务可能这样写:
## Options
1. 保留同步调用
2. 使用 Redis Streams
3. 使用 Kafka
## Recommendation
使用 Redis Streams。
## Rationale
当前吞吐量不需要 Kafka 的分区和运维成本。
Redis Streams 已提供 consumer group、确认机制和消息保留。
## Confidence
中高。主要不确定性是现有重试逻辑迁移后的幂等性。
## Falsifier
如果压测中 consumer lag 持续增长,或重投导致重复处理,
则当前方案不成立,应重新评估 Kafka。
人类可以批准,也可以覆盖推荐。覆盖原因也可以进入 ADR。下一次 Agent 不只读取代码,还能读取团队已经做过的取舍。
这能形成一种可持续的 AI 编程脚手架。它保存本次建议,也保存团队对建议的修改。后续任务可以把已批准、已拒绝和附带条件的方案当成上下文。
这不等于要求每个 commit 写一篇长文。更适合给高风险、高成本,或难以凭 diff 理解的改动加一道决策检查。
ADR 放进 Git,才是可协作的上下文
很多 Agent 工具已经擅长检索代码。先找相关文件,再读符号定义、搜索调用方,然后修改实现。
ADR 补的是另一层检索:哪些选择已经讨论过,哪些边界条件已经踩过坑。
假设第一次迁移数据库时,团队因为低流量选择了 SQLite。后来流量变化,又决定换 PostgreSQL。ADR 里应该有两次记录:
- 第一次为什么选 SQLite。
- 第二次为什么迁移 PostgreSQL。
- 哪些假设已经失效。
- 哪些限制仍然保留。
只读当前代码,后续 Agent 可能把旧方案当成偶然实现。读取 ADR,它至少有机会看到当时的约束。
Git 还带来三个协作特性。
第一,决策和实现可以一起审查。评审者能对照代码,检查模型是否兑现承诺。
第二,决策可以回滚。代码改错了,可以回滚 diff。架构选择错了,也可以通过新 ADR 明确替代,而不是抹掉历史。
第三,责任边界更清楚。人类批准或覆盖的是一份显式提案,而不是在模糊的“模型已经处理”里承担结果。
不过,ADR 不该替代测试、代码审查或架构讨论。它只是让这些活动多一个共同参照物。
反共识:更多记录未必带来更多监督
把结构化格式接进 Agent 流程,很容易得到一个好看的结果:每次任务多出 Options、Rationale、Confidence 和 Falsifier。
这也可能只是形式主义。
Confidence 不可靠。模型给出“0.8”,不代表结果有 80% 的正确概率。训练数据里的措辞习惯、提示模板,甚至任务难度,都可能改变这个数字。它最多是一个需要解释的信号。
Falsifier 同样不等于测试。
模型写下“如果 consumer lag 持续增长就说明方案失败”,不代表它已经编写压测,也不代表团队知道增长阈值是多少。一个永远不会被执行的证伪条件,只是把不确定性改写成更正式的语言。
因此,ADR 的质量要回到工程证据上:
- Rationale 是否引用真实约束,而不是泛泛的最佳实践?
- Recommendation 是否和实际代码变更一致?
- Falsifier 是否对应可执行测试或监控指标?
- 人类覆盖模型后,是否记录了覆盖理由?
- 后续 Agent 是否真的读取并使用了历史 ADR?
还有一个更隐蔽的问题:记录可能制造监督幻觉。
文档越完整,评审者越容易觉得决策已经妥善处理。可如果 ORRCF 是任务结束前自动生成的模板,它可能只在复述代码,而不是解释代码。
真正有用的 ADR 应该允许人发现不一致。
比如,模型推荐 Redis,理由是避免数据库锁竞争;实际代码却在事务中更新状态表。人一看就知道,提案和实现之间出现了偏差。
这比“模型很自信地说自己完成了任务”更有价值。
所以我会把 ADRs for AI 看成审计接口,而不是质量保证接口。它让 AI 的建议更容易被检查,但不自动让建议更正确。
原始项目说明来自 ADRs for AI 项目网站 及其 Hacker News 讨论。项目展示了 Architectural Deliberation Records、ORRCF 五项格式、人类批准或覆盖机制,以及基于 Git 的可持续 AI 编程脚手架。
编辑思考
ADRs for AI 的价值不在“记录 AI”,而在把模型建议变成可审计的工程对象。代码回答系统现在是什么,ADR 回答为什么变成这样。两者进入同一个 Git 历史后,后来的工程师和 Agent 才有机会继承决策上下文。
我的判断是,ORRCF 的短期价值主要在审查界面,不在自治能力。它未必让 Agent 更聪明,却能让偏差更早暴露:推荐和代码不一致,证伪条件没有对应测试,人类覆盖也没留下理由。团队若只把它当自动会议纪要,它很快会变成文档负担。
这和过去的 AI 编程工具不同。以前主要是补全代码、补测试;现在 Agent 开始做跨文件修改,决策跨度更大。素材没有给出生产环境效果、项目规模或错误率变化,成熟度仍需验证。该测的不是 ADR 多漂亮,而是半年后,新 Agent 能否少走一次旧弯路。