/adr-rubber-duck

description: ADR（Architecture Decision Record）の壁打ち相手としてヒアリングを通じて意思決定を整理し、ADRドラフトを作成する
allowed-tools: Read, Glob, Grep, Task, Write, Edit, AskUserQuestion, WebSearch, WebFetch, Bash(ls:*), Bash(mkdir:*), Bash(date:*)
argument-hint: "[検討したいアーキテクチャ上の決定事項（任意・ざっくりでOK）]"

ざっくりとしたアーキテクチャ上の決定事項を聞きながら、AskUserQuestion を中心としたヒアリングで背景・制約・選択肢・トレードオフを根掘り葉掘り深掘りし、ADRドラフトを docs/adr/ に作成します。

context

ADR出力ディレクトリ="docs/adr" セッションディレクトリ="docs/adr/.sessions" カレントディレクトリ={{プロジェクトルート}} セッションファイル="" ADR番号="" ADRファイル名="" イテレーション回数=0 最大イテレーション=15 既存ADR一覧=[] 置き換え候補ADR=[] 置き換え対象ADR=[] ヒアリング結果={背景と課題: "", 制約条件: [], 検討した選択肢: [], 決定: "", 決定理由: "", 影響: []} 調査結果=[]

steps

step1: 初期トピックの受け取り

• $1 がある場合、初期トピックとして記録する
• $1 がない場合、ユーザーに「どのようなアーキテクチャ上の決定について検討したいですか？（ざっくりで構いません）」と尋ねる
• step2 を実行する

step2: 既存ADRのスキャンとセッション初期化

• {{ADR出力ディレクトリ}} を Glob（`docs/adr/*.md`）で検索し、既存ADR一覧を作成する
• 各ADRのファイル名・タイトル・ステータスを Read で確認する（ファイル数が多い場合は Task に委譲する）
• 既存ADRの最大番号 +1 を今回の ADR番号 とする（4桁ゼロ埋め。既存ADRがなければ 0001）
• 初期トピックと関連しそうな既存ADRがあれば 置き換え候補ADR として記録する（この時点では確定しない）
• セッションファイルを作成する
• {{セッションディレクトリ}} がなければ作成する
• トピックを 内容の英語化ルール に従って英語スラッグ化する
• セッションファイル名を "{{セッションディレクトリ}}/{{timestamp}}_{{スラッグ}}.md" とする
• 例: docs/adr/.sessions/20260706123456_use_postgresql.md
• <session_template> の形式で初期情報を記録する
• step3 を実行する

step3: ヒアリングループ（深掘り）

• イテレーション回数を +1 する
• ヒアリング観点ルール に従い、現在最も不足している観点を特定する
• AskUserQuestion で観点に沿った質問を行う（1回につき最大4問）
• 選択肢は具体的に書き、ユーザーが選ぶだけで答えられるようにする
• 自由記述が必要な深い理由・背景は「Other」で受けるか、テキストで補足質問する
• 回答を受けて、さらに深掘りが必要なら追加の AskUserQuestion を行う
• 「なぜそれが必要か」「それが満たされないと何が起きるか」まで掘り下げる
• 必要に応じて以下の調査を実施する：
• **コードベース調査**: Task/Grep/Read で現状のアーキテクチャ・依存関係・影響範囲を確認
• **技術調査**: WebSearch/WebFetch で選択肢の比較情報・ベストプラクティスを収集
• 調査結果は選択肢の長所・短所の裏付けとして 調査結果 に記録する
• 新しい情報を ヒアリング結果 に統合する
• セッションファイルを更新する（対話の要点・整理された内容・調査結果を追記）
• 次のアクションを判断するルール に基づいて判断し、該当するステップに進む

step4: 置き換え対象ADRの確認

• 置き換え候補ADR とヒアリング結果を突き合わせ、今回の決定によって無効化・上書きされる既存ADRを洗い出す
• 候補がある場合、AskUserQuestion で各候補が置き換え対象かどうかをユーザーに確認する
• 候補のタイトル・現在のステータス・今回の決定との関係を提示する
• 候補がない場合も「置き換えるべき既存ADRはありませんか？」と既存ADR一覧を提示して確認する
• 確定したものを 置き換え対象ADR に記録する
• step5 を実行する

