「実装に入る前に設計を書いてほしい」と言われて、何をどこまで書けばいいか迷ったことはないでしょうか。
テックリードを目指して学んでいる立場から見ると、Design Doc は設計の合意を取るための道具で、きれいな仕様書とは目的が違います。
Google の設計文書文化を書いた公開記事をたどると、書く中身よりも「何のために書くか」がはっきりしていました。
その定義と、レビューを回すための運用をまとめます。
Design Doc は仕様書ではなく「合意と記録」の道具
Google の Malte Ubl 氏による解説によれば、Design Doc はコーディングに着手する前に主要な作者が書く、比較的インフォーマルな文書。
役割は二つあり、ひとつは設計に合意するプロセスを進めること、もうひとつは現在と将来の実装者・保守者・関係者のために設計を残すことです。
つまり読者は「これから作る人」だけでなく、半年後に触る誰かも含まれる。
もうひとつ強調されているのが、判断の際に検討したトレードオフを書く点です。
同じ記事は、採用しなかった代替案とその理由を並べることも挙げています。
何を作るかより、なぜその案を選んだかが本体だと考えると、書く分量の配分も決めやすくなるはず。
何を書くか：5つの節から始める
厳密なテンプレートは無く、プロジェクトにいちばん合う形で書けというのが第一の原則として置かれています。
そのうえで典型的な構成として、次の5つが挙げられていました。
- コンテキストとスコープ（前提となる背景を簡潔に）
- ゴールと非ゴール（やらないことを明記する）
- 実際の設計（概要から詳細へ、トレードオフを中心に）
- 検討した代替案（なぜ選ばなかったか）
- 横断的な関心事（セキュリティ・プライバシー・可観測性）
非ゴールを書く欄があるのは、レビューでの論点の発散を止める効き目があります。
設計の詳細については、システムの位置づけを示す図、高レベルの API のスケッチ、データの保存方式、新規性のあるアルゴリズムだけの擬似コード、といった粒度が示されていました。
逆に、形式的な定義のコピー貼りつけや、網羅的なスキーマの列挙は避けるよう書かれている。
分量の目安は大きめのプロジェクトで10〜20ページ、小さな改善なら1〜3ページのミニ版。
Design Docs at Google（Malte Ubl）
レビューを回す運用：4つの段階
書きっぱなしにしないために、文書のライフサイクルが4段階で整理されています。
最初が作成と高速な反復で、近しい共同作業者と一緒に短いサイクルで直していく段階。
次がレビューで、軽いコメントのやり取りから正式な会議まで幅があると説明されています。
三つ目が実装と反復。
ここでのポイントは、現実が計画とずれたら文書のほうを更新するという扱いにある。
最後が保守と学習の段階で、後から入る人にとっての入口として機能します。
レビューを会議だけに頼らず、コメントで済む段階を先に通すと、合意までの時間はかなり縮められるはずです。
書かないほうがよい場合と、よくある失敗
すべての作業に Design Doc が要るわけではありません。
同じ記事は、解が自明でトレードオフがほとんど無いときは省いてよいとしています。
高速なプロトタイピングが本質の場面も同様で、ただし判明している問題は記録しておく価値がある。
いちばん避けたい失敗として挙げられているのが、「どう作るか」しか書いていない実装マニュアルになってしまう状態です。
なぜその案が他の案より良いのかが書かれていない文書は、レビューする側が判断できません。
代替案の節が空のままなら、それは設計がまだ一案しか無いというサインでしょう。
最後に
Design Doc の要点は、合意を取るための文書であって、成果物の説明書ではないという一点に集まります。
トレードオフと代替案を書き、非ゴールで線を引き、実装中にずれたら文書を直す。
この運用が回り始めると、設計の議論が個人の記憶からチームの資産に移ります。
まずは1〜3ページのミニ版から、代替案の節を必ず埋めるところを試してみてはどうでしょうか。
テックリードが担う領域そのものは、3つの軸で整理した記事にまとめています。
シニアエンジニアから何が変わるのかは、こちらで整理しました。
以上です。
コメントを残す