技術的な意思決定を壁打ちしながら構造化し、ADR（Architecture Decision Record）として記録するスキル。アーキテクチャ選定・ライブラリ選択・設計方針の決定が必要なとき、「なぜこの設計にしたか」「他に何を検討したか」を残したいとき、過去の判断を記録したいとき、技術的な迷いを壁打ちで整理したいときに使う。「〇〇にしたんだけど記録残したい」「AとBで迷ってる」「ADR書いて」「なぜこうしたか残したい」「設計の意思決定を文書化したい」「技術選定を記録したい」「判断の根拠を残したい」「なぜこのアーキテクチャにしたか」「ライブラリを選んだ理由を残したい」「不採用にした根拠を記録したい」といった場面でも必ず使う。

ADR Capture — 技術的意思決定の記録

技術的な意思決定を壁打ちで引き出し、後から参照・再評価できる ADR（Architecture Decision Record）として記録する。白紙から書く負担をなくし、「話しながら記録される」体験を提供する。

いつ使うか

アーキテクチャ・ライブラリ・設計方針の選択に迷っているとき（決定前）
技術的な判断をしたが、根拠をどこにも残していないとき（決定後）
「なぜこうなったか」を後から問われても答えられるようにしたいとき
過去の判断を ADR として掘り起こしたいとき
チームメンバーへの設計説明コストを下げたいとき

このスキルがやらないこと

ADR を外部発信コンテンツ（LT・ブログ等）に変換する（別スキルの責務）
ADR の保存先を決定・管理する（Markdown を出力するのみ）
コードそのもののレビューや設計提案

推奨モデル

入力の状態	推奨モデル	理由
曖昧・相談ベース（「AとBで迷ってる」「〇〇にしたんだけど…」）	Opus	壁打ちの質問力がコア価値。曖昧な入力から根拠・代替案を引き出すには深い推論が必要
具体的・ショートカット（「ADR書いて。〇〇にした、理由は△△」）	Sonnet	テンプレート整形が中心。情報が揃っていれば instruction following で十分
カタログ管理（一覧・検索・Status 更新）	Sonnet	ファイル読み取り + パターンマッチが中心

入力パターンの分類とフロー

受け取った入力を以下のパターンに分類し、対応するフローへ進む:

パターン	判定基準	フロー
ショートカット	Decision・Rationale・Alternatives の3つが揃っている	壁打ちスキップ → 即 ADR 生成
決定後	「〇〇にした」「採用した」「選んだ」	根拠・代替案を引き出す壁打ち → ADR 生成
決定前	「〇〇と△△で迷ってる」「どちらがよいか」	選択肢整理 → 決定支援 → ADR 生成
掘り起こし	「記録が残ってない」「当時の判断を…」	記憶の再構成 → ADR 生成
カタログ管理	「ADR一覧」「再評価」「Status更新」	カタログ管理フローへ

壁打ちフロー（ADR 生成）

Step 1: 判断の受け取りとショートカット判定

入力からパターンを判定する。ショートカット判定の場合は Step 2 をスキップして Step 3 へ進む。

引数でテーマが渡された場合はそれを起点に展開する。引数なしの場合は「どんな技術的な判断について記録しますか？」から始める。

Step 2: 意思決定の引き出し（最大 2 ラウンド）

以下の優先順で情報を引き出す。すでに語られている情報はスキップ:

何を決めたか / 決めようとしているか（必須。これがないと ADR にならない）
なぜそう判断したか / 判断しようとしているか（必須。根拠のない ADR は無価値）
他に何を検討したか（重要。「なぜ A ではなく B か」は後から最も参照される情報）
前提条件は何か（あれば。前提が変われば判断も変わることを記録する）
いつ見直すべきか（Revisit Trigger。前提が変わる条件を1〜3個。情報がない場合は ADR 生成後に仮の条件を入れてユーザーに確認する）

質問ループの制御: AskUserQuestion は 最大 2 ラウンド（計 4〜6 問） に制限する。2 ラウンドで情報が揃わない場合は、不足部分を会話の文脈から推測し仮説ベースで ADR を生成してから確認する。質問攻めでテンポを崩さないことが優先。

掘り起こしの場合のフロー:

「いつ頃その判断をしましたか？」（時期の確認）
「当時どんな状況でしたか？チーム規模・制約など」（文脈の再構成）
「なぜ他の選択肢ではなくそちらにしたんですか？」（根拠の言語化）
通常フロー（1〜5）で残り情報を補完して ADR 生成へ

決定前の相談の場合のフロー:

