意思決定文書はこれを解決します。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

使い回せるテンプレート

#

出発点としてこのテンプレートを使い、チームに合わせて削ってください。

問題の説明

#

どんな問題を解決しようとしているか？なぜ重要か？何もしない場合のコストは？

背景

#

コンテキスト、履歴、関連する詳細を提供する。関連文書、過去の決定、スパイク結果へのリンクを含める。

制約

#

どの解決策でも守るべき制限や要件は何か？

• 予算の制約
• タイムラインの要件
• 技術的制約（既存システム、スキルセット）
• コンプライアンスまたはセキュリティ要件

検討した解決策

#

推奨

#

推奨するオプションを述べ、制約とトレードオフを考慮した上でなぜそれが最良の選択かを要約する。

決定

#

決定が下されたら最終決定を文書化する。推奨と異なる場合は理由を説明する。

結果

#

この決定の影響は何か？必要なフォローアップ作業は何か？

アクションアイテム

#

参考資料

#

関連文書、外部リソース、スパイク結果、過去の決定へのリンク。

習慣として根付かせる

#

文書は決まった場所に置きます。リポジトリ内の専用フォルダでも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の使いどころ

Alanが会議を見限った理由

#

出発点は誰にでも覚えがあるはずです。誰も準備してこない、開始は遅れる、そして声の大きい人が正しかろうが間違っていようが議論を制する。1時間後には入室前より頭が混乱していて、鎮痛剤の残りを気にしている。

Alanもまず会議の改善を試みました。最大15分、明確なアジェンダ、必ず決定を出す。それでもダメでした。議論は脱線し、何が話されたか誰も覚えておらず、欠席者やリモートの人は蚊帳の外。それで、丸ごと文章に移すことにしたそうです。

彼らの主張には頷けるものがあります。書くとなると立ち止まって考えざるを得ないので、議論はより丁寧に、根拠のあるものになる。すべてが記録に残り、うろ覚えに頼らなくて済む。弁論大会でもなくなる。しかもフォーラムは全社に公開されているので、たまたま会議室にいた人だけでなく、誰でも議論に参加できます。

社内フォーラムとしてのGitHub

#

フォーラムの正体はGitHubです。本来コードレビューのためのプラットフォームを、Alanは堂々と転用しました。仕組みは拍子抜けするほど簡単です。

1. GitHubのアカウントを作る。
2. コードの入っていないプライベートリポジトリを作る（Alanでは「Topics」という名前）。
3. 会話を分類するためのラベル体系を用意する。
4. Issuesタブを使う。openなissueは進行中の議論、closedは決定済み。

彼らのissueは17,000件を超えました。開かれずに済んだ会議の数と考えると相当なものです。そして私が一番惹かれるのはここですが、すべての決定について「なぜそうなったか」を検索できる履歴が残ります。過去の決定を蒸し返したくなったら、前回どの議論が勝ったのかを先に読めるわけです。

いつissueを開くか

#

すべての決定がissueに値するわけではありません。彼らのフィルターは4つの質問です。誰が影響を受けるか？どれくらい可逆的か？どれくらい急ぎか？決めるためにもっと文脈が必要か？

大まかには、影響が大きく後戻りしにくい決定はフォーラムへ、それ以外はSlackで済ませます。ワンウェイ・ツーウェイの区別も使っています。ワンウェイの決定（撤回に大きなコストや労力がかかるもの。例として挙がっているのは料金の値上げ）はフルコースの文章化。ツーウェイの決定（安く取り消せて、失敗しても多少エネルギーを失うだけのもの）には儀式は不要です。

LOCI：誰が何をするか

#

すべての議論に、LOCIモデル（Lead、Owner、Consulted、Informed）で役割を割り当てます。

Leadは決定の成否に責任を持ち、決定の背景がチームに正しく理解されるようにします。冒頭で自分がどこまで関与したいかを表明し、あとはOwnerを信頼してチームの成果に責任を持ち、強く反対のときだけ口を出します。Leadは議論ごとに1人だけ。

