AI Agent / 系统课时

记录架构决策与已知限制

记录架构决策与已知限制

在 Vibe Coding 项目中,AI 会根据上下文持续生成和修改代码。通过记录架构决策、选择原因和已知限制,可以让后续开发保持一致,避免重复讨论和错误重构。

学习目标

  • 理解架构决策记录的作用和核心内容
  • 掌握记录技术选择、权衡与限制的方法
  • 能建立适合 AI 协作开发的项目知识基线

为什么需要架构决策记录

架构决策记录(ADR)用于保存重要技术选择背后的原因,而不仅是记录最终结果。代码只能体现当前实现,无法说明为什么选择这种方案,以及放弃了哪些替代方案。

在多人协作或长期维护项目中,缺少决策记录会导致 AI 和开发者反复提出已经否决的方案,也容易破坏原有设计边界。

记录哪些关键信息

一份有效的决策记录通常包含以下内容:

  • 背景:当前遇到的问题和约束条件
  • 决策:最终采用的技术方案
  • 原因:选择该方案的收益和权衡
  • 限制:当前方案无法解决的问题
  • 后续:未来可能调整的方向

例如,选择某个数据库时,不仅记录“使用 PostgreSQL”,还应说明原因可能包括事务能力、团队经验和部署环境,同时注明读写规模或迁移成本等限制。

使用结构化记录辅助 AI 协作

项目中可以使用统一格式维护决策文档,例如:

markdown
# ADR-001 使用缓存方案

## 背景
接口响应时间超过目标范围。

## 决策
采用 Redis 缓存热点数据。

## 权衡
优点:降低数据库压力。
缺点:增加缓存一致性处理复杂度。

## 限制
暂不处理跨区域缓存同步。

保持记录简洁比写成完整设计文档更重要,目标是让未来的人和 AI 快速恢复设计上下文。

常见维护误区

不要只记录“做了什么”,忽略“为什么这样做”。没有原因的技术记录无法帮助后续判断,也无法避免重复踩坑。

当实际实现与原始决策发生变化时,应更新记录,而不是保留过期结论继续误导开发过程。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

记录架构决策与已知限制

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通