create-adr

ADR 作成ツール

Architecture Decision Record（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 形式の選択

広く使用されている形式は 3 つあります。状況に応じて適切な形式を判断するか、ユーザーに確認します。

形式	最適な用途	長さ
MADR（Markdown ADR）	選択肢を体系的に比較したいチーム	中程度
Nygard（オリジナル）	最小限かつ迅速な記録、明白な決定	短い
Y-Statement	インラインドキュメント、非常に簡潔な状況	1 段落

ユーザーから指定がない場合や、決定が非常に単純な場合を除き、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-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 つ含まれている
• 該当する場合、置き換える／置き換えられた ADR へのリンクが含まれている
• ファイルが命名規則 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
• ケバブケースのタイトル
• .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 に 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 を作成してください」
• 「RabbitMQ ではなく Kafka を選んだ理由を記録したいです」
• 「認証方式について、アーキテクチャ決定記録を追加してください」

ポルトガル語

• 「PostgreSQL を使用する決定について ADR を作成してください」
• 「プロジェクトで GraphQL を採用する決定を文書化してください」
• 「Kafka を選んだ理由を説明する ADR を作成してください」

スペイン語

• 「PostgreSQLを使用する決定についてADRを作成してください」
• 「マイクロサービスを採用する決定を文書化してください」
• 「Next.jsを選んだ理由を説明するADRを作成してください」