Ownerは最終決定を下し、プロジェクトを前に進めます。貢献者に情報が行き渡り、期限内に意見が集まるようにし、問題を調査し、issueを開いて閉じ、決定を共有します。自分で解決できない壁に当たったらLeadに相談します。Ownerも決定ごとに1人。

Consultedは、トレードオフの判断に本当に意見が必要な人たちです。期限内の貢献が義務で、「追加することはありません」の一言でも構いません。決定が大きく間違っていると思ったら警鐘を鳴らし、最悪の場合はLeadにエスカレーションします。Alanはこの人数を6人程度までに抑えています。それ以上はスケジュールが犠牲になるからです。

Informedは、たいてい決定後に知らされるだけの人たちです。コミュニケーションは一方通行で、何の貢献も期待されません。誰に知らせるかは、影響範囲を考えてOwnerが決めます。

ここまでは決定ひとつ単位の話です。プロジェクト全体については、同じことをプロジェクトのコミュニケーション計画として一度まとめておきます。誰が何を、どのくらいの頻度で、誰から伝えられるべきかを書いた表です。

issueの解剖図

#

どのissueも同じテンプレートに従います。思考が研ぎ澄まされるうえ、ジュニアメンバーへの「問題の分解の仕方」の教材にもなっています。

• Scope - 議論の「なぜ」。地味に効くのが「このissueは〜については扱わない」の一文
• Context & materials - 過去の議論や資料へのリンク
• LOCI - 誰がLead、Owner、Consulted、Informedか
• 期限 - 貢献の締め切り、issueを閉じる日、解決策が必要になる日
• 解決策の提案 - 推す案をひとつ、または選択肢をいくつか
• 質問 - 特定の人に向けて、特定の仮定を確認・反証するための質問。issueを「海に流すボトルレター」にしないための工夫です

議論を停滞させないための書き方のルール

#

文章の議論も、口頭と同じくらいダラダラと長引き得ます。だからルールがあります。まず簡潔に。彼らはボワローの「よく構想されたものは明晰に語られる」を引いています。シンプルに書けないなら、まだ自分の主張に確信がない証拠です。それから、書いたものすべてに「So what?」テストをかけること。コメントの含意が自明でないなら、はっきり書き添えます。

Ownerにとっては、開いた後の運営も同じくらい重要です。議論を「100万ドルの質問」、つまり本当に重要なたったひとつの争点に向け続け、細部の海で迷子にさせない。合意できた点とまだ開いている点を定期的に整理して見せる。そしてSlackでの催促は最後の手段。貢献の遅延か、本当の緊急時に限ります。

Ownerは会話を前に進めないコメントを非表示にすることもあります。また、見出し、脚注、表、キーボードショートカットといったGitHubの書式機能は全員が使いこなす前提です。文章では、中身と同じくらい見た目が物を言うからです。

コンセンサスなし、傍観者なし

#

この仕組みが「委員会による決定」に堕ちないよう、2つの歯止めがあります。

1つ目。Ownerは、Alanいわく「啓蒙専制君主」として決定します。アイデアを調査し、リスクを測り、同僚に質問はするけれど、コンセンサスは求めないし、言われたことを全部実装する義務もない。Alanは「うちは民主主義ではない」と言い切っています。全員が株主であり、チームや個人よりも会社の利益を優先する。とはいえ、孤立した拙速な決定を望んでいるわけでもありません。Ownerが「この賭けで行ける」とそれなりに確信したら決めて、みんなで試し、影響が見えてきたら振り返って次に活かします。

2つ目。貢献者の数を管理します。Jeff Bezosの「ピザ2枚ルール」は非同期にも当てはまります。人が増えるほど、1人あたりの貢献は減る。6人を超えたあたりから傍観者効果が顔を出し、参加の質が落ちるそうです。通知も同じ思想で、段階的に。全員が自分のGitHub通知を正しく設定している（Settingsで「Participating」と「Watching」の「Web and Mobile」にチェック）と信頼して、issueのQuestionsセクションでのタグ付けは最小限に抑えます。

自分が持ち帰るもの

#

