awesome-design-doc

設計ドキュメント／ADR

機能リクエストやアーキテクチャに関する質問を、チームが実行でき、将来の読者が経緯をたどれる決定事項にまとめます。基本となる原則は、コンポーネントより先に要件と数値を、推奨案より先に実際の代替案を示し、最後には必ず推奨案を示すことです。選択肢を紹介するだけで選ばない文書は、設計ドキュメントではなく会議の議題です。

使用するタイミング

• 「X を設計して」「Y はどのように構築すべきか」「設計ドキュメント／ADR／RFC を書いて」。
• レビュアーが、ADR が必要な重要な決定を指摘した場合（awesome-code-review がこの形式を案内します）。
• 信頼できるアプローチが 2 つあり、選択を後から覆すのに大きなコストがかかる場合。

命名やヘルパーの配置場所など、日常的で変更しやすい選択には使用しないでください。そうした選択に ADR を作成してもノイズになります。以下の 3 条件のテストで判断してください。

ADR が必要な場合

次の 3 つすべてを満たす場合にのみ、ADR を作成してください。

1. 変更を後から覆すのに大きなコストがかかる — スキーマ、公開 API の形状、永続化形式、イベント名、フレームワーク／ストレージの選択、サービス境界。
2. 境界をまたぐ — 複数のモジュール、チーム、またはサービスが、その決定に従う必要がある。
3. 背景が失われる — 6 か月後には、コードから「なぜそうしたか」をたどれなくなる。

単一の決定には 1 ページの ADR を使用します。機能にデータモデル、API の範囲、ロールアウト計画がまとめて必要な場合は、完全な設計ドキュメントを作成してください。

作業プロセス

1. コンポーネントの前に要件を定める — 機能要件はテスト可能な記述とし、それぞれに文書のほかの箇所から参照できる固定ラベルを付けます。必須要件と望ましい要件は分けて記載し、続いて設計を左右する制約を示します。想定規模（ユーザー数、QPS、データ量と増加率）、レイテンシ目標、一貫性の要件（書き込み後に読み取り可能でなければならないもの、遅延してもよいもの）、可用性への期待、コンプライアンス上の境界、成果物の運用・保守を担う人 — チームがすでに運用方法を把握しているものも、ほかの制約と同じく制約です。スコープを誤ると、技術的に見事な設計でも間違った問題を解くことになります。設計の前に、ユーザーに確認してください。設計の後ではありません。名前を付ける前に、すでに記録された決定（既存の ADR）とプロジェクト独自の用語集を確認してください。コードベースにすでにある概念を別の名前にする設計は、読者全員に読み替えの手間をかけさせます。また、承認済みの ADR と黙って矛盾する設計は、ここで決着する代わりにレビューで再び議論になります。
2. 概算で負荷を見積もる — リクエスト数／秒、年間ストレージ量、ワーキングセットのサイズ、アクションごとのファンアウト。3行の計算で、図よりも多くの悪い設計を退けられます。数値のない設計は雰囲気にすぎません。前提を明記し、前提が古くなったときに読者が計算をやり直せるようにしてください。その規模での月々の運用コストを1行で示し、最も大きな費目も記載してください。価格表ではなく、同じ計算から得られる桁の概算にします。
3. 内部構造より先に契約を描く — API のエンドポイントまたはイベントの入出力と、データモデルの中核となるエンティティおよびその不変条件を示します。契約を明らかにすれば、スコープの誤りをまだ修正コストの低いうちに見つけられます（HTTP リソースの詳細は awesome-api-design を参照）。まずコードに基づいて検討します。同種の既存実装の中で最も近いものを探し、契約変更が影響するすべての呼び出し元またはコンシューマーを、記憶ではなく検索によって洗い出して列挙してください。既存のパターンと並行して別のパターンを導入する設計では、既存のパターンでは対応できない理由を説明し、見つかったすべてのコンシューマーをロールアウト計画に含めます。
4. 真に異なる代替案を2～3個作成する — 実現可能な最も単純な方法も含めます（「何もしない」や「cron ジョブとテーブル」が有力候補になることもよくあります）。退けるためだけに加えた代替案は水増しです。それぞれの案について、最も有利な点を正直に示します。
5. 要件によって重要になるトレードオフの軸で評価する — 固定の評価基準ではありません。一貫性と可用性、同期と非同期、SQL と NoSQL、モノリスの拡張と新規サービス、内製と購入、レイテンシとコスト、チームがすでに運用している技術とチームにとって新しい技術などです。重要な各軸について、要件がどちらを支持するか、その理由を述べます。チームの誰も運用できない代替案は、技術的な軸だけでは優位になりません。緊張関係のない軸は省きます。水増しは、分析の要点を薄めます。
6. 要件に基づいて推奨する — 推奨は1つに絞り、判断を左右した要件にラベルを付けて結び付けます（「フィードでは30秒の遅延が許容されるため、結果整合性で十分です。これにより、より安価な読み取り時ファンアウトが可能になります」）。どのような新情報があれば判断が覆るか、また設計の限界も明記します。限界については、機能しなくなるステップ2の数値、最初に破綻するコンポーネント、そのときの次の対応を1文で示し、段階的なロードマップにはしません。不明点によって代替案間で選択が変わる場合は、推測で埋めないでください。文書に、期間を区切ったスパイク（検討）の実施を定めます。そこには、1つの質問、完了条件、判断日、どの結果ならどの代替案を選ぶかを記載し、回答が出るまで「未解決の質問」に残します。
7. 緩和策を考える前に逆向きに検討し、その後、非目標と道筋を示す — まずリスク評価を逆向きに行います。1年後、この判断が誤りだったと分かり、設計を取り消している状況を想定します。失敗の原因を3つ、具体的に挙げます（「バックフィルが完了せず、書き込み結果が分岐した」など）。「スケーリングのリスク」のような抽象的な表現は避けてください。前向きの検討では合理化されて見過ごされることも、逆向きに考えれば浮かび上がります。「何が失敗の原因になるか」という問いに「慎重に対応する」とは答えられないからです。挙げた各原因について、読者が実際に観測できる早期警告の兆候を示し、緩和策を講じるか、リスクを受け入れる旨を明記します。続いて、明示的な非目標（あえて解決しないこと。スコープクリープが生じた際に、文書の一文を根拠に議論できるようにする）、主要なリスクとその緩和策、既存データとコンシューマーの移行・ロールアウト順序、ロールバック方法を示します。段階的にロールアウトできない設計なら、PR の段階ではなく、ここでその旨を明らかにします。ロールバック基準は事前に数値で定めます。指標、しきい値、観測期間を明記し、各ロールアウト期間で確認する観測可能なシグナルも示します。これにより、インシデントの最中に議論する事態を防げます。後戻りできなくなる地点も明示します。契約に関わる手順（カラムの削除、旧経路の削除など）を実行した後、または新形式で最初の書き込みが発生した後は、ロールバックではなく前進による修正が必要になります。その地点を過ぎた後の対応を文書に記載します。