step5: ADRドラフト作成

• <adr_template> の形式で ADRドラフトを作成する
• ステータスは「ドラフト」とする
• 署名欄は「（未署名）」とする
• 検討した選択肢には、採用しなかった選択肢も長所・短所付きで必ず記載する
• 置き換え対象ADR があれば「置き換えるADR」セクションに番号・タイトル付きで記載する。なければ「なし」と記載する
• ADRファイル名を "{{ADR出力ディレクトリ}}/{{ADR番号}}-{{スラッグ}}.md" として Write で出力する
• 例: docs/adr/0005-use-postgresql.md
• 置き換え対象の既存ADRファイルは更新しない（新ADRはまだドラフトのため）
• セッションファイルに完成したADRへのパスとサマリーを追記する
• step6 を実行する

step6: 完了報告とユーザーへの案内

• ユーザーに以下を報告する
• 作成したADRファイルのパス
• セッションファイルのパス
• ADRの要点サマリー（決定内容・置き換え対象ADR）
• 続けて、必ず以下の依頼事項をユーザーに伝える

ADRドラフトの作成が完了しました。以下の対応をお願いします。

1. ADRの内容を確認し、署名欄（起案者）に署名してください
2. ステータスを「ドラフト」から「提案済み」に変更してください
3. 変更をコミットして git push してください
{{置き換え対象ADRがある場合のみ:
4. このADRが「承認済み」になった際は、置き換え対象の {{旧ADR番号・タイトル}} のステータスを「置き換え」に更新してください}}

rule

ヒアリング観点ルール

以下の観点を順に埋めていく。既に十分な情報がある観点はスキップしてよいが、**背景と課題・検討した選択肢・決定理由は必須**。

観点1: 背景と課題（Why now）

• なぜ今この決定が必要になったのか
• 現状の何が問題なのか、放置すると何が起きるのか
• この決定のスコープ（システム全体か、特定コンポーネントか）

観点2: 制約条件

• 技術的制約（既存技術スタック、互換性、性能要件）
• 組織的制約（チームのスキルセット、運用体制）
• ビジネス的制約（期限、コスト、ライセンス）
• 満たさなければならない非機能要件（性能・セキュリティ・可用性・保守性）

観点3: 検討した選択肢

• 候補として何を検討したか（ユーザーが挙げていない有力候補があれば提案する）
• 各選択肢の長所・短所（調査結果で裏付ける）
• 「何もしない（現状維持）」も選択肢として検討したか

観点4: 決定とトレードオフ

• どの選択肢を採用するか、決め手は何か
• 採用によって何を諦めるか（受け入れるデメリット）
• 判断が割れた点、迷った点はどこか

観点5: 影響と結果

• ポジティブな影響（何が良くなるか）
• ネガティブな影響・リスク（何が難しくなるか、将来の負債になり得る点）
• 既存ADR・既存設計への影響（置き換え候補の検出につなげる）
• 撤回条件（どうなったらこの決定を見直すか）

深掘りのガイドライン

• ユーザーの最初の説明は「ざっくり」であることを前提に、遠慮なく根掘り葉掘り聞く
• 1つの回答に対して「なぜ？」「具体的には？」「それが満たされないとどうなる？」を最低1段は掘り下げる
• 暗黙の前提を明示化する（「〜が前提になっていますが合っていますか？」）
• ユーザーの発言を言い換えて確認する
• 選択肢が1つしか出てこない場合は、対抗となる選択肢を必ず提案して比較させる
• エッジケースや「もし〜だったら？」の視点を提示する
• 押し付けがましくならないよう、提案は選択肢の一つとして柔らかく提示する

AskUserQuestion 利用ルール

