architecture-decision-record

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture Decision Records

架构决策记录（ADRs）

Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions along with their context and consequences. This skill provides templates, examples, and best practices for creating and maintaining ADRs in your projects.

架构决策记录（ADRs）是轻量化文档，用于记录重要的架构决策及其背景和影响。本技能为在项目中创建和维护ADRs提供模板、示例和最佳实践。

Overview

概述

Making significant technology choices (databases, frameworks, cloud providers)
Designing system architecture or major components
Establishing patterns or conventions for the team
Evaluating trade-offs between multiple approaches
Documenting decisions that will impact future development

做出重大技术选择（数据库、框架、云服务商）
设计系统架构或主要组件
为团队建立模式或规范
评估多种方案之间的权衡
记录将影响未来开发的决策

Why ADRs Matter

ADR的重要性

ADRs serve as architectural memory for your team:

Context Preservation: Capture why decisions were made, not just what was decided
Onboarding: Help new team members understand architectural rationale
Prevent Revisiting: Avoid endless debates about settled decisions
Track Evolution: See how architecture evolved over time
Accountability: Clear ownership and decision timeline

ADRs是团队的架构记忆库：

背景留存：记录决策的原因，而非仅记录决策内容
新人入职：帮助新成员理解架构设计的理由
避免重复讨论：防止对已确定的决策进行无休止的争论
追踪演进：了解架构随时间的演变过程
责任明确：清晰的决策归属和时间线

ADR Format (Nygard Template)

ADR格式（Nygard模板）

Each ADR should follow this structure:

每个ADR应遵循以下结构：

1. Title

1. 标题

Format:

ADR-####: [Decision Title]

Example:

ADR-0001: Adopt Microservices Architecture

格式：

ADR-####: [决策标题]

示例：

ADR-0001: 采用微服务架构

2. Status

2. 状态

Current state of the decision:

Proposed: Under consideration
Accepted: Decision approved and being implemented
Superseded: Replaced by a later decision (reference ADR number)
Deprecated: No longer recommended but not yet replaced
Rejected: Considered but not adopted (document why)

决策的当前状态：

提议中：正在考虑
已接受：决策已批准并正在实施
已取代：被后续决策替代（需引用对应ADR编号）
已弃用：不再推荐但尚未被替代
已拒绝：已考虑但未被采纳（需记录原因）

3. Context

3. 背景

What to include:

Problem statement or opportunity
Business/technical constraints
Stakeholder requirements
Current state of the system
Forces at play (conflicting concerns)

需包含内容：

问题陈述或机遇
业务/技术约束
干系人需求
系统当前状态
影响因素（相互冲突的关注点）

4. Decision

4. 决策

What to include:

The choice being made
Key principles or patterns to follow
What will change as a result
Who is responsible for implementation

Be specific and actionable:

✅ "We will adopt microservices architecture using Node.js with Express"
❌ "We will consider using microservices"

需包含内容：

所做的选择
需遵循的核心原则或模式
决策带来的变更
负责实施的人员

需具体且可执行：

✅ "我们将采用基于Node.js + Express的微服务架构"
❌ "我们会考虑使用微服务"

5. Consequences

5. 影响

What to include:

