どんなチームも意思決定をします。そして、ほとんどのチームは、なぜその決定をしたのかを忘れます。半年後に誰かが「なんでMongoDBじゃなくてPostgreSQLにしたんだっけ？」と言い出し、当時の制約を覚えている人は誰もおらず、同じ議論がもう一度始まります。しかも大抵、前回より少ない顔ぶれで。
意思決定文書はこれを解決します。ADRでもRFCでも決定ログでも、呼び方は何でも構いません。大事なのは、選択をしたその瞬間に、背景と選択肢と理由を書き残すことです。今年、開発チームを率いる立場になってから、そのありがたみを以前にも増して感じています。組織の記憶になるか、組織の言い伝えになるかの分かれ目です。
手間をかける価値がある理由#
わかりやすい見返りは、同じ議論を二度しなくて済むことです。「APIのバージョニング戦略って、もう決めましたよね？」決定内容と理由の記録がはっきり残っていれば、決着済みの問題は決着済みのままで、チームは来た道を辿り直す代わりに実行にエネルギーを使えます。
もうひとつの見返りは、時間が経ってから効いてきます。プロジェクトは何ヶ月も何年も続き、人は入れ替わり、最後に残るのはコードです。ただしコードが教えてくれるのは「何を」決めたかだけで、「なぜ」は決して語りません。意思決定文書は、当時あった制約、却下された代替案、誰が判断したかという推論の部分を保存します。新しいメンバーは言い伝えではなくコンテキストを手に入れます。チーム横断の決定は、結論だけでなく検討された要素まで全員に見えるので、本当の納得を得やすくなります。そして意思決定者と貢献者に名前が付くことで、実行にもちゃんと持ち主ができます。
いつ書くか#
すべての決定に文書が要るわけではありません。私が書くのは、決定が次のどれかに当てはまるときです。
- 後戻りが高くつく — 技術スタックの選定（フレームワーク、データベース、クラウドプロバイダー）、アーキテクチャパターン（マイクロサービスかモノリスか、イベント駆動かリクエスト・レスポンスか）、サードパーティベンダーの選定、セキュリティ・コンプライアンスの方針
- 影響が長く残る — 外部システムが依存するAPI契約、複数サービスにまたがるデータモデル、確立されたパターンへの破壊的変更
- チームをまたぐ — 複数チームや非技術系ステークホルダーの合意が要るもの、リソース配分や優先順位の判断
- スパイクの結論 — タイムボックス付きの調査が終わったら、発見と決定が蒸発する前に文書に残す
逆に、簡単に元へ戻せる決定、チーム内部の実装詳細、自分のスコープの外にほぼ影響しない選択には、形式張った文書は不要です。誰にも必要とされない文書は、ただの宿題です。
ライフサイクル#
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ ドラフト │ ──► │ レビュー │ ──► │ 承認 │ ──► │ 実装 │
│ 提案 │ │ フィードバック│ │ 受理 │ │ 完了 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ 却下/ │
│ 廃止 │
└─────────────┘著者が問題と候補案をドラフトにまとめ、ステークホルダーがレビューします。この作業の元が取れるのはレビュー段階です。前提が疑われ、盲点が表に出てくるのはここなので。そのうえで意思決定者（多くはテックリード、アーキテクト、プロダクトオーナー）が最終判断を下し、チームが実装します。実装中に現実に合わせて変えた部分があれば、文書も更新します。レビューで死ぬ文書もあれば、状況が変わって後から廃止される文書もあります。どちらも明確にマークしてください。「承認済み」のまま古びた文書は、次に見つけた人への罠になります。
読む価値のある文書にするには#
お気に入りの解決策ではなく、問題から始めます。何を解決しようとしているのか、なぜ今それが重要なのか、何もしなければどうなるのか。問題認識が揃っていないまま解決策を議論しても、それはただの演劇です。
次に、本物の選択肢を並べます。強い好みがあっても、最低2〜3案。それぞれに簡潔な説明、長所と短所、ざっくりした工数見積もり（Tシャツサイズで十分です：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スペースでも構いませんが、見つけられない決定は存在しないのと同じです。そして軽く保つこと。書くのに何日もかかる文書は、そもそも書かれません。コードコメントやコミットメッセージ、プルリクエストから文書を参照して、「なぜ」を「何を」のそばに繋いでおきましょう。決定が廃止されたら、古い文書は消さずに廃止とマークして新しい決定へリンクします。履歴こそが価値なので。そしてレトロスペクティブで過去の決定をたまに見直してください。どれが持ちこたえ、どれを今ならやり直すか。
失敗パターンも同じくらい予測可能です。分析麻痺には、期限を切って手持ちの情報で決めること。ほとんどの決定は後から見直せます。意味のある批評が一度も出ないハンコ押しレビューは、価値を足さずにプロセスだけ足しています。書かれたのに実行されない孤児文書は、文書がないより悪い。詳細の書きすぎにも注意で、文書が扱うのは「なぜ」と「何を」であって「どのように」ではありません。実装の詳細は技術仕様書へ。そして異論が出たら、それも書き残してください。決定はそのまま通るかもしれませんが、その異論こそ、1年後の誰かが必要とするコンテキストです。
次の重要な決定から始めてみてください。荒削りでもいいので書いて、プロセスは使いながら磨けばいい。「なんでXを選んだんだっけ？」という会議が、誰かがADRを読むだけで消える。その一回一回が、チームに返ってくる時間です。
参考資料#
このサイトの関連記事：
- アジャイルソフトウェア開発におけるスパイクの理解 - 大きな決定の前にスパイクで情報を集める
- レトロスペクティブ：フィードバックループの力 - 継続的改善の一環として過去の決定を見直す
- APIの計画 - 意思決定文書の考え方をAPI設計に応用する
- プロジェクト管理のためのGitHub - 意思決定文書をコードのそばに置いて管理する
外部リソース：
- Documenting Architecture Decisions - Michael Nygard - ADRを広めたオリジナルの記事
- ADR GitHub Organization - ADRのためのツール、テンプレート、実例
- Design Docs at Google - Googleの設計ドキュメントのやり方
- RFC Process at Rust - Rust言語のよく整備されたRFCプロセス
- Spotify’s Decision Record Template - SpotifyのADRの使いどころ