Back to Details

adr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecture Decision Records

架构决策记录（ADR）

Expert guidance for creating and managing Architecture Decision Records based on Olaf Zimmermann's research and the MADR (Markdown Architectural Decision Records) methodology.
基于Olaf Zimmermann研究成果及MADR（Markdown Architectural Decision Records）方法论的专业ADR创建与管理指南。

How This Skill Works

该技能的工作方式

When invoked, this skill guides you through the full ADR lifecycle:
  1. Readiness assessment — Evaluate whether a decision is ready to be recorded (START criteria)
  2. Creation — Write well-structured ADRs using the MADR template with anti-pattern avoidance
  3. Quality evaluation — Check completeness using the ECADR "Definition of Done" criteria
  4. Lifecycle management — Maintain ADR logs, supersede outdated records, track decision status
当调用该技能时，它会引导你完成ADR的完整生命周期：
  1. 就绪度评估 — 评估决策是否已准备好记录（START标准）
  2. 创建阶段 — 使用MADR模板编写结构清晰的ADR，同时避免反模式
  3. 质量评估 — 利用ECADR「完成定义」标准检查完整性
  4. 生命周期管理 — 维护ADR日志、替换过时记录、跟踪决策状态

Core Philosophy

核心理念

"Don't decide too early, this harms flexibility. Don't decide too late either."
ADRs function as decision journals — not blueprints or policies. They capture the rationale behind architecturally significant choices: the problem context, the alternatives considered, the criteria applied, and the consequences accepted. Good ADRs are executive summaries that balance tradeoffs, not sales pitches for a predetermined outcome.
「不要过早做决定，这会损害灵活性。但也不要太晚做决定。」
ADR的作用是决策日志——而非蓝图或政策。它记录架构重大选择背后的理由：问题背景、考虑过的备选方案、应用的标准以及接受的后果。优质的ADR是平衡取舍的执行摘要，而非预设结果的推销说辞。

When to Use This Skill

何时使用该技能

  • Creating a new ADR for an architectural decision
  • Evaluating whether a decision is ready to be recorded
  • Reviewing an existing ADR for completeness and quality
  • Writing or customizing a MADR template for a project
  • Assessing whether a requirement is architecturally significant
  • Managing an ADR log (superseding, deprecating, linking decisions)
  • Training teams on ADR best practices
  • 为架构决策创建新的ADR
  • 评估决策是否已准备好记录
  • 评审现有ADR的完整性与质量
  • 为项目编写或自定义MADR模板
  • 评估需求是否具有架构重要性
  • 管理ADR日志（替换、弃用、关联决策）
  • 培训团队掌握ADR最佳实践

Command Modes

命令模式

ArgumentAction
create
Walk through creating a new ADR interactively
review
Evaluate an existing ADR against quality criteria
check-ready
Assess decision readiness using START criteria
check-done
Assess ADR completeness using ECADR criteria
template
Output a blank MADR template ready to fill in
list
Help organize and maintain an ADR log
(no args)General ADR guidance based on context
参数操作
create
交互式引导创建新ADR
review
对照质量标准评估现有ADR
check-ready
使用START标准评估决策就绪度
check-done
使用ECADR标准评估ADR完整性
template
输出可直接填写的空白MADR模板
list
协助整理和维护ADR日志
(无参数)根据上下文提供通用ADR指导

The MADR Template (Quick Reference)

MADR模板（快速参考）

markdown
undefined
markdown
undefined

ADR-NNNN: [Short Title Describing Decision]

ADR-NNNN: [Short Title Describing Decision]

Status

Status

[proposed | accepted | deprecated | superseded by ADR-XXXX]
[proposed | accepted | deprecated | superseded by ADR-XXXX]

Date

Date

YYYY-MM-DD
YYYY-MM-DD

Decision Makers

Decision Makers

[Who made or approved this decision]
[Who made or approved this decision]

Context and Problem Statement

Context and Problem Statement

[1-3 paragraphs: What is the issue? Why does it matter? Frame as a question when possible.]
[1-3 paragraphs: What is the issue? Why does it matter? Frame as a question when possible.]

Decision Drivers

Decision Drivers

  • [Driver 1: quality attribute, business constraint, or technical concern]
  • [Driver 2]
  • [Driver 3]
  • [Driver 1: quality attribute, business constraint, or technical concern]
  • [Driver 2]
  • [Driver 3]