会議の内容を、その場にいなかった人に完全に説明することはできません。でも、書かれた決定なら誰でも読めます。Alan自身、これが最善で唯一の仕組みだとは言っていません。ただ自分たちに一番合っていた、というだけです。割り込みが減り、傍観者効果が薄れ、一歩引いて事実ベースで決められるようになった。私もチームの決定を全部GitHubのissueに移すつもりはありませんが、下のテンプレートはさっそくうちのリポジトリに入れます。

GitHubのissueテンプレートとして使う

#

フォーラムとして使うリポジトリに.github/ISSUE_TEMPLATE/decision.mdとして保存しておけば、誰かが新しいissueを開くたびに、GitHubがこのテンプレートを選択肢として出してくれます。セクションの構成はAlanのもので、LOCIの行とラベルは私が足しました。

---
name: 意思決定
about: 決定を提案して、意見を文章で集める
title: "[意思決定] "
labels: decision
---

## スコープ
- このissueの目標は...
- このissueでは...は扱いません

## このissueを開いた理由

## LOCI
- Lead:
- Owner:
- Consulted:
- Informed:

## 期限
- 意見の締め切り:
- 決定日:

## 背景と資料

## 提案

## 質問

GitHub IssuesとGitHub Projectsの使い分け

#

GitHubをもっと広くプロジェクト管理に使おうと考えているなら、この2つは役割が違うと押さえておくと楽です。Issuesには議論が残り、閉じたあとはそれがそのまま決定の記録になります。GitHub Projectsは、1つ以上のリポジトリのissueの上に重ねるボードや表で、ステータスや担当者、期限といった独自のフィールドを持たせられます。Alanのような意思決定フォーラムなら、ラベルとissue一覧で十分です。Projectsを足すのは、開いている決定を、決めなければならない日付順に1画面で並べたくなったとき。それから、開発の進捗も同じ場所で追い始めたときです。たいていのチームは、結局そこで両方を使うことになります。

人はなぜ、あれが欲しい、これが欲しいと思うのでしょうか。自分でも意外なほど、このことを考えています。最初にこの記事を書いた頃、私はみんなが一日中コスメについて語り合うプラットフォームに関わっていました。ほぼ同じような製品なのに、片方は熱望され、もう片方は見向きもされない。その理由こそが、事業のほぼすべてでした。好みは人それぞれですが、その下にあるパターンは驚くほど一貫しています。

望ましさ、実現可能性、事業性

#

この3つのレンズで見る考え方はデザイン思考から来たもので、プロダクトチームがアイデアに本腰を入れる前にチェックする方法として、すっかり定着しました。便利なのは、3つがそれぞれ違う形で失敗するところです。作れるし採算も合うのに誰も欲しがらない製品は、スタートアップの典型的な失敗パターンです。よく作り込まれていて、価格も妥当で、そして見向きもされない。望ましいのに作れない、あるいは稼げない製品は、少なくとも失敗の理由が前もって見えています。

3つのうち、チームがいちばん飛ばしがちなのが望ましさです。測るのがいちばん難しく、思い込むのがいちばん簡単だからです。チームの全員は、自分たちが作っているものをもともと欲しいと思っています。でもそれは、ほかの誰かについては何も教えてくれません。

この先は、望ましさが何でできているのか、そしてそれをどう確かめるかの話です。

ちゃんと働き、働き続けること

#

欲しさの出発点は、たいてい素朴な有用性です。本当に10分節約してくれるキッチン用品、とにかくつながり続けてくれるスマートフォン。ただ、有用性だけでは「悪くないね」止まりです。本当に熱望されるものは、役割を並外れてうまく果たし、しかも果たし続けます。買い物を「手放したくない持ち物」に変えるのは、品質と耐久性です。クラシックカーや、持ち主より長生きする包丁のように。壊れそうなものに恋い焦がれる人はいません。

何かを感じさせること

#

