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

B2BのSaaSをやっていると、いつか必ずテナンシーの問題にぶつかります。だいたいは、大口の見込み客から「うちのデータは他社と分離できますか？」と聞かれた日です。私もこの議論には何度か立ち会ってきました。答えは基本的に2つ。顧客ごとに専用インスタンスを用意する（シングルテナント・マルチインスタンス）か、全員を1つの共有インスタンスに乗せる（マルチテナント・シングルインスタンス）か。どちらが正解ということはなく、壊れ方が違うだけです。

インフラストラクチャ設計

#

シングルテナント・マルチインスタンス

#

こちらの魅力は「分離」に尽きます。メリットはほぼすべてそこから生まれます。顧客のデータがそれぞれ独立した環境にあるので、セキュリティレビューやコンプライアンスの話がぐっと楽になります。デプロイの失敗や重いワークロードの影響も、全顧客ではなく1顧客で済みます。インスタンスごとに独立してスケール、チューニング、カスタマイズができて、リソースが専用なので、隣のテナントの使い方次第でパフォーマンスが揺れることもありません。メンテナンスも顧客単位で計画できるのでダウンタイムを小さく抑えられますし、料金設計をきちんとすれば、インフラコストをテナントごとの実際の使用量に合わせることもできます。

その代償は、すべてをN個ずつ運用することになる点です。リソースのオーバーヘッドは積み上がり、インスタンス間で設定はドリフトし、フリート全体でバージョンとデータを揃えること自体がひとつのプロジェクトになります。スケーリング、分離、コスト管理の問題は消えるのではなく、増殖するのです。

マルチテナント・シングルインスタンス

#

こちらがデフォルトになっているのには理由があります。デプロイはひとつ、バックアップするデータベースもひとつ、本番のバージョンもひとつ。リソース効率が良く、運用はシンプルで、アップデートもセキュリティパッチも全顧客に同時に届きます。

難しさは「共有」の裏返しです。あるテナントの重い使い方が全員のパフォーマンスに響きますし、顧客ごとのカスタマイズには限界があります。そしてデータの分離はインフラではなくアプリケーションコードの責務になるため、バグひとつがテナント間のデータ漏えいになりえます。スケーラビリティのボトルネックは全顧客に同時に効きますし、「この顧客だけ」という影響範囲が存在しないぶん、メンテナンスにも余計に気を使います。

SaaS ソリューションの詳細 - マルチインスタンス vs. マルチテナントアーキテクチャ

マルチテナント vs マルチインスタンス

#

同じ選択が「マルチテナント vs マルチインスタンス」と呼ばれることもよくありますが、同じものを反対側から見ているだけです。「テナント」は顧客の話で、1つのソフトウェアを何社で共有するか。「インスタンス」はデプロイの話で、ソフトウェアをいくつ動かすか。シングルテナントのプロダクトは顧客ごとに1つずつ動かすマルチインスタンス構成で、マルチテナントのプロダクトはたいてい全員で共有するシングルインスタンスです。つまり「マルチインスタンスにしてほしい」という要望は、シングルテナントにしてほしいという意味です。

実際には2択というよりグラデーションで、本当の判断はほとんどデータベースで決まります。いちばん共有寄りなのは、全顧客の行を同じテーブルに入れて tenant_id 列を持たせ、すべてのクエリでそれを絞り込む形です。運用コストは最も安く、間違えるのも最も簡単です。一歩進むと、共有データベースの中に顧客ごとのスキーマを切る形になります。分離がきれいになり顧客単位のバックアップも取れますが、マイグレーションはスキーマの数だけ実行することになります。さらに進むと、アプリケーションは共有のまま、データベースを顧客ごとに分ける形です。スタック一式を顧客ごとに動かさなくてもデータをしっかり分離できるので、よく選ばれる中間地点です。反対の端が完全なシングルテナントで、アプリケーションもデータベースも専用です。AWSのSaaSガイダンスでは両端をサイロ（silo）とプール（pool）、その組み合わせをブリッジ（bridge）と呼んでいて、顧客のセキュリティチームに構成を説明するときに便利な言葉です。

シングルテナントとマルチテナントの比較

#

どちらをいつ選ぶか

#

特別な理由がない限り、マルチテナントを選びましょう。少額を払う顧客がたくさんいるとき、ユーザーが自分でサインアップするとき、そして30個の環境を抱えたら回らなくなるくらいチームが小さいときは、マルチテナントが正しいデフォルトです。