Considered Options

Considered Options

  1. [Option A — the chosen option]
  2. [Option B]
  3. [Option C]
  1. [Option A — the chosen option]
  2. [Option B]
  3. [Option C]

Decision Outcome

Decision Outcome

Chosen option: "[Option A]", because [justification referencing decision drivers].
Chosen option: "[Option A]", because [justification referencing decision drivers].

Consequences

Consequences

  • Good, because [positive consequence]
  • Good, because [another benefit]
  • Bad, because [accepted tradeoff]
  • Bad, because [known limitation]
  • Good, because [positive consequence]
  • Good, because [another benefit]
  • Bad, because [accepted tradeoff]
  • Bad, because [known limitation]

Pros and Cons of Options

Pros and Cons of Options

Option A

Option A

  • Good, because [advantage]
  • Bad, because [disadvantage]
  • Good, because [advantage]
  • Bad, because [disadvantage]

Option B

Option B

  • Good, because [advantage]
  • Bad, because [disadvantage]
  • Good, because [advantage]
  • Bad, because [disadvantage]

Option C

Option C

  • Good, because [advantage]
  • Bad, because [disadvantage]
  • Good, because [advantage]
  • Bad, because [disadvantage]

Validation

Validation

[How will we verify this decision works? Code review, design review, architectural fitness function, spike, etc.]
[How will we verify this decision works? Code review, design review, architectural fitness function, spike, etc.]

More Information

More Information

[Links to related ADRs, RFCs, spikes, or external references. Note confidence level and planned review date.]
undefined
[Links to related ADRs, RFCs, spikes, or external references. Note confidence level and planned review date.]
undefined

Key Frameworks

核心框架

START — Definition of Ready

START — 就绪定义

Before writing an ADR, confirm all five criteria:
  • Stakeholders known and available
  • Timing is the Most Responsible Moment
  • Alternatives identified (minimum two)
  • Requirements and context documented
  • Template selected and instantiated
在编写ADR之前，确认以下五项标准：
  • S：相关干系人已明确且可参与
  • T：时机为最负责任的时刻
  • A：已确定备选方案（至少两个）
  • R：需求与背景已记录
  • T：已选择并实例化模板

ECADR — Definition of Done

ECADR — 完成定义

Before marking an ADR as accepted, confirm all five criteria:
  • Evidence that the design will work
  • Criteria applied to compare at least two alternatives
  • Agreement from relevant stakeholders
  • Documentation captured and shared
  • Realization and review plan scheduled
在将ADR标记为已接受之前，确认以下五项标准：
  • E：有证据表明设计可行
  • C：已应用标准对比至少两个备选方案
  • A：相关干系人已达成共识
  • D：文档已记录并共享
  • R：已制定实现与评审计划

ASR Test — Architectural Significance

ASR测试 — 架构重要性

A requirement warrants an ADR when it scores on these criteria:
  • High business impact or risk
  • Critical stakeholder concern
  • Quality-of-service deviation from current architecture
  • External dependency that is unpredictable or uncontrollable
  • Cross-cutting concern affecting multiple components
  • First-of-a-kind implementation for the team
  • Historical precedent of causing problems
当需求符合以下标准时，需要编写ADR：
  • 高业务影响或风险
  • 关键干系人关注
  • 服务质量偏离当前架构
  • 不可预测或无法控制的外部依赖
  • 影响多个组件的横切关注点
  • 团队首次实施的方案
  • 历史上曾引发问题的先例

What This Skill Provides

该技能提供的功能

  1. Readiness assessment using START criteria with checklists
  2. MADR template generation (full and minimal variants)
  3. Anti-pattern detection in draft ADRs (11 known anti-patterns)
  4. Quality evaluation using ECADR Definition of Done
  5. Architectural significance assessment for prioritizing decisions
  6. Lifecycle guidance for maintaining ADR logs over time
  1. 就绪度评估：使用START标准及检查清单
  2. MADR模板生成：提供完整版和精简版变体
  3. 反模式检测：检测草稿ADR中的11种已知反模式
  4. 质量评估：使用ECADR完成定义
  5. 架构重要性评估：用于优先处理决策
  6. 生命周期指导：指导长期维护ADR日志