【ITニュース解説】The Spec Is the Fast Path

多くの人が、ソフトウェア開発において設計書や計画書といったドキュメントを作成することは、開発の速度を遅らせる原因だと考えている。特に、初期段階のスタートアップ企業では、ドキュメント作成を省略し、「とにかく作って、それから考える」というアプローチが一般的だ。ドキュメントは、成熟した大企業だけが費用をかけられる「贅沢品」であり、小規模な組織には不要な「負担」だと見なされがちである。しかし、この考え方は必ずしも正しくないと筆者は自身の経験に基づいて主張する。むしろ、適切にドキュメントを作成することが、開発を加速させる「近道」になるというのだ。

筆者はCendraという企業で、創設エンジニアの一人として12ヶ月間働いた経験を持つ。この期間中に、255の設計仕様書、207の実装計画書、そして17の運用手順書を作成した。これだけの数のドキュメントを作成しながらも、同時に377回の本番リリースと482回のマージコミットを達成している。これは、およそ22時間ごとに一度のペースで本番リリースが行われた計算になる。この実績は、ドキュメント作成が開発速度を阻害するどころか、むしろ高い開発効率と並行して行われたことを示している。これらのドキュメント作成と実際のコードのリリースは、同じ人物によって、同時に行われたものだ。

もちろん、ドキュメントの作成が直接的にこれらのリリース頻度を引き起こしたと断言することはできない。もしドキュメントが全くなかったとしても、同じかそれ以上のリリースがあった可能性も否定できないため、因果関係を直接証明するものではない。しかし、ドキュメントが存在することで、開発プロセスから特定の障害が取り除かれたことは明確である。その具体的なメカニズムを理解することが、ドキュメント作成がもたらす価値を判断する上で重要となる。

筆者が設計を始める前にドキュメントを作成する最も正直な理由は、他者とのコミュニケーションのためではない。それは、自分がその問題を本当に理解しているかどうかを確認するためだ。ドキュメントを書き進める中で、特定の段落がどうしても書けない瞬間が訪れることがある。それは、表現が難しいからではなく、自分が記述しようとしている「概念」自体がまだ明確にまとまっていないからだ。例えば、「この二つの条件が同時に真になったらどうなるのか？」「この状態の所有者はどちらのシステムか？」「まさか起こらないだろうと思っていた『第三のケース』が発生したら、システムはどう振る舞うのか？」といった疑問が浮かび上がる。

この「書けない段落」こそが、その設計に潜む欠陥の兆候である。この段階で欠陥が表面化すれば、修正にかかるコストは「段落を書き直す」程度で済む。もしドキュメントなしで開発を進めた場合、同じ欠陥は、後になって必ず表面化する。それは、データベースのスキーマが完成した後かもしれないし、その設計に依存する二つの機能が既に実装された後かもしれない。あるいは、本番環境でデータが流れ始めた後かもしれない。ドキュメント上で発見された場合と、実際にコードとして実装された後に発見された場合とでは、修正にかかる時間も労力も比較にならないほど大きくなる。多くの人が「思ったより時間がかかった」と感じる主な原因は、この「欠陥の発見が遅れたことによる手戻り」に他ならない。したがって、設計の誤りを最も安価に修正できる場所は、ドキュメントの中である。二番目に安価な場所は、その安価さに遠く及ばない。これが、ドキュメント作成が開発を加速させるという主張の根幹にある考え方だ。

筆者が作成した設計仕様書、実装計画書、運用手順書という三つの種類のドキュメントは、それぞれ異なる目的を持ち、異なる頻度で作成された。

設計仕様書は、「そのシステムが何をすべきか、なぜそれをするのか」を明確に定義する。これには「意図的に何をしないのか」という非目標も含まれる点が重要だ。この「非目標」の記述は、開発途中で機能が不必要に拡大することを防ぐための強力な防御策となる。「これは明確に範囲外だと明記されている」という事実は、議論の余地をなくし、開発者の負担を軽減する。一方、「私はこれを行うべきではないと思う」という個人的な意見は、単なる議論のきっかけにしかならない。

実装計画書は、「どの順序で実装を進めるのか」「何が壊れる可能性があるか」「何が先に完了している必要があるか」を明確にする。設計が正しくても、その実装順序が安全であるとは限らないため、この計画書は不可欠だ。

運用手順書は、「そのシステムを本番環境にどうデプロイするのか」「何か問題が発生した場合にどうやって元に戻すのか」を記述する。例えば、段階的なロールアウト、機能フラグを使ったリリース、ロールバック手順、異なるリポジトリ間の依存関係の順序付け、デプロイ後の動作確認、インシデント発生時の対応などが含まれる。運用手順書の数が他のドキュメントに比べて少ないのは、一度作成すれば、それが記述する「繰り返し発生する運用作業」に対して何度も活用できるためである。筆者自身、運用手順書は当初、作成をためらっていたが、結果として最も明確な効果をもたらしたと述べている。

