過去のADR・Design Docからボトムアップに作った運用ガイドを公開します
AIエージェントで実装を進めるチームが増えるにつれ、意思決定の文脈がコードに残りにくくなっています。OpenAIが2026年2月に公開したHarness Engineering事例では、「エージェントがコンテキストとしてアクセスできないものは、実質的に存在しないも同然」という原則のもと、設計ドキュメントや意思決定ログをリポジトリのファーストクラスのアーティファクトとして扱うことを紹介しています。実装速度が上がるほど、「なぜこう作ったか」を意図的に残す仕組みの重要性は増しています。
私たちのチームでは、ADR・Design Docを30本以上書いてきました。この記事では、その実践から帰納的にまとめた運用ガイドをほぼそのままの形で公開します。トップダウンで策定したルールではなく、実際の運用実態から積み上げた羅針盤です。「いつ書くか」「何を書くか」「書かなくていいか」の判断で迷ったとき、少しでも参考になれば幸いです。
はじめに：このガイドの読み方
以下のガイドは、私たちが開発するSaaSプロダクトで、エンジニア10人弱のチームが運用してきた実態をベースにしています。プロダクトの特性やチームの文化によって最適解は異なるため、そのまま転用するというよりも、判断軸や事例の参考として読んでいただけると幸いです。
ガイドの構成は以下の通りです。ADR・Design Docそれぞれの役割の定義から始まり、「書くかどうか」の判断軸、セクション構成のサンプル、実際の事例紹介、よくあるパターンとTipsの順に続きます。最初から通して読んでも、気になるセクションから拾い読みしても使えるようになっています。
ADR・Design Doc 運用ガイド
このドキュメントはルールではなく羅針盤です。運用しながらブラッシュアップしていきます。 最終更新: 2026-03-17
1. このドキュメントの目的
- ADR・Design Doc を「いつ・何を・どこまで」書くかの迷いを減らす
- チーム内の運用実態を帰納してまとめたもの（トップダウンのルールではない）
2. 各フォーマットの役割
以下の定義は原典・参考文献をベースにしているが、このプロジェクトでの運用は 必ずしも原典に従う必要はない。実態に合わせてブラッシュアップしていく。
ADR（Architecture Decision Record）
参考文献: Documenting Architecture Decisions - Michael Nygard (2011)
- 対象: 単一のアーキテクチャ上の意思決定（1 ADR = 1 decision）
- 主な目的: 「なぜその決定をしたか」「どんな力学が働いていたか」「却下した選択肢は何か」を残す
- 対象となる決定の基準: システムの構造・非機能特性・依存関係・インターフェース・構築技術に影響を与えるもの（Nygard の定義）
- タイミング: 決定の前後どちらでも可。ただし決定の経緯が鮮度を持っているうちに書く
- 注意: 一度 accepted になったら原則変更しない。決定が覆った場合は新しい ADR を書いて旧 ADR を superseded にする
Design Doc
参考文献: Design Docs at Google - Malte Ubl
- 対象: 機能やシステム全体の設計（複数の意思決定を含む）
- 主な目的: 実装前にトレードオフを明示し、チームの合意を形成する。実装後は設計上の意思決定のアーカイブになる
- タイミング: 実装着手前。コードより文章の方が問題を安価に解決できる段階
- 形式の自由度: "Rule #1 is: Write them in whatever form makes the most sense for the particular project"（Google）。厳密なフォーマットは存在しない
- 注意: 実装後は積極的に更新しない。半端に更新された不正確なドキュメントになるくらいなら、アーカイブとして扱う
3. 書くかどうかの判断軸
以下のいずれかに当てはまる場合、ドキュメントを書くことを検討する。
ADR を書くサイン
- OSS・技術選定など複数案のトレードオフがある
- 手戻りコストが大きい意思決定である
- 「なぜこうしたか」を後から説明する場面がありそう
- PRコメントや口頭では流れてしまいそうな意思決定
- チーム全体の開発方針・コーディング規約に影響する
Design Doc を書くサイン
- 複数人が関わる機能・コンポーネントの設計
- 要件・仕様が曖昧で、書きながら整理したい
- レビュアーに実装方針を事前に共有したい
- 複数のステークホルダーの合意が必要
- ユーザーストーリー・成功指標・リスクを整理してから実装に入りたい
書かなくて良いかもしれないサイン
- PRコメントで完結する粒度
- 実装してみて後追いでADRを書いても経緯が十分伝わる
- 影響範囲が自分1人に閉じている
4. 何を書くか（セクション構成）
セクション構成は起票者の判断で自由に組み替えてよい。 以下はあくまで過去事例から抽出したサンプルであり、意思決定やテーマに応じてセクションを追加・省略して構わない。 「このセクションがないからダメ」ということはなく、読み手にとって必要十分な情報が伝わることが最も重要。
ADR
プロジェクトの実態として、全ADRが「ステータス → 背景 → 決定 → 理由 → 影響 → 代替案」の構成を踏襲している。 ステータスはチェックボックス形式（提案中 / 承認 / 否認 / 保留 / 廃止）で管理されている。
基本的な項目
| セクション | 内容 | プロジェクトでの傾向 |
|---|---|---|
| タイトル・ステータス | 提案中 / 承認 / 否認 / 保留 / 廃止 | チェックボックス形式で統一 |
| 背景・課題 | なぜこの意思決定が必要になったか | 関連Issueへのリンクを含む傾向 |
| 決定内容 | 何を選んだか | 実装方針・パッケージ構成まで踏み込むものもある |
| 検討した選択肢 | 却下した案と理由 | 比較表形式が多い。メリット/デメリットを明記 |
| 理由 | なぜその決定をしたか | 番号付きリストで構造化される傾向 |
任意で追加する項目（過去事例でのサンプル）
| セクション | 内容 | 過去事例での使われ方 |
|---|---|---|
| トレードオフ・影響 | 採用した案のデメリット・注意点 | メリット/デメリットに分けて記述する傾向 |
| 候補比較表 | 複数候補の横並び比較 | OSS・ライブラリ選定で頻出 |
| 図・ダイアグラム | Mermaid図、シーケンス図、ER図 | アーキテクチャ系で頻出 |
| DB・テーブル設計 | SQLやテーブル定義 | データモデルに影響するADRで記載 |
| 移行計画 | フェーズ分けした段階的移行 | 既存コードへの影響が大きい場合に記述 |
| UIスクリーンショット・比較 | 候補のUI比較画像 | ビジュアル面の比較が必要な場合 |
| 関連 | 関連Issue・ADR・設定へのリンク | 他ドキュメントとの関係を明示したい場合 |
Design Doc
プロジェクトにはテンプレートが存在し、Goals / Non-Goals / Background / User Stories / Success Metrics / Biggest Hypotheses / Risk・Pre-mortem / Functional Requirements / Alternatives Considered / Results / Appendix の構成が推奨されている。
基本的な項目
| セクション | 内容 | プロジェクトでの傾向 |
|---|---|---|
| Goals | この取り組みのゴール | 簡潔に1〜3行で記述 |
| Non-Goals | あえて含めないこと | スコープを明確にするために重要。「将来は対応するが今は含めない」の粒度で書く |
| Background | なぜ作るか | 課題の列挙と現状分析。PRDやIssueへのリンクを含む |
| User Stories | ユーザーの心境・動機 | ペルソナごとにシナリオを記述する傾向 |
| Functional Requirements | 機能要件 | Epic/タスク単位でスコープ・Done条件を定義する傾向 |
任意で追加する項目（過去事例でのサンプル）
| セクション | 内容 | 過去事例での使われ方 |
|---|---|---|
| Success Metrics | 何をもって成功とするか | 定量的指標の定義に有効 |
| Biggest Hypotheses | 最も検証したい仮説 | MVP方針の明確化に有効 |
| Risk / Pre-mortem | 失敗要因の事前分析 | 技術・ビジネスリスクの整理に有効 |
| Implementation Plan | 実装計画 | Epic単位での段階リリース計画。Design Docの中核になることが多い |
| Alternatives Considered | 検討した代替案 | 概要・メリット・デメリット・判断を簡潔に |
| MVP完了条件 | MVPの定義 | テンプレート外だが必要に応じて追加 |
| 技術設計 | アーキテクチャ・データモデル | テンプレート外だが必要に応じて追加 |
| Results | 実施後の結果 | 多くの場合、空欄のまま（アーカイブとして扱う傾向） |
5. 運用例（実際のプロジェクト事例）
※ 以下は過去の事例から抜粋。書いた経緯のコメント付き。
ADR の事例
事例1: ホワイトボード機能のOSSライブラリ選定
- どんな意思決定: ホワイトボード機能に採用するOSSライブラリの選定（7候補）
- なぜADRを書いたか: 7つの候補があり、AI親和性・ライセンス・実装コスト・PostgreSQL保存容易性など多軸での比較が必要だった。選定理由を残さないと後から追えなくなる
- どこまで書いたか: 11項目の詳細比較表、不採用理由の一覧表、ライセンス根拠リンク、UIスクリーンショット比較まで
- 実際に役立った点: 後続のDesign Docが「ADRで選定済み」と参照しており、後続の設計議論で選定理由に立ち戻る必要がなくなった
事例2: Cookie ベースで認証する
- どんな意思決定: JWT認証のトークン管理方式（Cookie vs localStorage vs メモリ）とセキュリティ設計
- なぜADRを書いたか: セキュリティに関わる決定で手戻りコストが大きい。将来のセキュリティレビュー時に参照できる必要があった
- どこまで書いたか: セキュリティ要件の分析、トークン管理戦略の詳細、自動リフレッシュの設計まで
- 実際に役立った点: 後続のMFA認証ADRが、このADRの認証基盤の上に設計を重ねており、決定の積み上げが機能した
事例3: Repositoryパターンの導入（保留）
- どんな意思決定: Repositoryパターンの導入によるデータアクセス層の抽象化
- なぜADRを書いたか: アーキテクチャの根幹に関わる意思決定だが、チームの学習曲線と開発速度への影響を考慮する必要があった
- 実際に役立った点: 「保留（Suspended）」ステータスで記録を残したことで、再検討する際の出発点になる。「書いたけど今はやらない」も立派な意思決定記録
事例4: シングルテナント環境の設計方針
- どんな意思決定: Enterprise顧客向けシングルテナント環境のリポジトリ管理・デプロイ・監視等の包括的な設計方針
- 実際に役立った点: 「人的リソースが限られるため運用コストの最小化を最優先する」という基本方針を冒頭で明示したことで、後続の個別判断の方向性が統一された
- 課題: 1つのADRに多くの決定を含んでおり、Design Docとして書いた方が構造的だった可能性がある。ADRとDesign Docの境界が曖昧になるケースの好例
Design Doc の事例
事例5: チャット機能の初期設計
- どんな設計: フルページチャット → パネルチャット → AsIs編集の3段階Epic構成でのチャット機能設計
- なぜDesign Docを書いたか: 複数のステークホルダーの合意が必要で、Epic単位でのスコープ定義とDone条件の明確化が求められた
- 実際に役立った点: Non-Goalsで「自由度の高い万能チャット体験は提供しない」を明記したことで、スコープクリープを防げている
事例6: AsIsからToBeへの変化量可視化
- どんな設計: 業務フロー変更時の工数変化量を測定・可視化する機能の設計
- なぜDesign Docを書いたか: 「何を指標とするか」「どの粒度で可視化するか」という要件が曖昧で、書きながら仮説を整理する必要があった
- 実際に役立った点: 指標の粒度を代替案として検討し各粒度のメリット・デメリットを整理したことで、後続の実装判断がスムーズになった
6. よくあるパターンと使い分けTips
ADR と Design Doc の境界
- ADRが向いているケース: 「AかBか」の選択を記録したいとき。技術選定、アーキテクチャ方式、開発規約
- Design Docが向いているケース: 「何を・どう作るか」を整理したいとき。新機能の設計、複数Epicにまたがる実装計画
- 境界が曖昧になるケース: 1つの大テーマに複数の設計判断が含まれる場合。厳密に分けるより、「書く」こと自体を優先する方が実務的
ADR の書き方パターン
- 比較表パターン: OSS選定やライブラリ選定では、候補を横並びにした比較表が効果的。判断根拠が一目で分かる
- セキュリティ設計パターン: 認証・セキュリティ関連では、攻撃ベクター（XSS/CSRF等）に対する防御策をセットで記述する傾向
- 段階的移行パターン: 既存コードへの影響が大きい場合、フェーズ分けした移行計画を含める
- 保留・廃止パターン: 検討したが今はやらない、仕様変更で無効になった、も記録として価値がある。廃止理由を明記することで同じ議論の繰り返しを防げる
Design Doc の書き方パターン
- Epic分割パターン: 大きな機能はEpic単位でスコープ・Done条件を定義する。各Epicが独立してリリース可能な単位になっている
- Non-Goals明示パターン: 「やらないこと」を明確に書くことでスコープクリープを防ぐ
- 仮説検証パターン: Biggest Hypotheses セクションで「何が正しいかまだ分からない」ことを明示する
- ADR参照パターン: 技術選定はADRで行い、Design Docから参照する。Design Doc内で技術選定の議論を繰り返さない
その他のTips
- 「提案しながら書く」: ADRのステータスに「提案中」があるように、書いてから議論するのではなく、書きながら議論する
- 図は積極的に使う: Mermaid図、比較表、スクリーンショットが多くのADR・Design Docで活用されている
- 関連Issueへのリンクを必ず貼る: 議論の文脈を辿れるようにする
- Results セクションは空欄でも良い: 実装後に積極的に更新するより、アーカイブとして扱う方が現実的