用于创建、维护和管理架构决策记录(ADR)的综合模式,捕获重要技术决策背后的上下文和原理。
技能概述
architecture-decision-records 技能提供了创建、维护和管理架构决策记录的综合模式。ADR捕获重要技术决策背后的上下文和原理,帮助团队理解为什么做出特定决策,以及这些决策的后果。该技能提供多种ADR模板、管理工具和最佳实践。
下载地址:antigravity-awesome-skills/skills/architecture-decision-records at main · sickn33/antigravity-awesome-skills · GitHub
触发条件
使用此技能的情况:
- 做出重要的架构决策
- 记录技术选择
- 记录设计权衡
- 帮助新团队成员入职
- 审查历史决策
- 建立决策流程
核心概念
什么是ADR?
架构决策记录捕获:
- 上下文(Context): 为什么我们需要做出决策
- 决策(Decision): 我们决定了什么
- 后果(Consequences): 结果会发生什么
何时编写ADR
| 编写ADR | 跳过ADR |
|---|---|
| 新框架采用 | 小版本升级 |
| 数据库技术选择 | Bug修复 |
| API设计模式 | 实现细节 |
| 安全架构 | 例行维护 |
| 集成模式 | 配置更改 |
ADR生命周期
Proposed → Accepted → Deprecated → Superseded ↓ Rejected
ADR模板
模板1: 标准ADR(MADR格式)
包含完整的上下文、决策驱动因素、考虑的选项、决策、理由、后果、实施说明和相关决策。
模板2: 轻量级ADR
适用于较小的决策,包含状态、日期、决策者、上下文、决策和后果。
模板3: Y-Statement格式
简洁的一句话格式,适合快速记录决策。
模板4: 废弃ADR
用于记录废弃决策和迁移计划。
模板5: RFC风格
适用于需要广泛讨论的重大决策。
ADR管理
目录结构
docs/
├── adr/
│ ├── README.md # 索引和指南
│ ├── template.md # 团队的ADR模板
│ ├── 0001-use-postgresql.md
│ ├── 0002-caching-strategy.md
│ └── ...
自动化工具(adr-tools)
# 安装adr-tools
brew install adr-tools# 初始化ADR目录
adr init docs/adr# 创建新ADR
adr new "Use PostgreSQL as Primary Database"# 替代ADR
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"# 生成目录
adr generate toc > docs/adr/README.md
最佳实践
应该做的:
- 尽早编写ADR- 在实施开始之前
- 保持简短- 最多1-2页
- 诚实面对权衡- 包括真实的缺点
- 链接相关决策- 构建决策图
- 更新状态- 被替代时废弃
不应该做的:
- 不要更改已接受的ADR- 编写新的来替代
- 不要跳过上下文- 未来的读者需要背景
- 不要隐藏失败- 被拒绝的决策很有价值
- 不要模糊- 具体的决策,具体的后果
- 不要忘记实施- 没有行动的ADR是浪费
审查流程
提交前
- ☐ 上下文清晰解释问题
- ☐ 考虑了所有可行选项
- ☐ 优缺点平衡且诚实
- ☐ 记录了后果(正面和负面)
- ☐ 链接了相关ADR
审查期间
- ☐ 至少2名高级工程师审查
- ☐ 咨询了受影响的团队
- ☐ 考虑了安全影响
- ☐ 记录了成本影响
- ☐ 评估了可逆性
接受后
- ☐ 更新ADR索引
- ☐ 通知团队
- ☐ 创建实施工单
- ☐ 更新相关文档
使用限制
- 仅当任务明显符合上述描述的范围时才使用此技能
- 不要将输出作为环境特定验证、测试或专家审查的替代品
- 如果缺少所需的输入、权限、安全边界或成功标准,请停止并要求澄清