運用手順書の重要性は、特に「単一障害点」の解消という点で際立っている。筆者のチームでは、リリースは複数のリポジトリにまたがっており、厳密なデプロイ順序が必須だった。例えば、バックエンドのAPIがデプロイされてから、それを呼び出すフロントエンドがデプロイされる必要があった。この複雑な順序は、筆者の頭の中にしか存在していなかった。筆者はそれを正確に実行できる「有能なエンジニア」として振る舞っていたが、それがまさに問題だった。複雑な手順を常に正確に実行できるエンジニアは、その人が病気になったり、飛行機に乗っていたり、あるいは退職してしまったりする日まで、文書化されたプロセスと区別がつかない。リリース順序を知っている人間であることは、一見すると強みのように見えるが、実際には「強さの衣をまとった単一障害点」に他ならない。そして、それが「良いことだ」と感じてしまうことが、問題解決を妨げる原因となる。これを文書化することが、根本的な解決策だった。さらに、文書化された手順は他の開発者によるレビューが可能になり、予期せぬ欠陥や改善点を発見できるという、当初は予想していなかった副次的なメリットも生まれた。

ソフトウェア開発における真のボトルネックは、コードを「タイプする」速度ではない。最もコストがかかるのは、「手戻り（rework）」と「調整（coordination）」だ。設計仕様書は、この両方の問題に効果的に対処する。

手戻りについて言えば、設計上の欠陥がドキュメントの段階で発見されれば、その修正はドキュメントを編集するだけで済む。これは、コードが書かれた後や本番環境にデプロイされた後に発生する手戻りに比べて、はるかに安価で迅速である。

調整について言えば、明確に記述されたインターフェースがあれば、複数の開発者が会議を頻繁に行うことなく、それぞれが並行して開発を進めることができる。筆者の経験では、AIエンジニアがLangGraphサービスやRAGパイプラインを担当し、筆者はその上に構築されるプロダクトレイヤー（エージェント設定、ナレッジベース、ユーザーインターフェースなど）と、両者間の連携部分を担当した。AIエンジニアが担当するオーケストレーションの内部設計には深く関与しなかったが、明確な仕様が存在したため、両者は記述されたインターフェースを目指して同時に開発を進められた。記憶頼りのインターフェースでは、このような並行開発は不可能だ。

そして第三の要素として、「完了の基準」が重要となる。筆者は、ビルドが成功しただけでは「完了」とはせず、「本番環境のログ、データベース、あるいは実デバイス上でその機能が正しく動作していることを確認する」までを完了の基準とした。これは、テストをパスしてもなお問題が発生するケースを経験した結果である。モバイル機能が全てのテストをパスしたにもかかわらず、実機で再現可能な問題があり、リリース後に削除せざるを得なかった例が示しているように、設計し、実装し、そして本番環境で検証する、という三段階のステップが必要だ。この最後の検証ステップにおいて、仕様書に書かれた内容が真であったかどうかが明らかになる。

これらのドキュメントは、当初意図していなかったが、別の価値ももたらした。それは、筆者の仕事の「証拠」として機能する点である。自分がコードを投入したリポジトリは全て他者の所有物であり、自分が何にどれだけ貢献したかを証明するのは難しい場合がある。しかし、ドキュメントはリポジトリ内に独立した形で存在し、筆者の貢献の範囲と所有権を裏付ける記録となる。これは、NDA（秘密保持契約）の下で開発されたソフトウェアの場合、特にその価値が高い。単に動作するソフトウェアを生み出す習慣よりも、自身の仕事の記録も同時に生み出す習慣の方が、後に価値を持つ場合があるのだ。筆者自身の個人プロジェクトでも、コードとともに25の設計仕様書がコミットされている。また、大規模言語モデル（LLM）を活用した開発においても、仕様書は重要な役割を果たす。LLMが生成したコードの出力が正しいかを検証するための「基準点」となり、LLMを単なる「高速かつ希望的」なツールではなく、「安全な」ツールとして利用することを可能にする。仕様書、テスト、そして本番環境での検証は、LLMによって一人のエンジニアが広範な領域をカバーすることを可能にするための、不可欠な支えなのだ。

もちろん、全ての変更に対してドキュメントが必要なわけではない。変更の影響範囲がドキュメント作成のコストよりも小さい場合、それは単なる儀式となり、ドキュメントの評判を悪くするだけである。筆者の経験則では、意思決定を覆すコストが高い場合、他の開発者が依存する境界を越える変更の場合、あるいは導入される状態が自分の記憶よりも長く存続する場合にドキュメントを作成すべきだと考える。単なるテキストの修正、依存ライブラリのバージョンアップ、局所的なバグ修正などは、これらの条件に当てはまらないため、ドキュメントは不要である。

また、ドキュメントの「数」が「質」を保証するものではない。255のドキュメントが全て優れた内容であるとは限らないことも認識している。数の多さは、あくまで「一貫してドキュメントを作成する習慣があった」ことの証拠でしかない。完璧な順序で作業が進まないこともあり、時には問題を理解するためにまず試作コードを書き、そこから得られた学びを後でドキュメントにまとめる方が効率的な場合もある。そのようなプロセスで作成されたドキュメントも、十分な価値を持つ。

ドキュメント作成という習慣は、一見すると開発速度を低下させるように思えるかもしれないが、実際には初期段階で潜在的な問題を特定し、手戻りのコストを削減し、チーム間の協調を促進し、長期的な保守性や証拠能力を高めることで、結果的に開発プロセス全体を加速させる有効な手段となる。