Back to Details

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评论或某人的记忆中，本Skill会生成结构化的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: [Decision Title]

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

Context

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]
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]

Decision

Decision

What is the change that we're proposing and/or doing?
[1-3 sentences stating the decision clearly]
What is the change that we're proposing and/or doing?
[1-3 sentences stating the decision clearly]

Alternatives Considered

Alternatives Considered

Alternative 1: [Name]

Alternative 1: [Name]

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

Alternative 2: [Name]

Alternative 2: [Name]

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

Consequences

Consequences

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

Positive

Positive

  • [benefit 1]
  • [benefit 2]
  • [benefit 1]
  • [benefit 2]

Negative

Negative

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

Risks

Risks

  • [risk and mitigation]
undefined
  • [risk and mitigation]
undefined

Workflow

工作流程

Capturing a New ADR

捕获新ADR

When a decision moment is detected:
  1. 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.
  2. Identify the decision — extract the core architectural choice being made
  3. Gather context — what problem prompted this? What constraints exist?
  4. Document alternatives — what other options were considered? Why were they rejected?
  5. State consequences — what are the trade-offs? What becomes easier/harder?
  6. Assign a number — scan existing ADRs in 
    docs/adr/
    and increment
  7. 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.
  8. Update the index — append to 
    docs/adr/README.md
当检测到决策时刻时：
  1. 初始化（仅首次） — 如果
    docs/adr/
    目录不存在，需先征得用户同意，再创建该目录、包含索引表表头的
    README.md
    （见下方ADR索引格式），以及供手动使用的空白
    template.md
    。未经明确同意不得创建文件。
  2. 识别决策 — 提取核心的架构选择内容
  3. 收集上下文 — 是什么问题引发了这个决策？存在哪些约束条件？
  4. 记录替代方案 — 还考虑了哪些其他选项？为什么被拒绝？
  5. 说明影响 — 存在哪些权衡？哪些操作会变容易/困难？
  6. 分配编号 — 扫描
    docs/adr/
    中的现有ADR，递增编号
  7. 确认并写入 — 将ADR草稿呈现给用户审核。仅在获得明确批准后，写入
    docs/adr/NNNN-decision-title.md
    。若用户拒绝，则丢弃草稿，不写入任何文件。
  8. 更新索引 — 将新ADR追加到
    docs/adr/README.md
    中

Reading Existing ADRs

查看现有ADR

When a user asks "why did we choose X?":
  1. Check if 
    docs/adr/
    exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?"
  2. If it exists, scan 
    docs/adr/README.md
    index for relevant entries
  3. Read matching ADR files and present the Context and Decision sections
  4. If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"
当用户询问“我们为什么选择X？”时：
  1. 检查
    docs/adr/
    是否存在 — 若不存在，回复：“本项目中未找到ADR。是否要开始记录架构决策？”
  2. 若存在，扫描
    docs/adr/README.md
    索引中的相关条目
  3. 读取匹配的ADR文件，呈现背景和决策部分
  4. 若未找到匹配项，回复：“未找到该决策对应的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

Architecture Decision Records

ADRTitleStatusDate
0001Use Next.js as frontend frameworkaccepted2026-01-15
0002PostgreSQL over MongoDB for primary datastoreaccepted2026-01-20
0003REST API over GraphQLaccepted2026-02-01
undefined
ADRTitleStatusDate
0001Use Next.js as frontend frameworkaccepted2026-01-15
0002PostgreSQL over MongoDB for primary datastoreaccepted2026-01-20
0003REST API over GraphQLaccepted2026-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，但未经用户确认不得自动创建）
  • 比较两个框架或库并得出结论
  • 做出带有明确理由的数据库架构设计选择
  • 在架构模式之间做选择（单体架构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（务必链接替代的ADR）

Categories of Decisions Worth Recording

值得记录的决策分类

CategoryExamples
Technology choicesFramework, language, database, cloud provider
Architecture patternsMonolith vs microservices, event-driven, CQRS
API designREST vs GraphQL, versioning strategy, auth mechanism
Data modelingSchema design, normalization decisions, caching strategy
InfrastructureDeployment model, CI/CD pipeline, monitoring stack
SecurityAuth strategy, encryption approach, secret management
TestingTest framework, coverage targets, E2E vs integration balance
ProcessBranching strategy, review process, release cadence
分类示例
技术选型框架、语言、数据库、云服务商
架构模式单体vs微服务、事件驱动、CQRS
API设计REST vs GraphQL、版本策略、认证机制
数据建模架构设计、规范化决策、缓存策略
基础设施部署模型、CI/CD流水线、监控堆栈
安全认证策略、加密方式、密钥管理
测试测试框架、覆盖率目标、端到端测试vs集成测试的平衡
流程分支策略、评审流程、发布节奏

Integration with Other Skills

与其他Skill的集成

  • 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：当Planner agent提出架构变更时，建议创建ADR
  • Code reviewer agent：标记那些引入架构变更但未对应ADR的PR