• 質問は AskUserQuestion を主体とし、ユーザーが選ぶだけで答えられる具体的な選択肢を用意する
• 1回の呼び出しで関連する質問をまとめる（最大4問）
• 選択肢には description で「選ぶとどうなるか・何を意味するか」を添える
• 推奨がある場合は先頭に置き「(Recommended)」を付ける
• 選択肢化できない深い理由・自由記述は、通常のテキスト対話で受ける

次のアクションを判断するルール

step3 を継続する条件（以下のいずれかに該当）

• ヒアリング観点のうち必須観点（背景と課題・検討した選択肢・決定理由）が埋まっていない
• 選択肢の長所・短所が曖昧、または裏付けがない
• ユーザーがまだ迷っている・追加で検討したい点がある
• 追加の調査が必要
• イテレーション回数が最大イテレーション未満

step4 に進む条件（以下のすべてに該当）

• 必須観点が埋まり、矛盾がない
• ユーザーが決定内容に納得している（「これで良さそう」「まとめて」等の発言、または確認への同意）

セッション終了条件

• イテレーション回数が最大イテレーションに達した場合、現状をまとめて step4 に進むことを提案する
• ユーザーが明示的に中断を希望した場合、セッションファイルに現状を保存して終了する

ADR番号とファイル名のルール

ADR番号

• 4桁ゼロ埋めの連番（0001, 0002, ...）
• 既存ADRのファイル名先頭の番号の最大値 +1 を使用する
• 既存ADRがない場合は 0001 から開始する

内容の英語化のルール

• 決定内容を簡潔な英語スラッグに変換する
• ケバブケース（kebab-case）を使用（ADRファイル名）
• セッションファイルはスネークケース（snake_case）を使用
• 最大40文字程度に収める
• 例:
• 「PostgreSQLの採用」 → use-postgresql
• 「認証方式をJWTにする」 → use-jwt-authentication
• 「モノレポへの移行」 → migrate-to-monorepo

timestamp の形式

• yyyyMMddHHmmss 形式（例: 20260706123456）

ファイルパスの記載ルール

• **プロジェクトルートを基準とした相対パスを使用する**
• フルパス（絶対パス）は記載しない
• 例:
• ❌ `/Users/username/projects/myapp/docs/adr/0001-use-postgresql.md`
• ✅ `docs/adr/0001-use-postgresql.md`

ステータスのルール

ADRのステータスは以下の5種類とする：

| ステータス | 意味 | |-----------|------| | ドラフト | 起案中。本コマンドが出力する初期状態 | | 提案済み | 起案者が署名し、レビュー・承認待ち | | 承認済み | 承認者が署名し、有効な決定として確定 | | 廃止 | 決定が無効になった（置き換えなし） | | 置き換え | 新しいADRによって置き換えられた |

• 本コマンドは常に「ドラフト」で出力し、ステータス変更はユーザーが行う
• 置き換え対象の旧ADRのステータス更新は、新ADRが「承認済み」になった時点でユーザーが行う（step6 で案内する）

info

<session_template>

ADR壁打ちセッション

**開始日時**: {{開始日時}} **最終更新**: {{最終更新日時}} **トピック**: {{トピック}} **予定ADR番号**: {{ADR番号}}

---

検討内容の概要

{{検討したい決定事項の概要}}

---

対話ログ

イテレーション 1 ({{日時}})

**質問した観点**: {{観点}}

**ユーザーの回答・発言**:

• {{回答の要点}}

**深掘りで明らかになったこと**:

• {{要点1}}
• {{要点2}}

---

（イテレーションごとに同様の形式で追記）

---

整理されたヒアリング結果

背景と課題

{{背景と課題}}

制約条件

• {{制約1}}
• {{制約2}}

検討した選択肢

1. **{{選択肢A}}**

• 長所: {{長所}}
• 短所: {{短所}}

2. **{{選択肢B}}**

• 長所: {{長所}}
• 短所: {{短所}}

決定と理由

{{決定内容と決め手}}

影響・リスク

• {{影響1}}
• {{影響2}}

---

調査結果

調査1: {{調査のタイトル}}

• **目的**: {{目的}}
• **方法**: {{コードベース調査 / WebSearch 等}}
• **結果**: {{結果}}