Claude Codeで日常的に開発するようになったが、個人開発では仕様書なぞ書かずに、都度必要なドキュメントを書き捨てるような運用が多い。
一方で、会社の中で行っているチーム開発や、責任の重い大企業へのB2B開発では、依然として仕様書が必須どころか、よりその重要度が増していると感じる。
従来の仕様書には2つの用途があった。
- 開発チームへのインターフェース（何をどう作るか）と、
- 顧客へプロダクトの振る舞いを説明する際のSingle Source of Truth (SSOT)。
どちらも「人」に対するインターフェースだが、役割は異なる。
自分でアレコレやってみた結果、コーディングエージェントが実装を担う時代の仕様書の役割を、3つに再定義できると感じている。
役割1: 開発に携わる人達が「つくるもの」のイメージを揃える
この役割は従来の仕様書が担っていたものと大きくは変わらない。 SWE、Designer、QAなど、役割によって視点が違う。同じプロダクトを見ていても、頭の中にある「完成形」がずれていることは珍しくない。何で揃えるかが重要となる。
開発チームにとってのいちばん大事な共通項は、「利用者にとっての振る舞い、利用者が解決したいこと」。これが「イメージ」のセンターピンだと思う。
システムとしての振る舞いやUIのあり方は、思い切って別ドキュメントに預けていい。仕様書が担うべきは**「Why / What for whom」であり、「How」**は分離できると思っている。
開発チームの一員としてのコーディングエージェント
一方で変化が大きい点として、今や開発チームの中には、Claude Codeのようなコーディングエージェントも含まれる。自分の場合、日々の実装の大半をClaude Codeに委ねており、仕様書の読み手として人間と同じくらいの比重を占めている。
仕様書は人間が読んで理解できるものであると同時に、その人間がコーディングエージェントに情報をパスしやすい形であることが、新要件になっている。
そもそもコーディングエージェントにコンテキストを渡す際、ベストプラクティスとなる形式は「仕様書」ではないことが多い。CLAUDE.md（プロジェクトのルールや方針を記述するファイル）やSKILL（エージェントの定型タスク定義）、ADR（Architecture Decision Record: 設計判断の記録）といった形式に転換して渡すことになるだろう。
よって、人間にとって読みやすく、かつエージェント向けのコンテキストやプロセスへ変換しやすいこと。この2つを両立するものが、これからの仕様書だ。
それがどういった形なのかは、私もまだ掴めていないが、仕様書のフォーマットが進化を迫られていることだけは確定的だ。
役割2: 「実際に作られたもの」とイメージの乖離を埋める
仕様書から、実際に開発を始めるとイメージと違う着地になることは多い。それは実際の開発にはいろんな制約があり、そのトレードオフに意思決定があるからだ。
コーディングエージェントに実装を委ねていく場合も、トレードオフは発生し続ける。エージェントは技術的制約に直面したとき、人間のように相談せず独自に判断してしまうことがある。意図しないトレードオフが暗黙的に発生しやすく、なんなら人間だけのチームより頻繁に起きる。
この乖離を「乖離として放置しない」ため、以下のような基準の役割を担うのが仕様書となる。
- 仕様書があることで、「トレードオフを、意図に照らす」ことができる
- 開発中に起きる仕様の変化を、差分として追随させる
役割3: 「使う人にとっての正しい挙動」の拠り所
生成AIを使えば、ソースコードからシステムの挙動を記述するハードルは間違いなく下がった。AIにコードを検査させて、そこから出た説明を顧客に横投げすることもできる。
しかし生成AIは推論器だ。どれだけコンテキストを与えても、出力は推論であり正確ではない。
「Xっぽいです」は言えても「Xです」と言い切るのは、ビジネス上は当たり前に怖い。だから仕様書がSSOTとしてその役割を埋める。
仕様書とコードを追随させるプロセスが重要に
仕様書を元にコードを生成するのと同じくらい、実現可能なコードを元に仕様が変わっていく機会は多い。
仕様書を正しい挙動の拠り所とするなら、コードの変更に追従して仕様書がメンテされ続けなければ意味がない。ただ生成AI以前の世界ではこれをやりきるのが難しく、数々の大事故を引き起こす原因となっていた。
- ナイト・キャピタル事件: 本番環境に古いコードが残存し、仕様と実装の乖離が4億ドル超の損失を招いた
- Cloudflareの障害: WAFルールの変更が既存の挙動仕様と整合しないまま適用され、大規模障害に至った
いまのコーディングエージェントを前提とした世界では、仕様書とコードを動的に同期させるプロセスが現実味を帯びている。たとえばPRごとにエージェントが仕様書との差分を検出し、仕様変更のドラフトを自動生成する。レビュアーはコードレビューと同時に仕様書の更新もレビューする。こうしたワークフローにトライするタイミングだと思う。
B2Bにおいては仕様書がビジネスの境界線になりうる。「仕様です」と言い切れるかどうかが顧客との信頼関係を左右する。
だからこそ、仕様書の鮮度を保つことは技術課題であると同時にビジネス課題でもある。
まとめ
- コーディングエージェントが実装を担うようになっても、仕様書の役割は消えない。イメージを揃える、乖離を埋める、正しい挙動の拠り所となる。
- むしろこの3つは、エージェントの介在によって重要度が増している。
- 加えて、仕様書のフォーマットはエージェントへの伝達しやすさという新しい要件を引き受けることになる。エージェントへのコンテキストへの変換器も必要になるだろう。
- コードが変わって、仕様が変わることに追随するのは過去難しく大きな事故の原因となってきた。しかし今なら、この同期プロセスは技術的に現実味を帯びてきている。
余談
「この文章はAIを使わずに書きました」的な前置きの文章をよく見かけるようになったが、端的に無駄な一文で、ダサくない？と思うんだけどどうですかね？
