Back to Details

adr-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ADR Management

ADR管理

Note: This is the canonical ADR skill for the plugin ecosystem. For detailed ADR templates (Nygard, MADR, Enterprise), use MCP tools (
perplexity
, 
context7
) to research current best practices.
注意： 这是插件生态系统中的标准ADR技能。如需详细的ADR模板（Nygard、MADR、企业级），可使用MCP工具（
perplexity
、
context7
）调研当前最佳实践。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Document a technology choice or design decision
  • Record why a particular approach was selected over alternatives
  • Track the history of architectural decisions
  • Create a searchable record of decisions for team onboarding
Keywords: adr, architecture decision record, decision log, why we chose, alternatives considered, design decision, technology choice
当你需要以下操作时，可使用本技能：
  • 记录技术选型或设计决策
  • 记录为何选择某一方案而非其他备选方案
  • 跟踪架构决策的历史
  • 创建可搜索的决策记录，用于团队新成员入职培训
关键词： adr, architecture decision record, decision log, why we chose, alternatives considered, design decision, technology choice

ADR Workflow

ADR工作流

Creating a New ADR

创建新的ADR

  1. Determine the next ADR number
    • Check existing ADRs in 
      /architecture/adr/
    • Use sequential numbering: 0001, 0002, 0003, etc.
  2. Create the ADR file
    • Location: 
      /architecture/adr/NNNN-title-in-kebab-case.md
    • Use the template from 
      references/adr-template.md
  3. Fill in required sections
    • Status: Start with "Proposed"
    • Date: Current date in YYYY-MM-DD format
    • Context: Describe the problem and constraints
    • Decision: State the decision clearly
    • Consequences: List positive, negative, and neutral outcomes
  4. Document alternatives
    • List each alternative considered
    • Include pros, cons, and why it was rejected
  5. Optional: Generate context diagram
    • If visualization plugin is available, generate a diagram showing the decision's context
    • Spawn the 
      visualization:diagram-generator
      agent for C4 or component diagrams
    • Or use the 
      visualization:diagram-patterns
      skill for diagram type guidance
  1. 确定下一个ADR编号
    • 查看
      /architecture/adr/
      目录下的现有ADR
    • 使用连续编号：0001、0002、0003等
  2. 创建ADR文件
    • 位置：
      /architecture/adr/NNNN-title-in-kebab-case.md
    • 使用
      references/adr-template.md
      中的模板
  3. 填写必填章节
    • 状态：初始为“提议中”
    • 日期：当前日期，格式为YYYY-MM-DD
    • 背景：描述问题和约束条件
    • 决策：明确说明所做的决策
    • 影响：列出正面、负面和中性的结果
  4. 记录备选方案
    • 列出所有考虑过的备选方案
    • 包括各方案的优缺点，以及被否决的原因
  5. 可选：生成背景图
    • 如果有可视化插件可用，生成展示决策背景的图表
    • 调用
      visualization:diagram-generator
      agent生成C4图或组件图
    • 或使用
      visualization:diagram-patterns
      技能获取图表类型指导

ADR Status Lifecycle

ADR状态生命周期

StatusMeaning
ProposedDecision is under discussion
AcceptedDecision has been approved and implemented
DeprecatedDecision is no longer relevant but kept for history
SupersededDecision has been replaced by a newer ADR
When superseding an ADR:
  1. Update the old ADR's status to "Superseded by ADR-XXXX"
  2. Reference the old ADR in the new ADR's "Related Decisions" section
状态含义
Proposed决策正在讨论中
Accepted决策已获批准并已实施
Deprecated决策已不再相关，但为保留历史而留存
Superseded决策已被新的ADR取代
当取代某一ADR时：
  1. 将旧ADR的状态更新为“Superseded by ADR-XXXX”
  2. 在新ADR的“相关决策”章节中引用旧ADR

Searching Existing ADRs

搜索现有ADR

Before creating a new ADR, search for existing relevant decisions:
bash
undefined
创建新ADR前，先搜索现有的相关决策：
bash
undefined

Search ADR titles

搜索ADR标题

ls /architecture/adr/
ls /architecture/adr/

Search ADR content for keywords

按关键词搜索ADR内容

grep -r "keyword" /architecture/adr/
undefined
grep -r "keyword" /architecture/adr/
undefined

Integration with Architecture Principles

与架构原则的集成

Link ADRs to architecture principles when the decision:
  • Implements a principle
  • Makes a trade-off against a principle
  • Establishes a new principle
