どんなチームも意思決定をします。でも、ほとんどのチームはなぜその決定をしたのか忘れてしまいます。意思決定文書—ADR、RFC、決定ログなど呼び方は何でも—は、重要な選択の背景、選択肢、そして理由を記録することでこの問題を解決します。
このガイドでは、いつ書くべきか、どうすれば実際に使われる文書にできるか、そしてすぐに使えるテンプレートを紹介します。
意思決定文書が重要な理由#
1. 明確さと透明性#
意思決定文書は、主要な決定、検討された解決策、最終選択の根拠を明確に記述するための構造化された方法を提供します。この情報を一元化された文書に記録することで、チームは誤解を減らし、全員が同じ認識を持つことができます。透明性は、決定が思慮深く包括的に行われていることを示すため、ステークホルダー間の信頼を育みます。
2. チーム間の連携#
大規模なプロジェクトには通常、異なる視点や優先事項を持つ部門横断チームが関わります。意思決定文書は、解決策を評価するための明確なフレームワークを提供することで、これらの多様なグループの連携を支援します。すべての関係者が決定に影響を与える要因を理解すると、賛同を得て一体となって前進することが容易になります。
3. 手戻りと終わりのない議論の回避#
チームが同じ議論を何度も繰り返したことはありませんか？「なぜMongoDBではなくPostgreSQLを選んだのか？」「APIバージョニング戦略はもう決まったんじゃなかった？」決定を文書化することで、チームは既に解決した問題を再検討することを避けられます。過去の決定とその背景の明確な記録があれば、チームは足跡をたどり直すのではなく、実行に集中できます。
4. 組織知識の保存#
プロジェクトは数ヶ月から数年に及ぶことがあり、その間にチームメンバーが入れ替わることもあります。意思決定文書は、なぜ特定の道が選ばれたのか—何が決定されたかだけでなく—についての重要な知識を保存する歴史的記録として機能します。これにより、人員が変わっても継続性が確保されます。
5. 説明責任とオーナーシップ#
意思決定者、貢献者、承認者を明記することで、意思決定文書は説明責任を生み出します。各人が自分の役割と責任を理解し、進捗の追跡とフォローアップが容易になります。
いつ意思決定文書を書くべきか#
すべての決定に正式な文書化が必要なわけではありません。以下の場合に意思決定文書を使用してください：
影響の大きい決定：
- 技術スタック選択（フレームワーク、データベース、クラウドプロバイダー）
- アーキテクチャパターン（マイクロサービス vs モノリス、イベント駆動 vs リクエスト・レスポンス）
- サードパーティベンダーの選定
- セキュリティとコンプライアンスのアプローチ
長期的な影響を持つ決定：
- 外部システムが依存するAPIコントラクト
- 複数のサービスに影響するデータモデル設計
- 確立されたパターンへの破壊的変更
チーム間の連携が必要な決定：
- 複数のチームや部門に影響する変更
- 非技術系ステークホルダーの賛同が必要な決定
- リソース配分と優先順位付けの選択
スパイクから生まれた決定：
- タイムボックス化された調査が終了したら、調査結果と決定を正式な文書に記録する
正式な文書化をスキップできる場合：
- 簡単に元に戻せる決定
- チーム内部の実装詳細
- 直接的なスコープ外への影響が最小限の選択
意思決定文書のライフサイクル#
意思決定文書が組織内をどのように流れるかを理解することで、その効果を最大化できます：
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ ドラフト │ ──► │ レビュー │ ──► │ 承認 │ ──► │ 実装 │
│ 提案 │ │ フィードバック│ │ 受理 │ │ 完了 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ 却下/ │
│ 廃止 │
└─────────────┘ドラフト/提案： 著者が最初の文書を作成し、問題と潜在的な解決策の概要を示します。
レビュー/フィードバック： ステークホルダーが文書をレビューし、質問を投げかけ、代替案を提案します。この段階は重要です—前提が検証され、盲点が明らかになります。
承認/受理： 意思決定者（多くの場合、テックリード、アーキテクト、またはプロダクトオーナー）が最終決定を下します。
実装/完了： チームが決定を実行します。実装中に行われた変更を反映するよう文書を更新します。
却下/廃止： レビュー中に却下される決定もあります。状況が変わって陳腐化する決定もあります。混乱を避けるため、これらを明確にマークしてください。
効果的な意思決定文書の書き方#
解決策ではなく、問題から始める#
よくある間違いは、すぐに解決策に飛びつくことです。代わりに、以下を明確に述べましょう：
- 私たちはどんな問題を解決しようとしているのか？
- なぜこの問題が今重要なのか？
- 対処しなければどうなるか？
このフレーミングにより、解決策を議論する前に全員が問題に同意できます。
複数のオプションを提示する#
強い好みがあっても、少なくとも2〜3の代替案を文書化しましょう。これはデューデリジェンスを示し、選択された解決策がなぜ好ましいかを他者が理解するのに役立ちます。各オプションについて以下を含めます：
- 簡潔な説明
- 長所と短所
- 工数見積もり（大まかなTシャツサイズでOK：S/M/L/XL）
- リスクと軽減策
トレードオフを明示する#
すべての決定にはトレードオフが伴います。それらを率直に認めましょう：
- 「アーキテクチャの純粋さよりも市場投入スピードを選択しています」
- 「より良いスケーラビリティのために運用の複雑さが増すことを受け入れています」
- 「生のパフォーマンスよりも開発者体験を優先しています」
これらの声明は、将来の読者がコンテキストと制約を理解するのに役立ちます。
具体的な例を含める#
抽象的な議論は抽象的な決定につながります。文書を以下で具体化しましょう：
- 解決策がどのように実装されるかを示すコードスニペット
- システム間の相互作用を示す図
- スパイクからの概念実証実装へのリンク
明確なタイムラインを設定する#
期限のない決定は無期限に漂います。以下を明記しましょう：
- いつ決定を下す必要があるか
- 誰がいつまでにインプットを提供する必要があるか
- 決定が遅れた場合、何が進捗をブロックするか
例：アーキテクチャ決定記録（ADR）#
意思決定文書の実践的な例を以下に示します：
# ADR-001: API Authentication Strategy
**Status:** Accepted
**Date:** 2024-11-15
**Decision Maker:** Sarah Chen (Platform Architect)
**Contributors:** Backend Team, Security Team, Mobile Team
## Context
Our public API currently uses API keys for authentication. As we expand to
support third-party integrations and mobile apps, we need a more robust
authentication mechanism that supports:
- Token expiration and refresh
- Scoped permissions
- User-level authentication (not just service-level)
## Decision
We will implement OAuth 2.0 with JWT tokens for API authentication.
## Options Considered
### Option 1: OAuth 2.0 with JWT (Recommended)
**Description:** Industry-standard protocol with self-contained tokens
| Pros | Cons |
|------|------|
| Industry standard, well-documented | More complex initial implementation |
| Self-contained tokens reduce database lookups | Tokens cannot be revoked instantly |
| Broad library support | Requires refresh token management |
**Effort:** Medium (2-3 sprints)
### Option 2: Session-based Authentication
**Description:** Traditional server-side sessions with cookies
| Pros | Cons |
|------|------|
| Simple to implement | Not suitable for mobile apps |
| Easy to revoke sessions | Requires sticky sessions or shared session store |
| Familiar to most developers | Doesn't scale as well |
**Effort:** Small (1 sprint)
### Option 3: Custom Token System
**Description:** Build our own token-based authentication
| Pros | Cons |
|------|------|
| Fully customizable | Reinventing the wheel |
| No external dependencies | Security risks from custom implementation |
**Effort:** Large (4+ sprints)
## Consequences
- Mobile team can implement standard OAuth flows
- We'll need to set up a token refresh mechanism
- API documentation will need updates for OAuth flows
- Existing API key users will need a migration path (6-month deprecation)
## References
- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
- Internal spike document: [Authentication Options Spike](/spikes/auth-spike-2024)
- Security team review: SEC-2024-042意思決定文書テンプレート#
このテンプレートをチームの出発点として使用してください：
| 属性 | 詳細 |
|---|---|
| 決定/課題名 | [明確で説明的なタイトル] |
| ステータス | [ドラフト / レビュー中 / 承認済み / 却下 / 廃止] |
| 影響度 | [高 / 中 / 低] |
| オーナー | [決定を推進する人の名前] |
| 意思決定者 | [最終権限を持つ人] |
| 期限 | [決定を下す期限] |
問題の説明#
どんな問題を解決しようとしているか？なぜ重要か？何もしない場合のコストは？
背景#
コンテキスト、履歴、関連する詳細を提供する。関連文書、過去の決定、スパイク結果へのリンクを含める。
制約#
どのような制限や要件をすべての解決策が尊重する必要があるか？
- 予算の制約
- タイムラインの要件
- 技術的制約（既存システム、スキルセット）
- コンプライアンスまたはセキュリティ要件
検討した解決策#
| オプション | 説明 | 長所 | 短所 | 工数 | リスク |
|---|---|---|---|---|---|
| オプション1 | 説明 | 長所A、長所B | 短所A、短所B | S/M/L/XL | 低/中/高 |
| オプション2 | 説明 | 長所A、長所B | 短所A、短所B | S/M/L/XL | 低/中/高 |
| オプション3 | 説明 | 長所A、長所B | 短所A、短所B | S/M/L/XL | 低/中/高 |
推奨#
推奨するオプションを述べ、制約とトレードオフを考慮した上でなぜそれが最良の選択かを要約する。
決定#
決定が下されたら最終決定を文書化する。推奨と異なる場合は理由を説明する。
結果#
この決定の影響は何か？必要なフォローアップ作業は何か？
アクションアイテム#
| アクション | 担当者 | 期限 |
|---|---|---|
| アクション1 | 名前 | 日付 |
| アクション2 | 名前 | 日付 |
参考資料#
関連文書、外部リソース、スパイク結果、過去の決定へのリンク。
意思決定文書文化のためのヒント#
発見しやすくする： 意思決定文書を一貫した場所に保存する—リポジトリ内の専用フォルダ、Wikiスペース、またはドキュメントシステム。見つけられなければ使われません。
軽量に保つ： 書くのに何日もかかる意思決定文書は書かれません。必要最小限から始め、重要なところに詳細を追加しましょう。
レトロスペクティブでレビューする： レトロスペクティブで定期的に過去の決定をレビューしましょう。どの決定がうまくいったか？どれを違う形で行うか？このフィードバックループが将来の意思決定を改善します。
決定を実装にリンクする： コードコメント、コミットメッセージ、プルリクエストで意思決定文書を参照しましょう。これにより「なぜ」と「何を」の間のトレーサビリティが生まれます。
バージョン管理と更新： 状況は変わります。決定が廃止されたとき、古い文書を削除せず、廃止とマークして新しい決定にリンクしましょう。これにより歴史的記録が保存されます。
避けるべき一般的な落とし穴#
分析麻痺： 完璧を求めて良いものの敵にならないでください。期限を設定し、利用可能な情報で最善の決定を下し、先に進みましょう。ほとんどの決定は必要に応じて見直すことができます。
形式的な承認： レビューが常に意味のあるフィードバックなしに承認で終わるなら、プロセスは価値を追加していません。真摯な批評と代替の視点を奨励しましょう。
孤立した文書： 書かれたが実装されない意思決定文書は、文書がないより悪いです。決定が行動につながることを確認しましょう。
詳細すぎる： 意思決定文書は「なぜ」と「何を」を説明すべきであり、「どのように」ではありません。実装の詳細は技術仕様書に属し、決定記録には属しません。
異論を無視する： ステークホルダーが決定に同意しない場合、その懸念を文書化しましょう。決定が維持されても、異論を認めることは敬意を示し、将来の読者に重要なコンテキストを提供します。
結論#
意思決定文書はオーバーヘッドではなく、時間の節約です。「なんでXを選んだんだっけ？」という会話が、ADRを読むだけで済むようになる——その一回一回が節約された時間です。
次の重要な決定から始めてみてください。荒削りでもいいので書いてみましょう。プロセスは使いながら改善していけばいいのです。続けていくうちに、将来の意思決定を加速し、新メンバーのオンボーディングも楽にしてくれる、検索可能な記録が蓄積されていきます。
参考資料#
このサイトの関連記事：
- アジャイルソフトウェア開発におけるスパイクの理解 - 重要な決定を下す前に情報を収集するためにスパイクを使用する
- レトロスペクティブ：フィードバックループの力 - 継続的改善プロセスの一部として過去の決定をレビューする
- APIの計画 - API設計に意思決定文書の原則を適用する
- プロジェクト管理のためのGitHub - コードと一緒に意思決定文書を保存・追跡する
外部リソース：
- Documenting Architecture Decisions - Michael Nygard - ADRを普及させたオリジナルのブログ記事
- ADR GitHub Organization - アーキテクチャ決定記録のためのツール、テンプレート、例
- Design Docs at Google - Googleの設計ドキュメントへのアプローチ
- RFC Process at Rust - Rustプログラミング言語の十分に文書化されたRFCプロセス
- Spotify’s Decision Record Template - Spotifyのアーキテクチャ決定記録へのアプローチ