---
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 を新しい番号とする。
ディレクトリが存在しない場合は `mkdir -p docs/adr` で作成する。

```bash
ls docs/adr/*.md 2>/dev/null | sort | tail -1
```

ファイルが1件も存在しない場合は `0001` から開始する。

### 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 フォーマット

```markdown
# 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` へ変更する運用を提案する。