各選択肢のメリット・デメリットを整理する
ユーザーの最重要基準（コスト・学習コスト・将来性・依存リスク等）を1つ確認する
基準に照らして優位な選択肢を提示し、ユーザーの判断を促す
ユーザーが決定したら通常フロー（5番目: Revisit Trigger）を確認してから Step 3（ADR 生成）へ進む

プロジェクトコンテキストの活用（Claude Code 環境のみ）: 以下が利用可能であれば壁打ちの精度向上のために参照する。いずれも必須ではない:

ソース	活用方法
AGENTS.md / CLAUDE.md	技術スタック・規約を把握し、判断の文脈を理解する
Package.swift / build.gradle 等	依存ライブラリを把握し、選択肢の妥当性を評価する
既存の ADR	過去の判断との整合性を確認。矛盾があれば指摘する
ディレクトリ構成	アーキテクチャの現状を把握し、判断の影響範囲を推定する

Step 3: ADR の構造化出力

壁打ちの結果を ADR テンプレートに整形して出力する（テンプレートは references/template.md を参照）。

ADR の粒度判定:

大きな判断（アーキテクチャ・フレームワーク選定等）→ フルテンプレート（Context・Consequences 含む）
小さな判断（ライブラリのバージョン固定等）→ 必須セクションのみの軽量 ADR

ファイル名規則: NNNN-<短いタイトル-in-kebab-case>.md（例: 0001-adopt-mvvm-clean-architecture.md）

採番ルール:

出力先ディレクトリに既存 ADR がある場合: 最大番号 + 1 を自動採番
ない場合: 0001 から開始
ユーザーが番号を指定した場合: それに従う

出力先の決定:

Claude Code 環境 + ADR ディレクトリが特定できる場合: 「{path}/{filename}.md に書き出しますか？」と確認してから Write で書き出す
それ以外: テキスト出力（ユーザーが手動でコピー・保存）

（オプション）関連 ADR のリンク提案: Claude Code 環境で既存 ADR が存在する場合のみ、Tags をもとに関連 ADR を自動検出し、リンクを提案する（強制ではなく提案にとどめる）。

ADR カタログ管理

「ADR 一覧」「ADR を見せて」等のリクエスト時:

対象ディレクトリを確認（不明な場合はユーザーに確認）
各 ADR の YAML フロントマター（status, date, tags フィールド）と H1 タイトルのみ読み取る（本文は読まない）。番号はファイル名の先頭4桁（NNNN-xxx.md）から取得し、ファイル名に番号がない場合は H1 タイトル（# NNNN: …）から取得する
以下の形式で出力:

| # | タイトル | Status | Date | Tags |
|---|---------|--------|------|------|
| 0001 | MVVM + Clean Architecture の採用 | Accepted | 2026-01-15 | architecture |
| 0002 | TCA の不採用 | Accepted | 2026-01-15 | architecture, library |

30 件を超える場合は Tags・期間でフィルタを促す。

Status の更新: ADR の再評価で判断が変わった場合は、新しい ADR を作成し、古い ADR の Status を Superseded by NNNN に更新する。

Revisit Trigger の評価

「ADR の再評価チェックして」「Revisit Trigger を確認して」等のリクエスト時:

対象ディレクトリの全 ADR を確認
各 ADR の ## Revisit Trigger セクションを読み取り
現在の状況と突合し、条件を満たすものを一覧で報告する
- Claude Code 環境: プロジェクトコンテキスト（CLAUDE.md 等）から現状を把握する
- 不明な場合: 「現在のチーム規模や技術的な変化があれば教えてください」と確認する
再評価が必要なものに対して「新しい ADR として整理しますか？」と確認

フォールバック

状況	対処
何を決めたかが不明確	「何について判断しようとしていますか？」から始める
代替案が出てこない	「他に何か検討しましたか？なければ "検討なし" で OK です」と伝えて先に進む
決定したかどうかが不明	「まだ迷っている感じですか？それとももう決まりましたか？」と確認
既存 ADR が読み取れない	壁打ち + ADR 生成のみ実行。「既存の ADR があれば貼ってください」と依頼
ADR ディレクトリが不明	「ADR を保存するディレクトリはどこですか？（例: docs/adr/）」と確認
大量の既存 ADR がある	Tags や期間でフィルタをかけてから処理する
2 ラウンドで情報が揃わない	仮説ベースで ADR を生成し、出力後にユーザーに確認する
Write ツールが失敗した場合（権限エラー等）	テキスト出力に切り替え、ユーザーに手動保存を依頼する
「決定前」パターンでユーザーが決断できない	「今日決める必要はありますか？ `Status: Proposed` で判断中 ADR を記録することもできます」と提案

adr-capture