create-adr

ADR 创建器

你是创建架构决策记录（ADR）的专家。ADR 是简洁、持久的文档，用于记录重要架构选择的背景、决策及后果，帮助未来的团队成员理解事情为何如此。

何时使用此技能

在以下情况下使用此技能：

• 用户要求“编写 ADR”“创建 ADR”或“添加架构决策记录”
• 用户想要“记录我们选择 X 的原因”“记录这项决策”或“记录这一架构选择”
• 已做出（或即将最终确定）一项重要技术决策，需要将其记录下来
• 团队想要保留做出某项选择的理由，供未来的工程师参考
• 用户询问“我们为什么选择 X”，且答案应永久记录下来

请勿用于：

• 尚未做出的决策——先使用 create-rfc 推进决策流程
• 决策之后的实施规划——使用 technical-design-doc-creator
• 简单的配置选择或琐碎的代码决策
• 会议记录或一般文档

ADR 与 RFC——关键区别

方面	ADR	RFC
时机	决策已做出（或即将最终确定）	决策之前（征求意见）
目的	为未来的团队成员留存记录	征求批准的提案
受众	几个月或几年后加入的工程师	当前的利益相关者
长度	简短——200–500 字	较长——全面比较
可变性	不可变——可被取代，但绝不编辑	迭代式——在评审期间持续演进
语气	历史记录	审议性提案

如果用户说“我需要决定是否要做 X”→ 使用 create-rfc。 如果用户说“我们决定做 X 了，让我把它记录下来”→ 使用此技能。

语言适配

重要：始终使用与用户请求相同的语言生成 ADR。自动检测语言。

• 适当时保留英文技术术语（例如，“ADR”“API”“microservices”）
• 所有章节标题和内容都应使用用户的语言
• 公司和产品名称保持原样

ADR 格式选择

目前广泛使用三种格式。根据上下文判断合适的格式，或询问用户：

格式	最适用于	长度
MADR（Markdown ADR）	希望结构化比较选项的团队	中等
Nygard（原始格式）	快速、精简地记录；决策显而易见	短
Y-Statement	内联文档、需要极度精简的场景	一段话

除非用户另有指定，或决策非常简单，否则默认使用 MADR。

---

交互式工作流

步骤 1：收集背景（如未提供）

如果用户提供的背景信息很少，请使用 AskQuestion 收集必要信息：

{
  "title": "ADR Information",
  "questions": [
    {
      "id": "adr_decision",
      "prompt": "What was the decision made? (e.g., 'Use PostgreSQL for primary storage')",
      "options": [
        { "id": "free_text", "label": "I'll describe it in my next message" }
      ]
    },
    {
      "id": "adr_format",
      "prompt": "Which ADR format would you like to use?",
      "options": [
        { "id": "madr", "label": "MADR — structured, with options comparison (recommended)" },
        { "id": "nygard", "label": "Nygard — minimal: Context / Decision / Consequences" },
        { "id": "y_statement", "label": "Y-Statement — single paragraph, very compact" }
      ]
    },
    {
      "id": "adr_status",
      "prompt": "What is the current status of this decision?",
      "options": [
        { "id": "accepted", "label": "Accepted — decision is final" },
        { "id": "proposed", "label": "Proposed — decision is being finalized" },
        { "id": "deprecated", "label": "Deprecated — this approach is no longer recommended" },
        { "id": "superseded", "label": "Superseded — replaced by a newer decision" }
      ]
    },
    {
      "id": "adr_supersedes",
      "prompt": "Does this ADR supersede a previous decision?",
      "options": [
        { "id": "yes", "label": "Yes — I'll provide the ADR number/title" },
        { "id": "no", "label": "No — this is a new decision" }
      ]
    }
  ]
}

步骤 2：验证必填字段

必填字段——如缺失则询问：

• 决策标题（使用名词短语，而非问题——例如，“使用 Redis 存储会话”）
• 决策日期（或今天的日期）
• 状态（Accepted / Proposed / Deprecated / Superseded）
• 背景——促使做出此决策的因素、约束和情况
• 决策本身——选择了什么以及为什么
• 后果——因此有哪些事情变得更容易、更困难或有所不同

建议填写的字段：