シングルテナントが手間に見合うのは、いくつかの場面に限られます。医療、金融、行政の顧客は、データを物理的に分けることや特定の国に置くことを求めることが多く、セキュリティレビューでそれに正直に答えるいちばん簡単な方法が専用インスタンスです。エンタープライズ契約の大口顧客が数社なら、専用スタックのコストを負担してもらえますし、そもそもそれを期待されていることも多いです。そして、顧客ごとにリリースのタイミングを変えたい、バージョンを固定したい、深くカスタマイズしたいという要望があるなら、インスタンスを分けることはオーバーヘッドではなく、売っているものの一部になります。

結局、多くのチームは両方に落ち着きます。ほぼ全員向けにはマルチテナントのプロダクトを、必要としていてお金も払ってくれる一部の顧客には、エンタープライズプランとして専用インスタンスを。マルチテナント版で最初からすべてにテナントIDを持たせておけば、あとで1社だけ専用データベースに移すのは書き直しではなく、マイグレーションで済みます。

マルチテナントの分離を壊れにくくする

#

マルチテナントでいちばん怖いバグは、テナントの絞り込みを忘れたクエリです。エラーにはなりません。ほかの顧客のデータを黙って返すだけで、コードレビューですべてを拾えるわけでもありません。Postgresを使っているなら、行レベルセキュリティ（RLS）でこのチェックをデータベース側に移せます。絞り込みを忘れたクエリでも、見えるのは今の顧客の行だけになります。

ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON invoices
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

あとは各リクエストが、トランザクションの中で SET LOCAL app.tenant_id = '…' を実行してテナントを設定します。こうすればコネクションプールの接続が前の顧客のIDを次のリクエストに持ち越すことはなく、設定し忘れたリクエストは行の代わりにエラーを受け取ります。注意点は2つあります。アプリはテーブルの所有者ではないロールで接続すること。所有者は FORCE ROW LEVEL SECURITY を付けない限り、このポリシーを素通りします。そしてスーパーユーザーでは絶対に接続しないこと。こちらは何をしても素通りです。

シングルテナントはどこから始めるか

#

シングルテナントで行くなら、それが「管理可能」になるか「スローモーションの災害」になるかを分けるのはツールです。30個の環境を手作業で面倒見ることはできません。

核になるのはコンテナとInfrastructure as Codeです。Dockerでアプリを全テナント同一の形にパッケージし、Kubernetesで大量のインスタンスのデプロイとスケーリングを捌きます。TerraformやPulumi、AWS CloudFormationでテナント一式のスタックをコードとして定義しておけば、31社目の顧客の立ち上げは週末の徹夜作業ではなくプルリクエストになります。VM寄りの世界にいるなら、Ansible、Chef、Puppetといった構成管理ツールが同じ役割を果たしてくれます。CI/CD（Jenkins、GitLab CI/CD）はいつも以上に重要です。すべてのリリースを、付きっきりにならずに全インスタンスへ展開しないといけないからです。

その先はプロダクトの形次第です。ワークロードによってはサーバーレス（AWS Lambda、Azure Functions）でサーバー層ごと消せます。Amazon RDSやAzure SQL Databaseのようなマネージドデータベースは、テナントごとのDBを手で管理する苦行から救ってくれます。モニタリング（Prometheus、Grafana、New Relic）はフリートを持った時点で必須になります。どのインスタンスが不調かは、顧客に言われる前に知りたいですよね。認証まわりはAuth0やOktaのようなIAMサービスに任せれば、テナントごとに作り直さずに済みます。使っている言語にも、この手の配管作業を省いてくれるSaaS向けのフレームワークやライブラリがきっとあります。ホスティングはAWS、Azure、Google Cloud Platformといった大手クラウドならどこでも問題ありません。

初日から全部を揃える必要はありません。コンテナとIaCから始めて、テナントが増えるにつれてモニタリングとIAMを足し、あとは実際に痛みを感じた順に選んでいけば十分です。

ざっくり言うと

#

シングルテナント、つまりマルチインスタンスは、顧客ごとにアプリケーションとデータベースを別々に持つ構成です。分離と顧客単位の制御が手に入る代わりに、運用するフリートを抱えます。マルチテナントは1つを全員で共有する構成で、安くてシンプルですが、分離はコードで担保します。多くのプロダクトはマルチテナントで始め、すべてにテナントIDを持たせてデータベースにそれを強制させたうえで、必要としていてお金も払う一部の顧客にだけ専用インスタンスを提供するのがよいでしょう。シングルテナントで運用するなら、管理できる状態を保つ鍵はコンテナとInfrastructure as Codeです。