architecture-decision-records

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture Decision Records

架构决策记录（ADR）

Capture architectural decisions as they happen during coding sessions. Instead of decisions living only in Slack threads, PR comments, or someone's memory, this skill produces structured ADR documents that live alongside the code.

在编码会话进行过程中实时捕获架构决策。让决策不再只存在于Slack线程、PR评论或某个人的记忆中，本技能会生成结构化的ADR文档，与代码一同留存。

When to Activate

激活时机

User explicitly says "let's record this decision" or "ADR this"
User chooses between significant alternatives (framework, library, pattern, database, API design)
User says "we decided to..." or "the reason we're doing X instead of Y is..."
User asks "why did we choose X?" (read existing ADRs)
During planning phases when architectural trade-offs are discussed

用户明确说出"我们记录这个决策吧"或"生成ADR"
用户在重要备选方案间做选择（框架、库、模式、数据库、API设计）
用户提到"我们决定……"或"我们选择X而非Y的原因是……"
用户询问"我们为什么选择X？"（读取现有ADR）
规划阶段讨论架构取舍时

ADR Format

ADR格式

Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development:

markdown

undefined

采用Michael Nygard提出的轻量ADR格式，并适配AI辅助开发场景：

markdown

undefined

ADR-NNNN: [Decision Title]

ADR-NNNN: [决策标题]

Date: YYYY-MM-DD Status: proposed | accepted | deprecated | superseded by ADR-NNNN Deciders: [who was involved]

日期: YYYY-MM-DD 状态: proposed | accepted | deprecated | superseded by ADR-NNNN 决策者: [参与人员]

Context

背景

What is the issue that we're seeing that is motivating this decision or change?

[2-5 sentences describing the situation, constraints, and forces at play]

当前遇到了什么问题，促使我们做出这个决策或变更？

[2-5句话描述当前场景、约束条件及影响因素]

Decision

决策

What is the change that we're proposing and/or doing?

[1-3 sentences stating the decision clearly]

我们提议或正在执行的变更是什么？

[1-3句话清晰说明决策内容]

Alternatives Considered

备选方案考量

Alternative 1: [Name]

方案1: [名称]

Pros: [benefits]
Cons: [drawbacks]
Why not: [specific reason this was rejected]

优势: [好处]
劣势: [弊端]
未选原因: [具体拒绝理由]

Alternative 2: [Name]

方案2: [名称]

Pros: [benefits]
Cons: [drawbacks]
Why not: [specific reason this was rejected]

优势: [好处]
劣势: [弊端]
未选原因: [具体拒绝理由]

Consequences

影响

What becomes easier or more difficult to do because of this change?

这个变更会让哪些操作变简单，哪些变困难？

Positive

积极影响

[benefit 1]
[benefit 2]

[好处1]
[好处2]

Negative

消极影响

[trade-off 1]
[trade-off 2]

[取舍1]
[取舍2]

Risks

风险

[risk and mitigation]

undefined

[风险及缓解措施]

undefined

Workflow

工作流程

Capturing a New ADR

捕获新ADR

When a decision moment is detected:

Initialize (first time only) — if
```
docs/adr/
```
does not exist, ask the user for confirmation before creating the directory, a
```
README.md
```
seeded with the index table header (see ADR Index Format below), and a blank
```
template.md
```
for manual use. Do not create files without explicit consent.
Identify the decision — extract the core architectural choice being made
Gather context — what problem prompted this? What constraints exist?
Document alternatives — what other options were considered? Why were they rejected?
State consequences — what are the trade-offs? What becomes easier/harder?
Assign a number — scan existing ADRs in
```
docs/adr/
```
and increment
Confirm and write — present the draft ADR to the user for review. Only write to
```
docs/adr/NNNN-decision-title.md
```
after explicit approval. If the user declines, discard the draft without writing any files.
Update the index — append to
```
docs/adr/README.md
```

当检测到决策时刻时：

初始化（仅首次） — 若
```
docs/adr/
```
目录不存在，需先征得用户同意，再创建该目录、包含索引表头的
```
README.md
```
（见下方ADR索引格式），以及供手动使用的空白
```
template.md
```
。未经明确同意不得创建文件。
识别决策 — 提取核心架构选择内容
收集背景 — 问题的触发原因是什么？存在哪些约束？
记录备选方案 — 还考虑了哪些其他选项？未选的原因是什么？
说明影响 — 有哪些取舍？哪些操作会变简单/困难？
分配编号 — 扫描
```
docs/adr/
```
中现有ADR，编号递增
确认并写入 — 将ADR草稿呈现给用户审核。仅在获得明确批准后，写入
```
docs/adr/NNNN-decision-title.md
```
。若用户拒绝，则丢弃草稿，不创建任何文件。
更新索引 — 将新条目追加到
```
docs/adr/README.md
```

Reading Existing ADRs

读取现有ADR

When a user asks "why did we choose X?":

Check if
```
docs/adr/
```
exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?"
If it exists, scan
```
docs/adr/README.md
```
index for relevant entries
Read matching ADR files and present the Context and Decision sections
If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"

当用户询问"我们为什么选择X？"时：

检查
```
docs/adr/
```
是否存在 — 若不存在，回复："本项目未找到ADR记录。是否要开始记录架构决策？"
若存在，扫描
```
docs/adr/README.md
```
索引查找相关条目
读取匹配的ADR文件，展示背景和决策部分
若未找到匹配项，回复："未找到该决策的ADR记录。是否要现在创建一个？"