Reference format: "This decision implements Principle P1: [Principle Name]"
当决策满足以下情况时，将ADR与架构原则关联：
  • 某原则的具体实现
  • 与某原则存在权衡取舍
  • 确立了新的原则
引用格式：“本决策遵循原则P1：[原则名称]”

Template Reference

模板参考

The ADR template is available at 
references/adr-template.md
. Key sections:
  • Status: Current state of the decision
  • Date: When the decision was made
  • Deciders: Who was involved
  • Context: Problem and constraints
  • Decision: What was decided
  • Consequences: Outcomes (positive, negative, neutral)
  • Alternatives Considered: What else was evaluated
  • Related Decisions: Links to related ADRs
  • References: Supporting documentation
ADR模板位于
references/adr-template.md
，核心章节包括：
  • 状态：决策的当前状态
  • 日期：决策的制定日期
  • 决策者：参与决策的人员
  • 背景：问题和约束条件
  • 决策：所做的具体决策
  • 影响：产生的结果（正面、负面、中性）
  • 考虑过的备选方案：评估过的其他方案
  • 相关决策：关联的其他ADR链接
  • 参考资料：支持性文档

Best Practices

最佳实践

  1. One decision per ADR - Keep ADRs focused
  2. Immutable history - Never delete ADRs, only supersede
  3. Link decisions - Reference related ADRs
  4. Include context - Future readers need to understand the constraints
  5. Be honest about trade-offs - Document negative consequences too
  1. 一个ADR对应一个决策——保持ADR的聚焦性
  2. 不可变历史——永远不要删除ADR，仅可被取代
  3. 关联决策——引用相关的ADR
  4. 包含背景信息——未来的阅读者需要了解当时的约束条件
  5. 坦诚记录权衡——也要记录负面的影响

Related: Specification-Driven ADRs

相关：规范驱动的ADR

If you're extracting decisions FROM specifications, consider using the 
spec-driven-development
plugin's 
/spec:adr:create
which links ADRs directly to specification IDs (SPEC-xxx). Those ADRs are stored in 
docs/adr/
(linked to specification IDs).
Both approaches use MADR format and can coexist in the same project.
如果你需要从规范中提取决策，可考虑使用
spec-driven-development
插件的
/spec:adr:create
功能，它会将ADR直接与规范ID（SPEC-xxx）关联。这些ADR存储在
docs/adr/
目录下（与规范ID关联）。
两种方法均采用MADR格式，可在同一项目中共存。

Repository Structure

仓库结构

Ensure your project has the standard architecture directory:
text
/architecture/
  /adr/
    0001-record-template.md
    0002-first-decision.md
    ...
If the directory doesn't exist, create it before adding ADRs.
确保你的项目拥有标准的架构目录：
text
/architecture/
  /adr/
    0001-record-template.md
    0002-first-decision.md
    ...
如果该目录不存在，添加ADR前请先创建它。

User-Facing Interface

用户界面

When invoked directly by the user, this skill creates a new ADR.
当用户直接调用本技能时，它会创建一个新的ADR。

Execution Workflow

执行工作流

  1. Determine next ADR number by scanning existing ADRs in 
    /architecture/adr/
    (sequential: 0001, 0002, etc.)
  2. Create the ADR file using the standard template with sequential numbering, initial status "Proposed", current date (UTC), and title from arguments
  3. Report the created file path so the user can complete the Context, Decision, and Consequences sections
  1. 确定下一个ADR编号：扫描
    /architecture/adr/
    目录下的现有ADR（连续编号：0001、0002等）
  2. 创建ADR文件：使用标准模板，包含连续编号、初始状态“提议中”、当前UTC日期，以及从参数中获取的标题
  3. 报告创建的文件路径，以便用户填写背景、决策和影响章节

Example Usage

使用示例

text
/ea:adr-management Use PostgreSQL for persistence
/ea:adr-management Adopt microservices architecture
text
/ea:adr-management Use PostgreSQL for persistence
/ea:adr-management Adopt microservices architecture

Version History

版本历史

  • v1.0.0 (2025-12-05): Initial release
    • ADR creation and management workflow
    • Status lifecycle documentation
    • Integration with architecture principles
    • Template reference and best practices
  • v1.0.0（2025-12-05）：初始版本
    • ADR创建和管理工作流
    • 状态生命周期文档
    • 与架构原则的集成
    • 模板参考和最佳实践

Last Updated

最后更新

Date: 2025-12-05 Model: claude-opus-4-5-20251101
日期： 2025-12-05 模型： claude-opus-4-5-20251101