Positive outcomes (benefits)
Negative outcomes (costs, risks, trade-offs)
Neutral outcomes (things that change but aren't clearly better/worse)

需包含内容：

积极结果（收益）
消极结果（成本、风险、权衡）
中性结果（发生变更但无明显优劣的情况）

6. Alternatives Considered

6. 考虑过的替代方案

Document at least 2 alternatives:

For each alternative, explain:

What it was
Why it was considered
Why it was not chosen

至少记录2种替代方案：

针对每种替代方案，需说明：

方案内容
考虑该方案的原因
未选择该方案的原因

7. References (Optional)

7. 参考资料（可选）

Links to relevant resources:

Meeting notes or discussion threads
Related ADRs
External research or articles
Proof of concept implementations

ADR Lifecycle

ADR生命周期

Proposed → Accepted → [Implemented] → (Eventually) Superseded/Deprecated
          ↓
      Rejected

Proposed → Accepted → [Implemented] → (Eventually) Superseded/Deprecated
          ↓
      Rejected

Best Practices

最佳实践

1. Keep ADRs Immutable

1. 保持ADR不可变

Once accepted, don't edit ADRs. Create new ADRs that supersede old ones.

✅ Create ADR-0015 that supersedes ADR-0003
❌ Update ADR-0003 with new decisions

一旦被接受，请勿编辑ADR。创建新的ADR来取代旧的ADR。

✅ 创建ADR-0015来取代ADR-0003
❌ 更新ADR-0003以包含新决策

2. Write in Present Tense

2. 使用现在时态撰写

ADRs are historical records written as if the decision is being made now.

✅ "We will adopt microservices"
❌ "We adopted microservices"

ADR是历史记录，但撰写时应仿佛正在做出决策。

✅ "我们将采用微服务"
❌ "我们已采用微服务"

3. Focus on 'Why', Not 'How'

3. 聚焦于'为什么'，而非'怎么做'

ADRs capture decisions, not implementation details.

✅ "We chose PostgreSQL for relational consistency"
❌ "Configure PostgreSQL with these specific settings..."

ADR记录决策，而非实现细节。

✅ "我们选择PostgreSQL以保证关系数据一致性"
❌ "按以下特定配置PostgreSQL..."

4. Review ADRs as Team

4. 团队评审ADR

Get input from relevant stakeholders before accepting.

Architects: Technical viability
Developers: Implementation feasibility
Product: Business alignment
DevOps: Operational concerns

在接受决策前获取相关干系人的输入。

架构师：技术可行性
开发人员：实施可行性
产品经理：业务对齐
DevOps：运维关注点

5. Number Sequentially

5. 按顺序编号

Use 4-digit zero-padded numbers: ADR-0001, ADR-0002, etc. Maintain a single sequence even with multiple projects.

使用4位补零数字：ADR-0001、ADR-0002等。即使有多个项目，也需维护单一编号序列。

6. Store in Git

6. 存储在Git中

Keep ADRs in version control alongside code:

Location:
```
/docs/adr/
```
or
```
/architecture/decisions/
```
Format: Markdown for easy reading
Branch: Same branch as implementation

将ADRs与代码一起存储在版本控制系统中：

位置：
```
/docs/adr/
```
或
```
/architecture/decisions/
```
格式：Markdown（便于阅读）
分支：与实现代码使用同一分支

Quick Start Checklist

快速开始检查清单

Option 1: Use Script-Enhanced Generator (Recommended)

选项1：使用脚本增强生成器（推荐）

Run
```
/create-adr [number] [title]
```
to generate ADR with auto-filled context
ADR number, date, and author are auto-populated
Review and fill in decision details
Set Status to "Proposed" and review with team

运行
```
/create-adr [编号] [标题]
```
生成自动填充背景的ADR
ADR编号、日期、作者、总ADR数量将自动填充
评审并填写决策细节
将状态设置为"提议中"并提交团队评审

Option 2: Use Static Template

选项2：使用静态模板

Copy ADR template from
```
assets/adr-template.md
```
Assign next sequential number (check existing ADRs)
Fill in Context: problem, constraints, requirements
Document Decision: what, why, how, who
List Consequences: positive, negative, neutral
Describe at least 2 Alternatives: what, pros/cons, why not chosen
Add References: discussions, research, related ADRs
Set Status to "Proposed"
Review with team
Update Status to "Accepted" after approval
Link ADR in implementation PR
Update Status to "Implemented" after deployment

从
```
assets/adr-template.md
```
复制ADR模板
分配下一个连续编号（需检查现有ADRs）
填写背景：问题、约束、需求
记录决策：内容、原因、方式、负责人
列出影响：积极、消极、中性
描述至少2种替代方案：内容、优缺点、未选择原因
添加参考资料：讨论记录、研究资料、相关ADRs
将状态设置为"提议中"
提交团队评审
批准后将状态更新为"已接受"
在实施PR中链接该ADR
部署后将状态更新为"已实施"

Available Scripts

可用脚本

scripts/create-adr.md
- Dynamic ADR generator with auto-filled context
- Auto-fills: ADR number, date, author, total ADRs count
- Usage:
```
/create-adr [number] [title]
```
- Uses
```
$ARGUMENTS
```
  and
```
!command
```
  for dynamic context
assets/adr-template.md
- Static template for manual use

scripts/create-adr.md
- 动态ADR生成器，可自动填充背景
- 自动填充内容：ADR编号、日期、作者、总ADR数量
- 使用方式：
```
/create-adr [编号] [标题]
```
- 使用
```
$ARGUMENTS
```
  和
```
!command
```
  实现动态背景填充
assets/adr-template.md
- 静态模板，适用于手动创建

Common Pitfalls to Avoid

需避免的常见陷阱

❌ Too Technical: "We'll use Kubernetes with these 50 YAML configs..." ✅ Right Level: "We'll use Kubernetes for container orchestration because..."

❌ Too Vague: "We'll use a better database" ✅ Specific: "We'll use PostgreSQL 15+ for transactional data because..."

❌ No Alternatives: Only documenting the chosen solution ✅ Comparative: Document why alternatives weren't chosen

❌ Missing Consequences: Only listing benefits ✅ Balanced: Honest about costs and trade-offs

❌ No Context: "We decided to use Redis" ✅ Contextual: "Given our 1M+ concurrent users and sub-50ms latency requirement..."

❌ 过于技术化："我们将使用包含50个YAML配置的Kubernetes..." ✅ 合适的粒度："我们将使用Kubernetes进行容器编排，因为..."

❌ 过于模糊："我们将使用更好的数据库" ✅ 具体明确："我们将使用PostgreSQL 15+存储事务数据，因为..."

❌ 未记录替代方案：仅记录所选方案 ✅ 对比分析：记录未选择替代方案的原因

❌ 遗漏影响：仅列出收益 ✅ 全面平衡：坦诚记录成本和权衡

❌ 缺乏背景："我们决定使用Redis" ✅ 背景完整："鉴于我们有100万+并发用户且延迟要求低于50ms..."

Related Skills

Capability Details

能力详情

adr-creation

Keywords: adr, architecture decision, decision record, document decision Solves:

How do I document an architectural decision?
Create an ADR
Architecture decision template

关键词： adr, architecture decision, decision record, document decision 解决问题：

如何记录架构决策？
创建ADR
架构决策模板

adr-best-practices

Keywords: when to write adr, adr lifecycle, adr workflow, adr process, adr review, quantify impact Solves:

When should I write an ADR?
How do I manage ADR lifecycle?
What's the ADR review process?
How to quantify decision impact?
ADR anti-patterns to avoid
Link related ADRs

关键词： when to write adr, adr lifecycle, adr workflow, adr process, adr review, quantify impact 解决问题：

何时应该撰写ADR？
如何管理ADR生命周期？
ADR评审流程是什么？
如何量化决策影响？
需避免的ADR反模式
关联相关ADRs

tradeoff-analysis

Keywords: tradeoff, pros cons, alternatives, comparison, evaluate options Solves:

How do I analyze tradeoffs?
Compare architectural options
Document alternatives considered

关键词： tradeoff, pros cons, alternatives, comparison, evaluate options 解决问题：

如何分析权衡？
对比架构方案
记录考虑过的替代方案

consequences

Keywords: consequence, impact, risk, benefit, outcome Solves:

What are the consequences of this decision?
Document decision impact
Risk and benefit analysis

关键词： consequence, impact, risk, benefit, outcome 解决问题：

该决策的影响是什么？
记录决策影响
风险与收益分析

architecture-decision-record

Original

Translation

Architecture Decision Records

架构决策记录（ADRs）

Overview

概述

Why ADRs Matter

ADR的重要性

ADR Format (Nygard Template)

ADR格式（Nygard模板）

1. Title

1. 标题

2. Status

2. 状态

3. Context

3. 背景

4. Decision

4. 决策

5. Consequences

5. 影响

6. Alternatives Considered

6. 考虑过的替代方案

7. References (Optional)

7. 参考资料（可选）

ADR Lifecycle

ADR生命周期

Best Practices

最佳实践

1. Keep ADRs Immutable

1. 保持ADR不可变

2. Write in Present Tense

2. 使用现在时态撰写

3. Focus on 'Why', Not 'How'

3. 聚焦于'为什么'，而非'怎么做'

4. Review ADRs as Team

4. 团队评审ADR

5. Number Sequentially

5. 按顺序编号

6. Store in Git

6. 存储在Git中

Quick Start Checklist

快速开始检查清单

Option 1: Use Script-Enhanced Generator (Recommended)

选项1：使用脚本增强生成器（推荐）

Option 2: Use Static Template

选项2：使用静态模板

Available Scripts

可用脚本

Common Pitfalls to Avoid

需避免的常见陷阱

Related Skills

相关技能

Capability Details

能力详情

adr-creation

adr-creation

adr-best-practices

adr-best-practices

tradeoff-analysis

tradeoff-analysis

consequences

consequences