ADR Directory Structure

ADR目录结构

docs/
└── adr/
    ├── README.md              ← index of all ADRs
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← blank template for manual use

docs/
└── adr/
    ├── README.md              ← 所有ADR的索引
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← 供手动使用的空白模板

ADR Index Format

ADR索引格式

markdown

undefined

markdown

undefined

Architecture Decision Records

ADR	Title	Status	Date
0001	Use Next.js as frontend framework	accepted	2026-01-15
0002	PostgreSQL over MongoDB for primary datastore	accepted	2026-01-20
0003	REST API over GraphQL	accepted	2026-02-01

undefined

ADR	Title	Status	Date
0001	Use Next.js as frontend framework	accepted	2026-01-15
0002	PostgreSQL over MongoDB for primary datastore	accepted	2026-01-20
0003	REST API over GraphQL	accepted	2026-02-01

undefined

Decision Detection Signals

决策检测信号

Watch for these patterns in conversation that indicate an architectural decision:

Explicit signals

"Let's go with X"
"We should use X instead of Y"
"The trade-off is worth it because..."
"Record this as an ADR"

Implicit signals (suggest recording an ADR — do not auto-create without user confirmation)

Comparing two frameworks or libraries and reaching a conclusion
Making a database schema design choice with stated rationale
Choosing between architectural patterns (monolith vs microservices, REST vs GraphQL)
Deciding on authentication/authorization strategy
Selecting deployment infrastructure after evaluating alternatives

留意对话中以下表明架构决策的模式：

明确信号

"我们选X吧"
"我们应该用X而非Y"
"这个取舍是值得的，因为……"
"把这个记录为ADR"

隐含信号（建议记录ADR，但需用户确认后再自动创建）

比较两个框架或库并得出结论
基于明确理由做出数据库 schema 设计选择
在架构模式间做选择（单体 vs 微服务、REST vs GraphQL）
确定认证/授权策略
评估备选方案后选择部署基础设施

What Makes a Good ADR

优质ADR的标准

Do

要做

Be specific — "Use Prisma ORM" not "use an ORM"
Record the why — the rationale matters more than the what
Include rejected alternatives — future developers need to know what was considered
State consequences honestly — every decision has trade-offs
Keep it short — an ADR should be readable in 2 minutes
Use present tense — "We use X" not "We will use X"

具体明确 — 写"使用Prisma ORM"而非"使用ORM"
记录原因 — 决策理由比决策内容更重要
包含被否决的备选方案 — 后续开发者需要了解曾考虑过的选项
如实说明影响 — 每个决策都有取舍
保持简洁 — ADR应能在2分钟内读完
使用现在时态 — 写"我们使用X"而非"我们将使用X"

Don't

不要做

Record trivial decisions — variable naming or formatting choices don't need ADRs
Write essays — if the context section exceeds 10 lines, it's too long
Omit alternatives — "we just picked it" is not a valid rationale
Backfill without marking it — if recording a past decision, note the original date
Let ADRs go stale — superseded decisions should reference their replacement

记录琐碎决策 — 变量命名或格式选择不需要ADR
写成长篇大论 — 背景部分超过10行就太长了
省略备选方案 — "我们随便选的"不是合理的理由
补录时不标注 — 若记录过去的决策，需注明原始日期
让ADR过时 — 被取代的决策应关联替代它的新ADR

ADR Lifecycle

ADR生命周期

proposed → accepted → [deprecated | superseded by ADR-NNNN]

proposed: decision is under discussion, not yet committed
accepted: decision is in effect and being followed
deprecated: decision is no longer relevant (e.g., feature removed)
superseded: a newer ADR replaces this one (always link the replacement)

proposed → accepted → [deprecated | superseded by ADR-NNNN]

proposed：决策正在讨论中，尚未最终确定
accepted：决策已生效并被遵循
deprecated：决策不再相关（如功能已移除）
superseded：被新的ADR取代（需始终关联替代的ADR）

Categories of Decisions Worth Recording

值得记录的决策类别

Category	Examples
Technology choices	Framework, language, database, cloud provider
Architecture patterns	Monolith vs microservices, event-driven, CQRS
API design	REST vs GraphQL, versioning strategy, auth mechanism
Data modeling	Schema design, normalization decisions, caching strategy
Infrastructure	Deployment model, CI/CD pipeline, monitoring stack
Security	Auth strategy, encryption approach, secret management
Testing	Test framework, coverage targets, E2E vs integration balance
Process	Branching strategy, review process, release cadence

类别	示例
技术选型	框架、语言、数据库、云服务商
架构模式	单体 vs 微服务、事件驱动、CQRS
API设计	REST vs GraphQL、版本策略、认证机制
数据建模	schema设计、规范化决策、缓存策略
基础设施	部署模型、CI/CD流水线、监控栈
安全	认证策略、加密方式、密钥管理
测试	测试框架、覆盖率目标、端到端测试与集成测试的平衡
流程	分支策略、评审流程、发布节奏

Integration with Other Skills

与其他技能的集成

Planner agent: when the planner proposes architecture changes, suggest creating an ADR
Code reviewer agent: flag PRs that introduce architectural changes without a corresponding ADR

Planner agent：当规划agent提出架构变更时，建议创建ADR
Code reviewer agent：标记那些引入架构变更但未对应ADR的PR