adr-creator

name	adr-creator
description	Architecture Decision Record (ADR) を作成するスキル。 ADR フォーマット・品質基準に準拠した ADR ファイルを生成する。 「ADRを書いて」「ADRを作成して」「アーキテクチャの意思決定を記録したい」「〇〇を採用する判断を文書化して」 などの指示で発動する。技術選定、設計方針の変更、規約の策定など、アーキテクチャに関する意思決定の記録が必要な場面で使用すること。

ADR Creator

ADR（Architecture Decision Record）を一定品質で作成するためのスキル。

ワークフロー

Step 1: 情報収集

ADR の品質は、書き手がどれだけ背景を理解しているかで決まる。以下の情報を集める。 ユーザーが既に十分な情報を提供している場合は、不足分だけを確認する。

1. 何を決めたのか？ — 意思決定の内容を一文で言えるレベルまで明確にする
2. なぜその判断に至ったのか？ — 背景の課題・制約・動機
3. 他にどんな選択肢を検討したか？ — 少なくとも2つ以上の代替案とその評価
4. この判断で何が良くなり、何が犠牲になるか？ — トレードオフ
5. 参考リンクはあるか？ — Slack の議論URL、技術ドキュメント、書籍など

Step 2: 連番の決定

docs/adr/ ディレクトリを確認し、既存 ADR の最大番号 + 1 を新しい番号とする。

ls docs/adr/*.md | sort -t/ -k3 | tail -1

Step 3: ADR の執筆

以下のフォーマットとガイドラインに従って ADR を作成する。

ファイル命名規則

docs/adr/{NNNN}-{kebab-case-name}.md

• {NNNN}: ゼロ埋め4桁の連番（例: 0019）
• {kebab-case-name}: ADR の内容を端的に示す英語のケバブケース名

例:

• 0024-adopt-redis-for-caching.md
• 0025-frontend-state-management-with-zustand.md

ADR フォーマット

# ADR {NNNN}: {日本語のタイトル}

## Status

{Proposed | Accepted | Deprecated | Superseded}

## Context

{背景と課題を価値中立的に記述する}

### 解決したい課題

{箇条書きまたは説明文で、具体的な課題を挙げる}

### 検討した選択肢

{少なくとも2つ以上の選択肢を列挙する}

### 各選択肢の評価

{比較表で客観的に評価する}

| 観点 | 選択肢A | 選択肢B | 選択肢C |
|------|---------|---------|---------|
| ...  | ...     | ...     | ...     |

## Decision

**{決定内容を太字で一文にまとめる。}**

### 1. {決定の詳細1}

{必要に応じてコード例、図、設定例を含める}

### 2. {決定の詳細2}

{...}

## Consequences

### Positive

- {ポジティブな結果}

### Negative

- {ネガティブな結果}
  - → {緩和策}

### Risks

- {リスク}
  - → {対策}

## 決めていないこと（任意）

{スコープ外とした事項がある場合に記載する}

| 項目 | 決めない理由 | いつ決めるか |
|------|------------|------------|
| ... | ... | ... |

## Notes

### 参考資料

- {参考リンクや関連ADR}

執筆ガイドライン

Context セクション — 読み手に「なぜ今この判断が必要か」を伝える

• 価値中立的に書く。特定の選択肢を推す書き方にしない
• プロジェクトの現状（技術スタック、アーキテクチャ）を最初に簡潔に述べ、読み手が前提を共有できるようにする
• 関連する既存 ADR がある場合は言及する（例: 「モジュラーモノリスアーキテクチャ（ADR 0002）を採用している」）
• 検討した選択肢は比較表で整理する。評価軸は判断に直結するものを選ぶ

Decision セクション — 「何を・どう決めたか」を明確にする

• 冒頭で決定内容を太字の一文にまとめる
• 詳細は番号付きサブセクションで構造化する
• 技術的な決定にはコード例を含めて実装イメージを伝える
• アーキテクチャの構造を示す場合は ASCII 図を使う
• 「選択理由」「採用理由」のセクションで、なぜその選択肢を選んだかを明記する

Consequences セクション — トレードオフを隠さない

• Positive と Negative の両方を必ず書く。Negative がゼロの判断は存在しない
• Negative には必ず → で緩和策を付ける
• Risks セクションで将来のリスクとその対策を記述する
• 関連 ADR への参照で、対策の根拠を示す

決めていないことセクション — スコープを明確にする

• 意図的にスコープ外とした事項がある場合に「決めていないこと」セクションを追加する
• 「決めない理由」と「いつ決めるか」を表形式で記述し、先送りが意図的であることを示す
• このセクションにより、読み手が「なぜこれが書かれていないのか」を疑問に思うことを防ぐ
• 全ての ADR に必要なわけではない。スコープが明確で先送り事項がなければ省略してよい

全体の品質基準

• 言語: 日本語で記述する（コード例・技術用語は英語のまま）
• 分量: 1〜3ページ程度。冗長にならず、かつ判断の根拠が十分に伝わる分量
• 相互参照: 関連する既存 ADR は番号とタイトルで参照する
• コード例: 技術的な決定の場合、Good/Bad の対比で実装方針を示す
• 読者: 半年後のチームメンバーや新規参加者が読んで理解できる水準を目指す

Step 4: レビュー提示

ADR のドラフトが完成したら、ユーザーに提示してフィードバックを求める。 指摘に基づいて修正し、最終版を docs/adr/ に書き出す。 Status は特に指定がない場合 Proposed とし、レビュー承認後に Accepted へ変更する運用を提案する。