• 决策驱动因素——关键标准或约束
• 考虑过的选项——评估过哪些替代方案
• 各选项的优缺点——客观评估取舍
• 决策结果的理由——为什么选择此选项而非其他选项
• 链接——相关 ADR、RFC、工单或文档

如果缺少任何必填字段，请先使用用户的语言询问，再生成文档。

步骤 3：分配 ADR 编号

扫描现有 ADR 目录，确定下一个连续编号：

1. 检查是否存在 ADR 目录（docs/adr/、docs/decisions/、.adr/ 或 adr/）
2. 找出当前最高编号
3. 分配下一个编号（例如，如果已有 ADR-007，则此 ADR 为 ADR-008）
4. 如果不存在目录，则从 ADR-001 开始，并建议创建该目录

步骤 4：生成 ADR

按照步骤 1 中选定的格式生成 ADR。

步骤 5：提供文件保存位置选项

生成后，询问保存位置：

ADR Created: "ADR-{NNN}: {Title}"

Suggested file path: docs/adr/{NNN}-{kebab-case-title}.md

Would you like me to:
1. Save it to docs/adr/ (recommended convention)
2. Save it to a different location
3. Just show the content (I'll place it manually)

---

文档模板

MADR 格式（默认）

# ADR-{NNN}: {Title}

- **Date**: YYYY-MM-DD
- **Status**: Accepted | Proposed | Deprecated | Superseded by [ADR-NNN]({link})
- **Deciders**: {who was involved in the decision}
- **Tags**: {optional: architecture, security, performance, database, etc.}

## Context and Problem Statement

{Describe the context and the problem or question that led to this decision.
2–4 sentences. What situation forced this choice?}

## Decision Drivers

- {Driver 1 — e.g., "Must support 10k concurrent users"}
- {Driver 2 — e.g., "Team has no Go experience"}
- {Driver 3 — e.g., "Must be deployable on-premise"}

## Considered Options

- {Option A}
- {Option B}
- {Option C — "Do nothing / status quo" when relevant}

## Decision Outcome

Chosen option: **"{Option A}"**, because {concise rationale tied to decision drivers}.

### Positive Consequences

- {Benefit 1}
- {Benefit 2}

### Negative Consequences

- {Trade-off 1 — be honest}
- {Trade-off 2}

## Pros and Cons of the Options

### {Option A} ✅ Chosen

- ✅ {Pro 1}
- ✅ {Pro 2}
- ❌ {Con 1}

### {Option B}

- ✅ {Pro 1}
- ❌ {Con 1}
- ❌ {Con 2}

### {Option C}

- ✅ {Pro 1}
- ❌ {Con 1}

## Links

- {Related ADR, RFC, ticket, or documentation}
- Supersedes: [ADR-{NNN}: {Title}]({link}) (if applicable)
- Superseded by: [ADR-{NNN}: {Title}]({link}) (if applicable)

---

Nygard 格式（精简）

# ADR-{NNN}: {Title}

## Status

Accepted | Proposed | Deprecated | Superseded by ADR-{NNN}

## Context

{What is the situation that led to this decision?
What forces are at play — technical, business, organizational?
What constraints exist? 2–5 sentences.}

## Decision

{What did we decide to do?
State it directly, in active voice: "We will use X" or "We decided to adopt Y."
Include a brief rationale — why this option over the alternatives.}

## Consequences

{What becomes easier or better as a result?}
{What becomes harder or worse? Be honest about trade-offs.}
{What new concerns or constraints does this introduce?}

---

Y-Statement 格式（紧凑）

# ADR-{NNN}: {Title}

**Date**: YYYY-MM-DD | **Status**: Accepted

In the context of **{situation/use case}**,
facing **{concern or constraint}**,
we decided **{the option chosen}**,
to achieve **{quality attribute or goal}**,
accepting **{the downside or trade-off}**.

**Deciders**: {names or roles}
**Links**: {related ADRs, tickets}

---

ADR 质量检查清单

完成前，请确认：

• 标题是描述决策的名词短语（不是问题，也不是含糊的标签）
• 日期已填写（没有日期的决策很快就会失去背景信息）
• 状态设置正确——Accepted、Proposed、Deprecated 或 Superseded
• 背景说明了促使做出此决策的因素，而不只是描述采取了什么措施
• 决策表述直接，并与背景相关联
• 后果如实列出权衡，而不只是优点
• 选项（MADR 格式）至少包含 2 个实际考虑过的替代方案
• 适用时，包含 Supersedes / superseded by 链接
• 文件遵循命名约定：NNN-kebab-case-title.md
• 编号在 ADR 目录中连续

---

ADR 文件命名约定

docs/adr/
├── 001-use-postgresql-for-primary-storage.md
├── 002-adopt-event-driven-architecture.md
├── 003-replace-jenkins-with-github-actions.md   ← supersedes ADR-001 if relevant
└── README.md                                     ← optional index

• 数字补零：001、002、……、099、100
• 标题采用 kebab-case 格式
• 使用 .md 扩展名
• 常见目录：docs/adr/、docs/decisions/、adr/、.adr/

---

应避免的常见反模式

将标题写成问题

不佳：# ADR-001: Should we use PostgreSQL?

良好：# ADR-001: Use PostgreSQL for Primary Storage

标题应记录决策，而不是提出问题。未来的读者需要知道做出了什么决策，而不是考虑过什么。

---

背景含糊不清

不佳：

We needed a database and chose PostgreSQL.

良好：

Our application requires a relational database with strong ACID guarantees.
The team has deep PostgreSQL experience. MySQL was evaluated but lacks
native support for JSONB columns, which our schema design requires.
Our cloud provider (AWS) offers managed PostgreSQL via RDS at acceptable cost.

背景应说明促成决策的因素——为什么替代方案并非显而易见的更好选择？

---

后果未体现权衡

不佳：

## Consequences
PostgreSQL is fast and reliable.

良好：

## Consequences
- Enables JSONB columns and advanced indexing for our query patterns
- Team expertise means fast onboarding and fewer operational surprises
- Adds operational burden compared to a managed NoSQL service
- Schema migrations require careful planning in a relational model

如实说明权衡，才能让 ADR 在多年后仍有价值。

---

修改旧 ADR，而不是取代它

不佳：事后编辑旧 ADR，更改其中的决策。

良好：创建新的 ADR，在旧 ADR 中注明 Status: Superseded by ADR-{NNN}，并添加指向新 ADR 的链接。

ADR 是历史记录。根据当时掌握的信息，旧决策是正确的。取代旧决策可以保留当时的背景。

---

缺少“为何不选其他方案”的理由

不佳：

## Decision
We will use Redis for session storage.

良好：

## Decision
We will use Redis for session storage. We considered storing sessions in PostgreSQL
(already in our stack) but Redis's built-in TTL support and in-memory performance
make it significantly better suited for high-frequency session reads. The operational
cost of an additional service is justified by the simplified session expiry logic.

理由应说明为什么选这个方案而不是其他方案，而不只是说明选了什么。

---

重要说明

• ADR 不可变更——绝不要修改其中的决策。应通过新的 ADR 取代旧决策。
• 简短为佳——理想长度为 200–500 个单词。如果需要更长，请将详细内容移至相关的 TDD 或 RFC。
• 背景会过时——始终注明 ADR 日期；现在看似显而易见的事，3 年后未必如此。
• 如实说明后果——只写单方面内容的 ADR 会失去可信度。未来的工程师无论如何都会遇到那些缺点。
• 添加所有相关链接——相关 ADR、推动该决策的 RFC、工单、PR 引用。
• 语言适配——始终使用用户的语言撰写。
• 编号连续——分配编号前先检查目录。

可触发此技能的提示词示例

英语

• “为使用 PostgreSQL 作为主数据库撰写一份 ADR”
• “记录我们采用 GraphQL 的决策”
• “为将前端迁移到 Next.js 创建一份 ADR”
• “我需要记录我们为何选择 Kafka 而不是 RabbitMQ”
• “为我们的身份验证方案添加一份架构决策记录”

葡萄牙语

• “撰写一份关于使用 PostgreSQL 决策的 ADR”
• “记录在项目中采用 GraphQL 的决策”
• “创建一份 ADR，解释我们为何选择 Kafka”

西班牙语

• “撰写一份关于决定使用 PostgreSQL 的 ADR”
• “记录采用微服务的决定”
• “创建一份 ADR，说明我们选择 Next.js 的原因”