用途
架构决策记录（ADR，Architecture Decision Record）是一种轻量级方法，用于记录重要的架构决策及其上下文、权衡与理由。该技能源自 Michael Nygard 的 ADR 模式，并融合了 Google、Meta、字节跳动等公司的设计文档文化。
其核心理念是：每个架构决策都是一次下注。ADR 记录下注内容、理由以及预期回报，以便未来的团队了解当初为什么做出该选择。
为什么 ADR 重要
没有 ADR 时：
- 「为什么我们用 MongoDB 而不是 Postgres？」——没人知道
- 新员工反复进行旧的争论
- 权衡被遗忘——只剩结果可见
- 糟糕的决策无法重新审视，因为不知道当初为何做出
有了 ADR 时：
- 每个决策都有上下文——未来开发者理解「为什么」
- 决策质量提升——写下来迫使思考更清晰
- 新员工通过阅读 ADR 即可跟上进度，无需翻找 Slack 历史
- 重新审视决策更容易——「上下文变了吗？」
主要能力
ADR 生命周期
Proposed → Accepted → Superseded → Deprecated
- Proposed：决策已建议但尚未达成一致
- Accepted：团队同意，开始实施
- Superseded：新的 ADR 取代此决策（链接到新 ADR）
- Deprecated：决策不再相关（系统已变化）
ADR 模板
标准模板包含以下部分：
# ADR-NNN: [标题——简短、描述性]
- **Status**: [Proposed | Accepted | Superseded | Deprecated]
- **Date**: YYYY-MM-DD
- **Author**: [姓名]
- **Supersedes**: ADR-NNN（如适用）
- **Superseded by**: ADR-NNN（如适用）
## Context
什么上下文使此决策成为必要？包括：
- 正在解决的具体问题
- 业务约束（时间、成本、资源）
- 技术约束（现有技术栈、团队专长）
- 相关背景或先例
## Decision
我们在决定什么？清晰陈述决策。
「我们将使用 [技术/方法] 用于 [目的]，因为 [主要理由]。」
## Options Considered
### Option A: [名称]（推荐）
**Description**: 方法的简要说明。
**Pros:**
- 优点 1
**Cons:**
- 缺点 1
### Option B: [名称]
（同上结构）
### Option C: [名称]（什么都不做 / 基线）
（同上结构）
## Trade-off Analysis
使用清晰的对比表展示决策理由：
| Criteria | Option A | Option B | Option C |
|--------------------|----------|----------|----------|
| Performance | High | Medium | Low |
| Maintainability | High | High | Medium |
| Learning curve | Medium | Low | None |
| Operational cost | Low | High | Medium |
| Time to implement | 2 weeks | 1 week | 0 |
| Risk | Low | Medium | High |
## Consequences
**Positive:**
- 什么变得更容易/更好？
**Negative:**
- 什么变得更难？接受了哪些权衡？
**Neutral:**
- 我们的运作方式发生了什么变化？
## Validation
如何验证此决策是正确的？
- [ ] Metric to track: [例如 p99 延迟、错误率、开发速度]
- [ ] Review date: YYYY-MM-DD（决策后 3-6 个月）
- [ ] Success criteria: [例如「p99 < 200ms」]
## Related Decisions
- ADR-NNN: [相关决策标题]
ADR 快速模板（2 分钟版）
适用于仍需记录的小型决策：
# ADR-NNN: [标题]
- **Status**: Accepted
- **Date**: YYYY-MM-DD
## Context
[1-2 句话]
## Decision
使用 [X] 用于 [Y]。
## Rationale
[1-2 句话说明关键权衡]
## Consequences
[因此发生了什么变化]
示例
技能中提供了两个示例：
- 示例 1（完整 ADR）：ADR-017 订单服务使用 PostgreSQL 而非 MongoDB，包含详细的 Context、Decision、三个备选方案（PostgreSQL / MongoDB / CockroachDB）、对比分析表、Consequences 与 Validation。
- 示例 2（快速 ADR）：ADR-009 使用 Biome 替代 ESLint+Prettier，包含 Context、Decision、Rationale 与 Consequences。
使用方式
ADR 文件组织
docs/adr/
├── README.md # 所有 ADR 的索引及状态表
├── ADR-001-initial-architecture.md
├── ADR-002-use-postgres-for-orders.md
├── ADR-003-use-redis-for-caching.md
├── ADR-004-supersede-003-use-memcached.md
└── ADR-005-microservices-vs-monolith.md
README.md 索引示例：
# Architecture Decision Records
| ADR | Title | Status | Date | Author |
|-----|-------|--------|------|--------|
| 001 | Initial Architecture | Accepted | 2026-01-15 | Alice |
| 002 | Use PostgreSQL for Orders | Accepted | 2026-02-01 | Bob |
| 003 | Use Redis for Caching | Superseded | 2026-02-15 | Carol |
| 004 | Supersede 003: Use Memcached | Accepted | 2026-03-01 | Carol |
| 005 | Microservices vs Monolith | Proposed | 2026-04-01 | Alice |
何时写 ADR
应当写 ADR 的情况：
- 在两种以上技术之间做选择
- 做出具有长期影响的决策
- 更改现有架构决策
- 向团队引入新模式/范式
- 决策涉及成本、风险或依赖影响
不应写 ADR 的情况：
- 选择代码风格（那是风格指南）
- 做出微不足道的实现细节决定
- 需要在 5 分钟内做出决策（可以稍后补写）
- 决策是临时的且会被撤销
ADR 评审流程
- 作者起草 ADR（Proposed 状态），可选地在 slack #architecture 频道分享
- 团队评审（异步——至少 48 小时），重点关注：选项是否公平？权衡是否真实？
- 架构同步会（可选——如有争议），讨论未解决的分歧并达成最终决策
- 状态 → Accepted，除非出现新信息，决策锁定
- 按 ADR 实施
- 3-6 个月后评审，判断决策是否正确，更新或取代
适用场景
适合需要记录架构决策背景与理由的软件团队，尤其是涉及技术选型、模式引入、跨模块架构变更等需要长期留存决策依据的项目。也适合新成员较多的团队用于知识传承。
限制
资料未提供该技能的具体工具形态、安装方式、平台支持范围与收费信息。