ADR 形式

# ADR-<n>: <decision, stated as a decision>
Status: proposed | accepted | superseded by ADR-<m>
Date: <date>

Context: <the forces — requirements, constraints, numbers — that make this a decision at all>
Decision: <what we will do, one paragraph, active voice>
Alternatives considered: <each with its honest best case and why it lost against the requirements>
Consequences: <what becomes easier, what becomes harder, what debt is accepted knowingly>
Non-goals: <what this decision deliberately does not cover>

エージェント向けブリーフ（決定を実装担当者に引き継ぐ場合）

設計ドキュメントは決定内容を読者に説明するものですが、ブリーフは実装担当者（人または無人で動作するエージェント）に何を作るべきかを伝えるものです。同じセッション内で実装せずに作業を引き継ぐ場合は、作業単位ごとにブリーフを作成し、待ち時間に耐えられる内容にしてください。コードベースがその間に変化する中で、ブリーフが何日も置かれることがあります。

精密さよりも耐久性を重視します。インターフェース、型、設定の形式、動作上の契約を説明してください。古くなり、存在しなくなったファイルへ実装担当者を導くファイルパスや行番号は記載しないでください。コードを「どのように」変更するかではなく、システムが「何を」すべきかを記述してください。実装担当者が現在のツリーを調べ、自ら実装方法を決定します。

## Brief: <one-line summary of what must happen>

Category:          feature | bug | migration
Current behavior:  <what happens today — the status quo the work builds on>
Desired behavior:  <what happens after, including edge cases and error conditions>
Key interfaces:    <the types, signatures, events or config shapes that change, and how>

Acceptance criteria:
- [ ] <requirement label> <specific, independently verifiable — "returns 409 on a duplicate
      idempotency key", not "handles duplicates correctly">

Out of scope:      <the adjacent thing that must NOT be touched, so gold-plating has to argue>

決定が複数のブリーフに分かれる場合は、依存関係の順に公開し、それぞれのブリーフで先行するブリーフを明記してください。そうすれば、ドキュメントを読み直さなくても、着手可能なブリーフを把握できます。

出力