美しさは、私たちが認めたがる以上に強く効きます。スポーツカーのラインや料理の美しい盛り付けは、理性が口を挟む前にこちらを掴んでしまう。そして、いちばん強い「欲しい」は感情から来ます。喜び、懐かしさ、帰属感。ボロボロになった子どもの頃のおもちゃは、実用性のテストには全部落ちるのに、どうしても捨てられません。パーソナライズも同じ本能に訴えます。自分に合わせて作られたものは、既製品には決して出せない「自分のもの」という感覚をくれます。

思っている以上に、他人が決めている

#

欲しさの一部は、社会的に作られたものです。トレンド、周囲の評価、文化的な規範が、私たちの欲しいものを静かに方向づけています。希少性も同じです。限定版、希少な宝石、一点物。「これを欲しがること自体が、小さなクラブへの入会証になる」というシグナルですね。そして評判がすべてを増幅します。絶賛レビューや口コミがあると、それを欲しがっても大丈夫だと安心できる。あのコスメのプラットフォームでは、このループが回るのを毎日のように見ていました。人気のレビュアーがひとり、生産数の少ない製品がひとつ。それだけで、1週間後には売り切れです。

それでも計算は合わないといけない

#

価格が欲しさを殺すことはありませんが、割に合わない取引は殺します。人はラグジュアリーには喜んでプレミアムを払う一方で、苦労して稼いだお金に見合わないと感じたものからは、あっさり離れていきます。そして最近は、価値観も同じ計算式に入ってきました。サステナブルに、倫理的に作られたものかどうかで、欲しいものリストの順位が上下する人が増えています。私もその一人です。

欲しいと思われるかを確かめる方法

#

望ましさの落とし穴は、本人に直接聞いても役に立たないことです。「これ、使いますか？」と聞けば、ほぼ全員が礼儀正しく「はい」と答えます。「はい」と言うのはタダだからです。うまくいくテストはどれも、時間やお金、メールアドレス、あるいは習慣など、相手に何かを手放してもらうよう頼み、実際にそうするかを見るものです。

未来ではなく過去について聞きます。「最後にこの問題にぶつかったのはいつで、そのときどうしましたか？」と聞けば、実際の行動がわかります。最後がいつだったか誰も思い出せないなら、その問題は、解決策を欲しがるほど痛くはないということです。

フェイクドア（偽の入り口）を用意します。まだ存在しないもののランディングページや、既存の製品の中のボタンを作って、何人がクリックしたか、メールアドレスを残したかを数えます。少しずるい気もしますが、これほど安くて正直なシグナルはほかにありません。扉の向こう側では、近日公開であることを正直に伝えておきましょう。

コミットメントを求めます。ウェイトリストは弱いシグナルで、予約注文や手付金は強いシグナルです。人は何にでも登録しますが、お金を払うのは本当に欲しいものに対してだけです。

すでに使われているものなら、もう使えなくなったらどう感じるかを聞きます。プロダクト界隈でよく言われる目安に、ユーザーのおよそ40%が「とてもがっかりする」と答えるなら、本当に欲しがられるものができている、というものがあります。大ざっぱな指標ですが、気に入っているかどうかを聞くよりはるかにましです。

そして、何を言うかではなく、何をするかを見ます。どの機能が2回目も使われるか、リマインドしなくても戻ってくるのはどれか、壊れたときに何について文句が出るか。ここでは苦情が過小評価されています。欲しくもなかったものを失って文句を言う人はいません。

全部合わせると

#

これらの要素は、どれか一つだけで製品を支えられるわけではありません。でも、いくつか積み重なると、つまり本当に役に立ち、丁寧に作られ、見た目が良く、少しだけ手に入りにくく、信頼できる人たちが薦めているものになると、行列のできる製品になります。残りの大部分は、マーケティングの仕事です。

要するに

#

望ましさとは、必要かどうかを超えて、人がどれだけそれを欲しいと思うかです。プロダクトの文脈では、実現可能性、事業性と並ぶ「人はこれを欲しがるか？」というレンズにあたります。望ましさを生むのは、長く続く有用性、感情や美しさに訴える力、社会的証明と希少性、そしてフェアだと感じられる価格です。使うかどうかを聞いても、望ましさは見つかりません。何か本当に手放すものを差し出してもらい、相手が実際にどうするかを見て確かめましょう。