ソフトウェア開発では、コードを書く前に設計を言葉にしておくことがある。今回取り上げる記事は、その「design doc（設計書）」をどう書けば役に立つのかを、実務経験に基づいて整理したものだ。単なる文書作法ではなく、どの場面で書くべきか、何を入れて何を入れないかまで踏み込んでいるのが面白い。設計書を“面倒な儀式”として扱う人ほど、読み直す価値がある内容だと思う。
元記事の筆者 Michael Lynch は、Google、Microsoft、自分の会社で design doc を書いてきた経験から、効果的な設計書の書き方をまとめている。主張の軸はかなりはっきりしていて、design doc は「実装前に大事な判断を洗い出し、チーム内の認識を合わせるための道具」だという。雑にコードを書き始めてしまうと、あとで間違った方向に大きく進んでしまうことがある。設計書はそれを防ぐ。
記事では、筆者が実際に作った例として、キャッシュ層を追加する web app の設計書も示されている。コードを書く前に設計書を作り、その設計に沿って実装を進めている点が印象的だ。しかも、その文書は趣味の一人開発なら少し大げさなくらいの分量だが、複数人が関わる仕事ならこのくらいの密度が必要になる、と説明している。
書くべきタイミングについては、複雑さや危険度が高いほど価値が増すと整理している。複数人で分担して作る、フルタイムで3か月を超える、何年も本番で動かす、他チームと協業する、要件が曖昧、セキュリティや法務のような重大な失敗を設計段階で避けたい、こうした条件が当てはまるなら設計書を書くべきだという。2つ以上当てはまるなら、ほぼ確実に投資する価値があるとも述べる。
一方で、設計書は長ければよいわけではない。1ページで足りることもあれば、5チームの承認が必要な50ページ級になることもある。重要なのは長さではなく、チームの目的、リスク、締切、文化に対して適切な投資かどうかだ。場合によってはゼロ、つまり書かない判断もありうる。
内容面では、「全部を決めすぎない」ことを強調している。もし細部まで書き込みすぎると、設計フェーズの時点で実装そのものを書いてしまうことになる。そこで筆者は「その判断を間違えたときの損失はどれくらいか」を基準に入れるべき内容を選べと勧める。たとえば、最初に C++ で web app を作ってしまい、20万行後に Ruby on Rails のほうが適切だったと気づくのは致命的だが、一覧表示を25件ずつにするか一度に全部出すかは、数時間で直る程度の話なので設計レベルではない、という具合だ。
設計書の構成としては、タイトル、metadata、objective、background、related documents、goals、non-goals、scenarios、diagrams、glossary などを挙げている。たとえばタイトルは短く、言いやすく、目的が伝わるものがよい。metadata には作者、作成日、正規URL、承認者と承認日を入れる。objective は誰が読んでも分かる一文で、background はなぜこの仕事をやるのかを説明する。goal にはユーザーやチーム、会社への効果を書く。non-goals は、読者が勝手に範囲内だと思い込みそうなものを明示的に外すための欄だ。
さらに、シナリオで完成後の使われ方を描き、diagram で構成やデータの流れを見える化する。glossary は、チーム外の人や新しいメンバーが知らない用語を補う役割を持つ。全体として、design doc は「思いつきを並べる紙」ではなく、読んだ人が設計の意図と境界線を理解できる文書であるべき、というメッセージになっている。
この記事でいちばん納得感があるのは、design doc を完成品ではなく、レビューのための装置として捉えている点だと思う。設計書は自分の考えをきれいにまとめるための作文ではない。むしろ、他人が「ここは違うのでは」「この前提は危ない」と言いやすくするための土台だ。だからこそ、背景、目的、非対象、図、用語集のような項目が効いてくる。読む側が迷わない形にしておくと、議論が実装の枝葉ではなく、重要な判断に寄る。
これはプロダクト開発だけでなく、社内ツールや基盤開発にもかなり効く考え方だと思う。特に、あとから触る人が多いシステムでは、コードより先に「なぜそうしたか」を残す価値が大きい。実装は見れば分かるが、捨てた案や却下した案は見えないからだ。設計書はその空白を埋める。レビューのたびにゼロから説明し直すより、文書に固定したほうがチームの認知コストは低い。
一方で、この手の話には落とし穴もあると思う。設計書の項目が豊富だからといって、全部を埋めればよいわけではない。記事もそこは警戒していて、すべての設計判断を文書化すると、設計と実装の境目が消えてしまうと指摘している。ここはかなり重要だ。文書が厚くなるほど安心した気になるが、実際には小さな実装詳細まで合意形成の対象にしてしまい、議論が重くなることがある。
だから本当に必要なのは、判断基準の線引きだと思う。たとえば、後から変えやすい UI の細部まで設計書で固定してしまうと、機動力が落ちる。逆に、データ保存方式や権限設計のように後戻りしづらい部分を曖昧にしたままだと、あとで高くつく。筆者が「損失が大きいものだけ書け」と言うのは、このバランス感覚を持てということだろう。設計書は万能ではないが、線引きの下手なチームほど効く。そこは少し皮肉だ。
面白いのは、記事が design doc を持ち上げつつ、書かない選択も認めていることだ。これは見落とされがちだが、かなり健全だと思う。文書文化は、放っておくと「とにかく書け」に寄りやすい。でも実際には、小さな修正や短命な試作にまで重い設計書を求めると、速度だけでなく気力も削る。設計書は安全装置であって、儀式ではない。
この視点は、今の開発現場でますます大事になるはずだ。生成AIで実装の初速が上がるほど、逆に「何を作るか」「何を作らないか」を先に決めないと、あとで迷走しやすい。コードを早く書けるようになっても、設計の判断まで自動化されたわけではないからだ。だからこそ、重い変更には文書を、軽い変更には軽い合意を、という使い分けが必要になる。この記事はその境界をかなり実務的に示していて、単なる文書作法の解説よりずっと役に立つ。
