デザインドキュメントは実は政治文書だ

私が書いたり読んだりしてきたすべてのデザインドキュメントは、二つの会話の交差点にある：ドキュメントが主張する技術的な会話と、組織がスコープ、オーナーシップ、予算について実際にしている政治的な会話だ。最初のものだけが存在するふりをすることが、デザインが承認されながらも堂々巡りで出荷される仕組みだ。この記事は、どちらかを失うことなく両方の聴衆のために書くことを学んだ方法だ。

二つの聴衆、二つの会話

良いデザインドキュメントはいつも二つの問いに同時に答えている：

技術的な問い： これはどう機能すべきか？
政治的な問い： 誰がオーナーで、誰がファンドし、誰がクレジットを受け、誰がオプションを失い、誰が起きるために「はい」を言わなければならないか？

ドキュメントは最初のものについてだと主張する。会議は大抵二番目についてだ。技術的な聴衆のためだけに書けば、「これは良く見える、スコープを縮小しよう」のようなコメントを受け取り、その後三週間後にあなたなしでSlackスレッドでスコープが再拡大されるのを眺めることになる。

難しい方法で学んだこと

私が最も早いエンジニアリングマネジメントの時代の一つで、インフラ統合のための素晴らしいデザインドキュメントと思えるものを書いた。アーキテクチャ図：クリーン。トレードオフ：列挙済み。マイグレーション計画：原子的。代替案：考慮済み。

ドキュメントはレビューで承認された。六ヶ月後、プロジェクトは計画の40%ほどを出荷し、二つの隣接チームが同じ作業の独自バージョンを行っており、私はVPになぜ完了していないかを説明しようとしていた。その部屋を出て気づいた：

ドキュメントは、私が統合していたシステムに重複するクレームを持つ三人のVPを一度も名指ししなかった。
チームAのオンコールローテーションがマイグレーションウィンドウの制約であることを一度も認めなかった。
意図的にやらないことを一度も言わなかった。 つまり他のチームは自分たちの希望のフィーチャーがスコープ内だと仮定した。
構築後の統合システムを誰がオーナーになるかを一度も名指ししなかった。 つまり答えは重要になった時点で「誰でもない」になった。

アーキテクチャは問題なかった。ドキュメントは政治で失敗した。そして — 難しい方法で — 政治は設計の一部だということを学んだ。

今使うテンプレート

それ以来書いたすべてのデザインドキュメントには、この順序でこれらのセクションがある。政治的なものは荷重を持っていて、オプションではない：

1. 問題（一段落、ユーザーまたは操作上に可視）
2. 制約（チーム、予算、タイムライン、既存システム）
3. 提案（詳細の前の一段落のサマリー）
4. 非目標（これが明示的に*やらない*こと）
5. 検討した代替案（少なくとも二つ。それぞれ敗れた理由付き）
6. 技術設計（図と散文）
7. マイグレーション/ロールアウト計画
8. オーナーシップ（人間の名前。「プラットフォームチーム」は名前ではない）
9. 未解決の問い（まだわからないこと）
10. 決定ログ（レビューで何が、いつ、誰によって決定されたか）

誰もが期待するセクションは3、6、7だ。そこにアーキテクチャが住む。しかし セクション2、4、8がプロジェクトを出荷するか静かに殺すかを決める。

制約は脚注ではない

セクション2はレビューで最も議論されるべきセクションだ。技術設計ではない。制約だ。

制約はこういうものだ：

「チームAのオンコールローテーションはこれ以上アラートを吸収できない — 新しいサービスはトラフィックを切り替える前にゼロ追加ページのバーを満たさなければならない。」
「データベースマイグレーションウィンドウは四半期に2時間だ。それ以上を必要とする設計は出荷できない。」
「このプロジェクトの予算は追加インフラ支出ゼロドル — 既存のキャパシティ内に収めなければならない。」
「VP Xはこのフィーチャーをボードに対してQ3にコミットした。Q3を過ぎる設計はエンジニアリングのメリットにかかわらず政治的に高くつく。」

それらを書き下せば、政治的な会話をドキュメントに書き込む。 読んでいる人は今、何に同意または不同意しているかを知っている。代替案 — それらの制約を暗黙のままにして全員が同じ理解を共有していると望む — は六人が六つの異なるプロジェクトを持ってデザインレビューを去る仕組みだ。

