architecture-decision-record

架构决策记录

第 1 步：了解决策

询问用户：

你需要记录哪项架构决策？请提供：

• 决策标题（例如：“从 SQS 切换到 EventBridge 进行事件路由”）
• 背景——你要解决什么问题，或要进行什么变更？
• 考虑过的选项（至少 2 个）——或者让我提出替代方案

如果用户已经描述了决策，请直接继续。

重要：如果你正在处理代码库，务必先分析代码，以实际实现为依据编写 ADR。如果没有可用代码，请根据口头描述继续，但要将实现相关部分标记为“需对照代码验证”。

第 2 步：梳理当前状态

分析代码库，了解目前已有的内容。

你必须检查：

• 与该决策相关的基础设施即代码（CDK、CloudFormation、Terraform）
• 实现该决策或将受其影响的应用代码
• 配置文件、依赖清单、环境变量
• 代码库中现有的模式和约定
• 验证当前行为的测试

针对决策背景，你必须记录：

• 当前实现：目前已有的内容，包括文件路径和行号
• 受影响的代码：每个选项需要修改的所有文件
• 集成点：每个选项必须满足的接口、API、契约
• 现有代码的约束：限制选项的语言、框架、模式
• 依赖项：依赖当前实现的其他服务或组件

你必须指出：

• 每个选项必须修改的代码（量化说明：“选项 A 涉及 3 个文件，选项 B 涉及 12 个文件”）
• 现有依赖带来的兼容性约束
• 已确立且决策应遵循的模式（或说明打破这些模式的理由）
• 变更影响有状态资源时的数据迁移要求

第 3 步：基于证据评估选项

针对每个选项，提供具体分析：

实现工作量——不要使用 T 恤尺码，要给出具体信息：

• 需要修改的文件（列出文件）
• 引入的新依赖项
• 所需的迁移步骤
• 选项之间的预计时间差异（例如：“根据迁移复杂度，选项 A 约需 2 周，选项 B 约需 6 周”）

WA 支柱的影响——仅评估相关支柱，并说明具体理由：

支柱	选项 A	选项 B
{相关支柱}	{影响 + 原因 + 来自代码的证据}	{影响 + 原因}

使用：✅ 正面 | ➖ 中性 | ⚠️ 权衡 | ❌ 负面

如果某些支柱对两个选项确实都没有影响，请跳过，不要凑数。

对于每项非中性评估，你必须说明：

• 该选项产生此影响的原因（以代码的实际情况为依据）
• 带来收益或风险的具体 AWS 服务、模式或代码路径
• 这是暂时的权衡（迁移带来的痛点）还是永久性的权衡（架构约束）

运营影响——团队需要做出哪些改变：

• 监控/告警所需的变更
• 操作手册的更新
• 值班方面的影响
• 部署策略的变更

---STOP--- 检查点：选项分析已完成——可以提出建议

已针对“{decision title}”评估 {N} 个选项。比较了每个选项的实现工作量（受影响的文件、迁移步骤）、WA 支柱影响和运营影响。

是否继续识别权衡、评估风险，并产出包含建议的最终 ADR？

在用户明确确认之前，不要继续。

---

第 4 步：识别权衡与风险

对于推荐选项，MUST 明确说明：

• 你能获得什么——提供证据，说明这对当前工作负载为何重要（而非泛泛而谈的好处）
• 你要放弃什么——诚实评估在当前约束下，这是否可以接受
• 可能出现什么问题——说明实施期间或之后的具体风险，以及缓解措施
• 可逆性——撤销有多困难？有哪些退路？哪些数据是单向的？

对于被否决的选项，MUST 解释：

• 主要否决理由（一句清晰的话）
• 在哪些未来条件下它会成为更好的选择（具体触发条件）

第 5 步：生成 ADR

# ADR-{number}: {Decision Title}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-X}

## Date
{YYYY-MM-DD}

## Context

### Problem Statement
{What problem? Why now? What triggered this decision?}

### Current State
{What exists today — with file paths and code references}
- `{file:line}` — {what it does and why it's relevant}
- `{file:line}` — {what it does}

### Constraints
{Derived from codebase analysis — not assumptions}
- {constraint} — Evidence: `{file:line}`

### Decision Drivers
{Ordered by priority — what matters most}
1. {driver} — {why, grounded in business or code reality}
2. {driver} — {why}

## Decision
{One clear statement of what we're doing.}

## Options Evaluated

### Option 1: {name} ← Chosen
- **How it works**: {description}
- **Pros**: {benefits grounded in this codebase's reality}
- **Cons**: {drawbacks with honest assessment}
- **Files affected**: {list with paths}
- **Migration**: {what needs to happen to get from current state to this}
- **Effort**: {specific estimate with basis}

### Option 2: {name} — Rejected
- **How it works**: {description}
- **Pros**: {benefits}
- **Cons**: {primary reason for rejection}
- **Files affected**: {list}
- **Effort**: {estimate}
- **Would choose this if**: {specific future condition}

## Well-Architected Impact

| Pillar | Impact | Evidence |
|--------|--------|----------|
| {pillar} | {✅/⚠️/❌} | {specific reasoning tied to code/architecture} |
{Only pillars with non-neutral impact}

## Trade-offs

### What We Gain
- {benefit} — matters because {evidence from this workload}

### What We Accept
- {drawback} — acceptable because {justification}

### Risks
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| {specific risk} | {Low/Med/High} | {what breaks} | {concrete action} |

## Implementation

### Migration Path
1. {step} — affects `{file}`
2. {step} — affects `{file}`
3. {step} — verify with {test/metric}

### Rollback Plan
{How to undo if this goes wrong — specific steps, not "revert the change"}

### Verification
- {How to confirm the decision is working as expected}
- {Metric or test that validates success}

## Review Triggers
{Specific, measurable conditions — not "if things change"}
- {metric} exceeds {threshold} (e.g., "p99 latency > 500ms")
- {event} occurs (e.g., "team grows beyond 8 engineers")
- {time} passes (e.g., "re-evaluate after 6 months of production data")

第 6 步：修订现有 ADR

当用户要求修订或更新 ADR 时：

MUST：

• 阅读现有 ADR 文件
• 分析自 ADR 编写以来代码库发生了哪些变化（git log、文件差异）
• 判断该决策是否仍然成立，或是否已触发复审条件
• 如果要取代原 ADR：创建新的 ADR，引用旧 ADR 并说明发生了哪些变化

第 7 步：提供后续步骤

生成 ADR 后，提供以下选项：

你希望我：

• 为所选方案生成实现代码？
• 创建迁移脚本或分步 PR 计划？
• 编写用于验证新架构的测试？
• 为相关决策起草后续 ADR？
• 检查现有 ADR 的复审条件是否已触发？

校准指南

• ADR 是决策记录，不是推销文案——记录真实的权衡，包括不那么好听的部分
• 代码证据为决策提供依据——“影响 3 个文件”比“工作量较小”更有说服力
• 带有具体阈值的复审条件，能让 ADR 在 6 个月后仍然有用
• 如果没有可用代码，ADR 仍有价值，但要将实现部分标记为待验证
• 迁移路径是 ADR 中最具可操作性的部分——要具体到足以让他人照着执行
• 记录可逆性至关重要——不可逆的决策值得分析更多选项
• 不要为了填充 WA 支柱表格而凑内容——只纳入确实有明显影响的支柱