ADR (Architecture Decision Record) 作成スキル

特定の課題に対する設計判断を、後から読んだ人が「なぜその判断に至ったか」を追体験できる形で記録する。単なる決定事項の記録ではなく、比較検討のプロセスそのものを残すことが目的。

スコープ：アーキテクチャレベルであって実装レベルではない

ADR の "A" は Architecture の略であり、対象はシステムの構造・境界・非機能特性に関わる意思決定である。特定のコードの書き方や関数の実装詳細には踏み込まない。

判定の目安: 「この決定を変えると、コンポーネント間の責務分担・システム境界・チーム間のインターフェースに影響するか？」に Yes と答えられるものがアーキテクチャレベル。「特定の関数・クラス・モジュールの内部で完結し、外部からは見えない実装の詳細か？」に Yes と答えられるものは実装レベルであり、ADR の対象外。

課題を受け取った時点でこの表の右側（実装レベル）に寄っている場合は、ADRを書く前にユーザーに「これはアーキテクチャレベルの意思決定というより実装の詳細に見えるが、ADR化する意図があるか」を確認する。あるいは、実装レベルの相談を一段抽象化し、「その実装を成立させるためにどのようなアーキテクチャ上の前提・制約があるか」という論点に引き上げられないか検討する。

このスキルの核となる原則

1. 1つのADRにつき、決定する課題は1つ、結論も1つに限定する。 課題を検討する過程で生じる複数の論点・観点（実装方式、パフォーマンス、運用コスト、可逆性など）は、1つの決定を多面的に評価する軸であり、別のADRに分割しない。多角的に検討した跡はむしろ検討の質を示す証拠であるため、観点を削るのではなく、検討内容・検討結果の中ですべて扱いきる。Architectureに絶対的な正しさは存在せず、どの案を選んでもどこかにリスクは残る——検討結果では「どのリスクをなぜ許容するか」を1つの結論として明示する。ただし、そもそも前提や制約が別物で互いに影響しない独立した決定（=本当は別の課題）である場合は、論点の分割ではなく最初から別の課題として別のADRを起票する。
2. 結論ありきで書かない。 検討内容（選択肢の比較）を先に書き終えるまで、どの案を採用するかを本文に書かない。検討結果セクションで初めて決定を下す。
3. 課題に対する解決案を必ず複数出す。 課題そのものを解決しうる具体的な案を複数用意する。1つの観点だけを解決する部分的な案を並べるのではなく、課題全体への解決策として案を立てる。1案しか思いつかない場合でも、「何もしない（Do Nothing）」案や「最小実装」案など、最低でももう1案を比較対象として立てる。
4. メリット・デメリットは同じ熱量で書く。 採用予定の案だからといってデメリットを薄める、不採用の案だからといってメリットを削る、といった非対称な書き方をしない。
5. デメリットが思いつかない案は検討不足を疑う。 運用負荷・学習コスト・依存関係の増加・パフォーマンス・可逆性（後で変更しやすいか）・チームの習熟度などの観点から、実務上のデメリットを最低1つは洗い出す。
6. 決定の根拠は比較結果に紐づける。 「検討結果」で書く採用理由は、「検討内容」で挙げた具体的なメリット・デメリットを参照する形にする。根拠のない断定（「Bの方が良いため」だけで終わる等）は避ける。
7. 図は文章の代わりにならない。 Mermaid図はあくまで構造・流れの理解を助ける補助であり、メリット・デメリットの比較や決定根拠は必ず文章（表）で書く。図だけで済ませない。

ワークフロー

ステップ1: 課題を理解する（推測で進めない）

ユーザーから課題を受け取ったら、以下が揃っているか確認する。足りない場合は先に調査・質問する。

• 何が問題か（現状の課題・きっかけ）
• なぜ「今」決定が必要か
• 既知の制約条件（期限、技術スタック、互換性など）
• 対象システムの現状のコード・構成（リポジトリ内に情報があれば読む。曖昧なまま進めない）

ここが曖昧なまま「検討事項」に進むと、後段の比較が的外れになりやすい。不明点はユーザーに確認するか、リポジトリ内のコード・既存ドキュメントを調査してから進める。

ステップ2: 課題を評価する観点を洗い出す

課題を検討する上で考慮すべき論点・観点（例:「リトライ戦略」という課題なら、実装方式・リトライ上限回数・待機時間アルゴリズムなど）を洗い出す。これらは1つの決定を構成する複数の側面であり、論点ごとに別のADRへ分割したり、論点ごとに別々の結論を出したりしない。多面的に検討した論点は、後述の検討内容・検討結果の中でまとめて扱いきる。

• 洗い出した論点・観点は「検討事項」セクションに列挙し、案を評価する軸として明示する
• 「検討内容」で比較する各案（案A/B/Cなど）は、洗い出した観点すべてに触れる完結した提案にする。特定の観点だけを見た部分的な提案にしない
• 観点の数が多すぎて1つの決定として扱いきれない場合（例: 明らかに担当チーム・意思決定のタイミングが別々で、片方の結論を後から完全に取り消しても他方に影響しない、など）は、それは論点ではなく実は独立した別の課題である可能性を疑う。その場合は論点の分割ではなく、最初から別の課題として別のADRを起票すべきかユーザーに確認する
• 検討事項が実装の詳細（特定のコードの書き方、関数の分割方法など）になっていないか確認する。実装レベルに寄っている場合は、「スコープ」節を参照し、アーキテクチャレベルの論点に引き上げる