非目標はスコープを守る方法だ

セクション4 — 非目標 — は任意のデザインドキュメントの最も高いレバレッジなセクションだ。

明示的に言う：「この提案はX、Y、Zを含まない。それらが欲しければ、別のドキュメントだ。」

健全なデザインレビューでは、非目標セクションはスコープクリープが早期に捕まえられる場所だ。それなしでは、スコープクリープが承認後の数ヶ月に静かに起きる。レビューにいなかったステークホルダーが自分たちの隣接する懸念がカバーされていると仮定し始める。

今では非目標セクションのないデザインドキュメントを承認することを断っている。非目標のないドキュメントは省略によってすべてに同意したドキュメントだ。

名前でのオーナーシップ、役職ではなく

セクション8 — オーナーシップ — は責任を割り当てるか、虚空に漏らすかを決めるセクションだ。

良い例：

オーナーシップ： Amal H.がロールアウトを所有する。ロールアウト後、インベントリチーム（DRI：Ben L.）が運用を所有する。SLOはops/inventory.mdに定義されている。安定稼働90日後、オーナーシップはプラットフォームチーム（DRI：Priya N.）が長期保守のために引き継ぐ。

悪い例：

オーナーシップ： プラットフォームチームがこれを所有する。

悪いバージョンはオーナーシップのように見えるが違う — 「プラットフォームチーム」はカレンダーを持たず、ポケベルを持たず、業績評価を持たない。人間を名指しすることで人と責任の間の関係を作る。チームを名指しすることで責任の拡散を作る。

レビューのために書くことと、承認のために書くこと

ほとんどのデザインドキュメントが間違える微妙な点：健全なレビューのために書くドキュメントは、承認シアターのために書くドキュメントとは同じではない。

レビューフレンドリーなドキュメント：

多くの非目標を持つ。
代替案を正直に列挙する。著者が最悪だと思うものも含めて。
本当に未解決のことで満ちた「未解決の問い」セクションを持つ。
レビュー後に記入される決定ログで終わる。

承認シアターのドキュメント：

不可避に提示された「計画」を持つ。
代替案をそれぞれ一文で却下する。
不十分な準備に見られたくないので未解決の問いがない。
「承認済み」で決定ログを事前記入している。

組織のデザインドキュメント文化が承認シアタードキュメントを報奨するなら、それは文化の失敗だ — でも自分のドキュメントから始めて修正可能だ。レビューフレンドリーなドキュメントを書いて、その一部が却下されることを受け入れろ。それがデザインレビューが常に機能するはずだった方法だ。承認率100%は承認プロセス0%だ。

2026年のひねり

AI支援の書き物がここで何かを変えている。今は20分でデザインドキュメントの「完成して見える」最初のドラフトを生成できる。技術セクションには素晴らしい — 構造的で、トレードオフが列挙され、一貫した散文スタイルで出てくる。

政治セクションには積極的に悪い。LLMは重複するクレームを持つ三人のVPを知らない。どのチームのオンコールが脆弱かを知らない。今四半期の予算のふりが実際の予算に対して何かを知らない。

現在のワークフロー：セクション3、6、7、9のドラフトをAIに任せる。セクション1、2、 4、8、10は自分で書く。 それらの散文もAIは助けられるが、実質は私から来なければならない。なぜなら人々の頭の中にあり、リポジトリにはないからだ。

私があらゆるデザインドキュメントに今問う一つの問い

デザインドキュメントを承認または却下する前に、著者に一つの問いを声に出す： 「これが書かれた通りに出荷されたら、誰が不満を持つか？」

具体的な人物を名指しできなければ、ドキュメントはレビューの準備ができていない。なぜなら具体的な人物は存在するから — 常に存在する — そして著者が彼らが誰かわからなければ、その人たちは第三ヶ月に「なぜ相談されなかったのか」を尋ねて現れる。

著者が彼らを名指しできれば、次のステップは「もう話したか？」だ。答えが「いや」なら、話しに行け。答えが「はい」なら、ドキュメントはおそらく準備できている。

その問いは私が持つ他のどの習慣よりも多くの手戻り月を救ってくれた。