记录架构决策,防止 AI 反复改错
文章以 AI 多次建议将 Redis 队列改回数据库为例,说明代码和旧配置无法完整传达历史约束。它主张通过架构决策记录保留选择原因,避免开发者与 AI 重复踩坑。
原文暂未完整获取,基于公开信息的快读
AI 助手连续建议把 Redis 队列改回数据库,理由是配置更简单,旧 .env.example 里也留着对应设置。但作者团队当初迁走,恰恰是因为数据库队列曾引发死锁、拖住结账流程。作者借这个案例提出:需要留在仓库里的,不只是代码,还有当初为什么这样写。
目前能确认什么
据作者描述,同一个客户项目里,AI 助手在两个月内三次提出类似修改。触发任务都是加速慢作业,但当年迁移到 Redis 的原因,只存在于 Slack 讨论和一位工程师的记忆中,当前团队已经没人记得。
代码能展示当前实现,却未必能解释历史约束。
作者推荐用架构决策记录(Architecture Decision Record,ADR)补上这层信息:每份 Markdown 记录一个决策,写清背景、选择、后果和状态,放在仓库的 docs/decisions/ 中,再通过 AGENTS.md 等项目规则文件引导 AI 读取。
其中一个关键字段是「何时重新评估」。它让后来的人知道哪些条件变化后可以调整方案。决策被替代时,作者主张新增记录并关联旧记录,保留演变过程,而不是直接覆盖原来的理由。
我的判断
这个案例对程序员最直接的提醒是:让 AI 优化某段代码时,任务描述里只有「更快」「更简单」,可能不足以表达真正的边界。一次故障换来的设计约束,如果没有进入可读取的上下文,就容易在重构时被再次推翻。
ADR 适合优先记录那些看起来麻烦、却有明确历史原因的选择,例如队列方案、金额表示和依赖锁定。记录里既要解释保留它的代价,也要写清允许改变它的条件,否则旧决策也可能阻碍合理调整。
写下决策,只是让 AI 有机会读懂它。
节选末尾没有提供完整的行为变化或效果验证,不能据此断言错误重构已经减少。规则文件是否被读取、相关 ADR 是否进入本次上下文,以及 CI 如何检查重大变更引用了决策记录,仍需完整原文或对应工具文档确认。