ステップ3: 課題に対する解決案を複数立てて比較する（検討内容）

• 課題に対する解決案を、最低2案、できれば3案以上用意し、案ごとにメリット・デメリットを中立的に書く。
• 「一般的な代替パターンは何か」をまず考える（既知のデザインパターン、業界標準的なアプローチ、ライブラリ・フレームワークが提供する機能など）
• 判断に迷う場合や技術的な裏付けが必要な場合は、Web検索や既存コードの調査で事実確認してから書く（不確かなことを確かであるかのように書かない）
• 表形式（メリット/デメリットの2列）を使うと比較しやすい
• 各案は、ステップ2で洗い出した観点すべてに触れる。一部の観点にしか言及しない部分的な提案にしない
• この時点では「どれを選ぶか」に触れない
• 各案の説明は「どういう構造・責務分担・境界になるか」を軸にする。具体的なコード例や関数実装まで書き始めたら実装レベルに脱線しているサイン
• 案の構造・処理の流れ・状態遷移が文章だけでは伝わりにくい場合は、案ごとにMermaid図を添える（詳細は後述の「図解（Mermaid）を使う場面」を参照）

ステップ4: 検討結果を決定する

検討内容の比較結果をもとに、採用案と根拠を決める。複数の観点を検討した場合でも、結論は1つに絞る。

• 根拠は検討内容で挙げた具体的なメリット・デメリットに対応させる
• 採用案が抱えるリスク・デメリットのうち、受け入れることにした点（トレードオフ）を明示する。「絶対的に正しい案」としてではなく、「このリスクは許容できると判断した案」として書く
• 迷いがある場合は「暫定的にAを採用するが、Xの条件が変わればBを再検討する」のように正直に書いてよい（完璧な結論である必要はない）

ステップ5: テンプレートを埋めてファイルを出力する

templates/adr-template.md を元に、Markdownファイルを作成する。

• ファイル名・番号の付け方: リポジトリ内に既存の ADR（例: docs/adr/0001-xxx.md のような連番ファイル群）があれば、その最大連番の次の番号を使う。見つからない場合はユーザーに保存先ディレクトリと採番ルールを確認する。ファイル名は NNNN-短いタイトル-kebab-case.md の形式にする。
• ステータス: 特に指示がなければ「提案中」とする。ユーザーが「もう決定済み」と言えば「承認」にする。
• 出力後、以下を明示的にユーザーに伝える（断定しない）:
  • 今回の検討は現時点の制約に基づくものであり、前提が変わればADR自体を更新・廃止（Superseded）してよいこと
  • 検討事項のうち、特に不確実性が高い・追加調査が必要な箇所があればそれも一言添える

図解（Mermaid）を使う場面

図は必須ではない。文章・表による比較（メリット/デメリット、決定根拠）を省略・簡略化する目的で図を使わないこと。 以下のように、構造や時間的な流れを言葉だけで説明すると読み手の負荷が高い場合にのみ追加する。

図を入れる場所の目安:

• 課題の内容・背景: 現状構成（As-Is）を示す図。複雑な既存構成を理解してもらう目的。
• 検討内容の各案: 案ごとの構成・処理フローの違いが視覚的に分かりやすい場合、その案の小見出し直下に図を1つ添える（全案に無理に揃える必要はない。分かりやすい案にだけ入れても良い）。
• 検討結果: 採用が決まった構成（To-Be）を示す図。複数の観点を踏まえた決定後の全体像を、文章だけでは伝えにくい場合に有効。

記法上の注意:

• コードブロックは ```mermaid で開始する（GitHub・多くのMarkdownビューアでそのままレンダリングされる）。
• 図中のラベルは日本語で統一し、本文の用語（案A/案Bなど）と一致させる。
• Mermaid Chart のツールが利用可能な場合は、埋め込む前に構文が正しくレンダリングされるか検証してから本文に貼る。利用できない場合は、Mermaidの基本文法（ノード定義とエッジの対応、ラベルのクォート漏れなど）を自己点検してから記載する。
• 図が複雑になりすぎる場合（矢印が多すぎて読みにくい等）は、図を分割するか、無理に1枚に収めず文章での説明を優先する。
• Mermaidのコードブロックを <!-- --> で丸ごとコメントアウトしないこと。 flowchart系の矢印 --> はHTMLコメントの終了記号と同じ文字列のため、コメント内に含めると意図せずコメントがそこで終了し、Markdownが崩れる。図を任意にしたい場合は、コードブロックの直前に矢印を含まない説明コメント（例:「不要ならこのコードブロックを削除してよい」）を置き、コードブロック自体はコメントで囲まない。

テンプレートの構成（templates/adr-template.md）

テンプレートの {{ }} は埋めるべきプレースホルダー。案の数（案A/B/Cなど）は増減してよいが、最低2案は必須。

出力時の注意

• 標準の Markdown ファイル(.md)として出力する。分量が多い場合(>1500文字目安)はファイル成果物として作成し、単なる会話用の短い確認であればそのままチャットで見せてもよい。
• 表や箇条書きは日本語で統一する（ユーザーの言語に合わせる）。
• 検討事項に複数の論点・観点を挙げた場合でも、検討結果は1つの結論にまとめる。論点ごとに結論を分けて書かない。
• Mermaid図を入れた場合は、図の直後に1〜2文で「この図が何を示しているか」を文章で補足する（図だけを貼って終わらせない）。