設計ドキュメント全体：タイトル → 問題と要件（番号付き） → 提案する設計（契約を先に、その後に内部構造） → 代替案とトレードオフ → 推奨案 → 対象外事項 → リスクと軽減策 → ロールアウトとロールバック → 未解決の質問（明示し、隠さない）。リポジトリのドキュメント規約に従った Markdown ファイルとして作成してください（docs/adr/、docs/design/、または既存ドキュメントの保存場所を使用します。独自に作らず、見つけてください）。ファイル名は追加先フォルダーの規約に従います。連番が付いている場合は、すでにディスク上にある番号ではなく、次の空き番号を使ってください。また、新しいドキュメントで既存のドキュメントを上書きしてはいけません。別の設計ドキュメントに置き換える場合は、その旨を本文で明記し、レビュー担当者がリンクした旧ファイルはそのまま残してください。

提出前のセルフチェック

まず機械的な部分を済ませて、以下を読む時間はプレースホルダー探しではなく判断に使いましょう。各行は、現時点の文書について「はい」か「いいえ」で答える項目です。どのように確認するかは自由です。読み返す、検索する、あるいはこの文書専用の使い捨てチェックを書いて、確認後に破棄してもかまいません。

ブロッキング項目：以下のいずれかに該当する文書は、引き渡せる状態ではありません。

• 本文中にプレースホルダーが残っていないこと：TBD、TODO、FIXME、出典が必要であることを示すマーカー、lorem ipsum、「ここに入力」、角括弧で囲まれた 、続きの記載へと文が途切れている箇所。
• 完全版の文書には、要件または課題、設計または提案、代替案、推奨または決定、対象外事項、リスク、展開またはロールバックの各セクションがあり、それぞれに本文が記載されていること。見出しだけのセクションは認められません。ADR には Status、Context、Decision、Alternatives considered、Consequences があり、どの項目も空欄でないこと。
• ADR のステータスは proposed、accepted、superseded のいずれかであり、それ以外ではないこと。
• 代替案が2つ以上あり、リスト項目または表の行として数えられること。1つの選択肢に触れた段落は、どれだけ長くても代替案1つとして数えます。
• 受け入れ基準がある場合、各要件ラベルが少なくとも1つの基準でカバーされており、各基準が要件セクションで実際に定義されているラベルを参照していること。

警告項目：それぞれに回答するか、明示的に対象外とします。

• 冒頭の3分の1に、少なくとも1つの数値が記載されていること。数量を示していないコンテキストでは、課題を述べたことになりません。
• リスク（またはADRの帰結）に、早期警告、つまりリスクが顕在化した場合に読者が観察できる事象が記載されていること。
• 完全版の文書に、明示的に示された未解決の質問セクションがあること。

次に、どのチェックでも決められない判断事項です。

• 「3条件テスト」の結論を1行で記載し、なぜこの決定を文書化する価値があるのかを説明します。
• 各規模の数値が、読者が再現できる形で明記された前提に基づいていること。前提のない数値は、数字を付けただけの感覚にすぎません。
• 推奨事項を示し、その根拠となった要件をラベルで参照し、どのような新情報があれば判断が覆るかを述べ、最初に破綻するコンポーネントとともに上限を明示します。
• それぞれの代替案を支持者の立場から読み直します。最善の条件でも成り立たない案は藁人形なので、差し替えるか削除します。
• リスク一覧が、軽減しやすいものからではなく、逆算して洗い出したものであること。各リスクに読者が観察できる早期警告を記載し、軽減策がないリスクは削除せず、受容すると明記します。
• ロールバックには、数値によるトリガー（指標、しきい値、期間）と、不可逆点、およびその点を過ぎた場合に起こることを記載します。代替案の選択を左右する未知の事項は、推測ではなく日付を定めたスパイクにします。
• 対象外事項、ロールバック、明示された未解決の質問を含めます。確認されておらず、独自に設定した要件は、未解決の質問に移すか削除します。

アンチパターン

アンチパターン	代わりに行うこと
コンポーネント選び — 要件を定める前に技術を挙げる	まず要件と数値を示し、そこから技術を導き出します
推奨のないトレードオフの列挙	比較の最後に、要件に結び付けた推奨事項を必ず示します
藁人形の代替案	各代替案が敗れる前に、正当な最善の主張を示します
要件の捏造（「マルチリージョンが必要になるかもしれない」など）	明示または確認された要件のみを扱い、推測は対象外事項に記載します
ADR の乱発 — 元に戻せる選択ごとに文書を作る	3条件テストを使い、元に戻せる選択はコードコメントに記載します
展開計画のない設計	移行順序、後方互換性、ロールバックを文書に記載します
リスクを順方向に列挙し、それぞれに安心できそうな軽減策を添える	まず逆算し、何が破綻させるのかを挙げてから、挙げた原因を軽減します
未解決の質問を、記載しないことで暗黙に解決する	読者が回答できる明示的な未解決の質問セクションを設けます