AI Agent / 系统课时
记录架构决策与已知限制
记录架构决策与已知限制
在 Vibe Coding 项目中,AI 会根据上下文持续生成和修改代码。通过记录架构决策、选择原因和已知限制,可以让后续开发保持一致,避免重复讨论和错误重构。
学习目标
- 理解架构决策记录的作用和核心内容
- 掌握记录技术选择、权衡与限制的方法
- 能建立适合 AI 协作开发的项目知识基线
为什么需要架构决策记录
架构决策记录(ADR)用于保存重要技术选择背后的原因,而不仅是记录最终结果。代码只能体现当前实现,无法说明为什么选择这种方案,以及放弃了哪些替代方案。
在多人协作或长期维护项目中,缺少决策记录会导致 AI 和开发者反复提出已经否决的方案,也容易破坏原有设计边界。
记录哪些关键信息
一份有效的决策记录通常包含以下内容:
- 背景:当前遇到的问题和约束条件
- 决策:最终采用的技术方案
- 原因:选择该方案的收益和权衡
- 限制:当前方案无法解决的问题
- 后续:未来可能调整的方向
例如,选择某个数据库时,不仅记录“使用 PostgreSQL”,还应说明原因可能包括事务能力、团队经验和部署环境,同时注明读写规模或迁移成本等限制。
使用结构化记录辅助 AI 协作
项目中可以使用统一格式维护决策文档,例如:
markdown
# ADR-001 使用缓存方案
## 背景
接口响应时间超过目标范围。
## 决策
采用 Redis 缓存热点数据。
## 权衡
优点:降低数据库压力。
缺点:增加缓存一致性处理复杂度。
## 限制
暂不处理跨区域缓存同步。保持记录简洁比写成完整设计文档更重要,目标是让未来的人和 AI 快速恢复设计上下文。
常见维护误区
不要只记录“做了什么”,忽略“为什么这样做”。没有原因的技术记录无法帮助后续判断,也无法避免重复踩坑。
当实际实现与原始决策发生变化时,应更新记录,而不是保留过期结论继续误导开发过程。
按自己的节奏,确认真正理解。