architecture-decision-record

アーキテクチャ決定記録（ADR）スキル

このスキルは、最も広く採用されている標準である Nygard 形式に従って、完全なアーキテクチャ決定記録（ADR）を作成します。ADR には、重要な技術的決定の背後にある理由を記録します。これにより、将来のチームメンバーが、何が決定されたかだけでなく、なぜ決定されたかも理解できます。

必須入力

与えられた情報をもとに作成してください。以下の情報が不足している場合も、完全な出力を作成してください。不足箇所には妥当な仮定を (仮定、要確認) と明記し、最後に仮定の一覧を記載してください。中核となる題材そのものが欠けている場合（書くことが何もない場合）に限り、まず質問してください。

• ADR 番号（ADR レジストリの連番。例：012。不明な場合は「次に利用可能な番号」）
• 決定のタイトル（簡潔なもの。例：「主要データストアとして PostgreSQL を使用する」）
• 背景（どのような状況から、この決定が必要になりましたか？）
• 検討した選択肢（少なくとも 2 つ。1 つしか提示されていない場合は、検討または却下した代替案を尋ねてください）
• 決定内容（どの選択肢を選びましたか？）
• 選択理由
• ステータス（提案／承認／廃止／置き換え）
• 作成者と日付
• チームの背景（任意。チームの規模、関連する経験、組織上の制約など。背景セクションの形式や詳しさを調整する際に役立ちます）

出力形式

---

ADR-[NNN]：[決定のタイトル]

日付： [YYYY-MM-DD] ステータス： [提案／承認／廃止／ADR-NNN に置き換え] 作成者： [氏名] 決定者： [最終決定権を持った個人またはチーム]

---

背景

[3～6 文。この決定を必要とした状況、制約、作用した要因を説明してください。解決する問題、関連するシステムの状態、チームの制約、スケジュール上のプレッシャー、または譲れない要件を含めてください。18 か月後にチームに加わり、事前の背景情報がない人に説明するつもりで書いてください。]

主な制約：

• [制約 1：例：「エンタープライズ顧客向けにオンプレミス環境へデプロイできる必要がある」]
• [制約 2：例：「チームに Go の経験がない」]
• [関連する制約を必要なだけ追加]

---

検討した選択肢

各選択肢について、以下を作成してください。

選択肢 [N]：[名前]

説明： [この選択肢がどのようなものか。1～3 文]

メリット：

• [メリット 1]
• [メリット 2]

デメリット：

• [デメリット 1]
• [デメリット 2]

却下した理由（選択しなかった場合）： [率直な理由]

---

決定

[選択した選択肢]を採用します。

[決定の理由を、平易な言葉で 2～4 文で説明してください。この段落だけを読んでも理解できるようにします。文書全体を読まなくても、決定内容が分かるようにしてください。]

---

結果

肯定的な結果

• [この決定によって可能になること、または改善されること]
• [軽減されるリスク]

否定的な結果／受け入れるトレードオフ

• [この決定によって手放すこと、または引き受けること]
• [発生する技術的負債や制限]
• [この決定が有効であり続けるために、今後満たす必要がある条件]

リスク

• [後になって、この決定が誤りだったと判明する要因]
• [この決定を再検討するきっかけとなる条件]

---

実装上の注意

[実装時に分かりにくい注意点がある場合、または実装者が参照する必要のある関連チケット／RFC がある場合に記載してください。ツールの選定だけで実装上の曖昧さがない場合に限り、省略してください。]

---

見直し日

[決定が恒久的であるか、明らかに最終決定である場合を除き、記載してください。「定期的に見直すべき」のような記述ではなく、「チームが 20 人を超えた場合、またはトラフィックが 1 日あたり 1,000 万リクエストを超えた場合に見直す」のように、具体的なきっかけを示してください。]

---

詳細資料

このスキルにはサポートファイルが含まれています。利用可能な場合は使用してください。

• references/decision-scoping.md — ADR に記録すべき内容（および「コンテキスト」に含めるべき内容）。出力を作成する際に適用してください。ここには、上記の手法の概要で簡略化されている判断基準と判断のポイントが記載されています。
• templates/adr.md — 品質チェック項目がインラインで含まれた、記入式の成果物テンプレートです。生成を任せるのではなく、自分で文書を作成したいユーザーにはこちらを提示してください。

採点基準（0～40）

このスキルの出力は、引き渡す前に採点してください。32 点以上がリリース品質です。

項目	0	5	10
コンテキストの再構成	読者がすでに問題やプレッシャーを理解している前提になっている	問題は述べられているが、要因（チームの制約、規模、期限、決定を迫る出来事）が欠けている	2 年後に読んだ人でも、コンテキストのセクションだけで判断内容を推測できる
選択肢の誠実さ	選択した案のみ、または却下した案が藁人形論法で書かれている	2 つ以上の案があるが、却下理由が循環論法（「要件を満たさなかった」）になっている	却下した案それぞれに実質的な強みがあり、コンテキストの要因に結びついた具体的な不採用制約が示されている
結果のバランス	結果がすべて肯定的	実務上の具体性がない、形だけの否定的な記述がある	否定的な結果に、実際に生じる負債、新たな運用負担、判断を維持するために必要な条件が明記されている
再検討のトリガー	リスクや見直し条件が記載されていない	「定期的に見直す」とあるが、測定可能な条件がない	判断を無効にする具体的かつ測定可能なトリガー条件と、その担当者が示されている

品質チェック

• コンテキストで「何をしたか」だけでなく、「なぜそうしたか」が説明されている
• 少なくとも 2 つの選択肢（却下した案を含む）が記録されている
• 却下した案に、誠実な不採用理由が含まれている
• 結果に否定的な影響が含まれている。どの判断にも結果が伴う
• Decision セクションに判断が平易な言葉で記載されている
• Risks セクションで、この判断を無効にする要因が特定されている
• コンテキストの最初の 1～2 文で問題が明確に述べられている（チームが解決しようとしていた問題を読者が知っている前提にしない）
• 却下した各案の「却下理由」に、具体的な制約またはトレードオフが記載されている（「要件を満たさなかった」のような循環論法にしない）

アンチパターン

• 判断がすでに完全に実装され、チームも次の作業に移っている段階で ADR を書かないでください。事後に書かれた ADR では、本当の理由や代替案が抜け落ちがちです。
• 選択した案だけを列挙しないでください。将来の読者にとって ADR で最も価値があるのは、却下した案とその誠実な理由です。
• 結果をすべて肯定的に書かないでください。あらゆるアーキテクチャ上の判断にはトレードオフがあります。否定的な結果がない ADR は、誠実に検討されていません。
• ステータスを「Proposed」のまま放置しないでください。誰にも承認されていない ADR は、誰の判断にも指針を与えません。
• 読者が解決対象の問題をすでに知っている前提のコンテキストを書かないでください。コンテキストのセクションは、その背景を知らない読者のためにあります。

使用例

• 「[technology] を使う ADR を書いてください」
• 「[architectural choice] に関する判断を記録してください」
• 「[topic] のアーキテクチャ決定記録を作成してください」
• 「[alternative] ではなく [option] を選んだ理由を文書にまとめるのを手伝ってください」

トリガーフレーズの例

• 「技術的な判断を記録してください。」
• 「ADR を書いてください。」
• 「アーキテクチャ上の選択を記録してください。」
• 「ある技術を選んだ理由を記録してください。」