仕様駆動開発(SDD)って、本当に不要なの？
仕様駆動開発なんて要らない、やめておけ。
仕様駆動開発不要論が界隈を飛び交っています。
しもしさんの「仕様駆動開発はやめた方がええ」という記事を読んで、共感しました。めちゃくちゃわかる。でも、うーん、ちょっと待てよ、と。
人の意見を鵜呑みにせずに、いったん自分の中で本当に不要なのか考えてみたいと思いました。
仕様駆動開発不要論について
しもしさんの主張を整理すると、
- 実装に関するドキュメントは不要で、仕様はすべてコードにある。
- ドキュメントとコードの両方をメンテナンスするコストが大きすぎる。
- AIエージェント時代にはドキュメントの更新が確率的で、トークンの無駄も大きい。
コードは最新なのにドキュメントは半年前の設計のままってことありません？ 新しく入ったメンバーがドキュメントを信じてコードを読むと、現実のコードとの乖離に混乱する。これって、ドキュメントがないよりタチが悪いんですよねぇ。
さらに、AIにドキュメントを更新させると、やるときとやらないときがある。気分屋で確率的なんですよね。
なので、実装ドキュメントを常にメンテし続けるのは割に合わないという主張に、私も激しく同意です。
そもそも仕様駆動開発(Spec-Driven Development)とは何なのか？
まずここで、仕様駆動開発という言葉の意味を整理しておきたいと思います。
仕様駆動開発って言葉は意味が広くて曖昧な言葉のため、正直何を指して「仕様駆動開発」というのかは、わかりにくいんですよね。どのツールを使うのかだったり、その人が属している業界や派閥によって言ってることが変わるので共通認識が得られにくいというか。特にSIerの人と自社Webサービス開発企業に勤める人では、見ている景色がまったく異なります。私はどちらの企業にも勤めているので、両者の違いがよくわかります。
X上で盛り上がっている議論を見ていると、仕様書は必要だろ という話と、仕様駆動開発が不要 という話がごっちゃになっているように感じます。この二つは似ているようで全然違う話なので、ここを整理しないと議論が噛み合わないと思います。
多くの人は、「Spec(仕様書)を固めてからコーディングに取り掛かる開発手法」という広い意味で「仕様駆動開発」という言葉を使っているように思います。
仕様書が必要というのは、コードを書くときに仕様書がないなんてありえないという話です。
仕様書なしでコードを書くなんてけしからんという意見もチラホラ。
ただ、これは仕様駆動開発の話とは、ちょっと論点がズレています。（と私は感じています
仕様駆動開発とは、単に仕様書があるかないかという話ではありません。仕様が実装を駆動している状態を指す言葉です。 （と私は考えています
仕様駆動開発では「何を作るか」を仕様書に明確化し、それを唯一の真実の情報源 として開発を進めます。仕様書を「生きたドキュメント」としてコードと同期的に管理するのを推奨しています。
つまり仕様駆動開発しようとすると、コードと仕様書を常に最新の状態に同期させて管理する必要があります。
これがかなり大変で難しいんですよ。。。
これは例えると、OpenAPIのスキーマを先に定義して、そこからサーバーのスタブやクライアントコードを自動生成する。あるいはProtocol Buffersでインターフェースを決めて、それに沿って各サービスを実装していく。仕様をSingle Source of Truthとして据えて、実装はそこから導出するという開発スタイルのことです。
仕様が実装を駆動しているなら、仕様とコードがズレることはないハズです。自動生成されたコードは仕様と一致していることが保証されるからという前提の元で成り立っています。
ところがですね、ここに落とし穴があります。仕様を信頼できるソースとして維持し続けるのは、実際にはかなり無理があるんすよ。 仕様駆動開発をやってみるとわかるのですが、完全に無理ゲーです。
まず仕様書とコードを二重レビューするのがしんどい。
それからAIに仕様書を渡して実装すると、確率的にどこかの時点でズレが発生するんですよ。仕様書を100%反映して実装してくれるとは限らないし、微調整はコードだけをいじる場合もあるし、コードから仕様書に反映しようとしても確率的になるし。。。
しかもそのズレはコードが大規模になればなるほど、指数関数的にズレが大きくなります。
そもそも実装の前に完璧な仕様書を用意すること自体がかなり難しい場合が多いです。
OpenAPIのスキーマだって、最初は自動生成していたのに途中から手で直し始めて、気づいたらスキーマとコードが別々に進化しているなんてことは珍しくないです。仕様が実装を駆動している状態を保ち続けるには相当な規律が要るし、それが崩れた瞬間にただの古いウソ仕様書に成り下がります。
結局のところ、信頼できるソースになれるのはコードとテストだけです。 仕様は考えるためのツール、合意を取るためのツールとしては優秀だけど、Single Source of Truthとして君臨し続けるには脆すぎじゃないですか。
だが、新規開発では仕様がないと詰む
一方で、不要論の反対意見として
という意見もあります。
でも、ま、これは、仕様駆動の話というより、仕様書が必要かどうかという話ですね。
大規模な開発であればあるほど、仕様書は必要になります。
例えば、今から家を建てるとして、設計図なしでいきなり大工さんにいい感じの家を建ててとお願いしたらどうなるか。たぶん、柱を立ててからここにトイレ入らないなってなります。壁を作ってから窓の位置が逆だったと気づく。完成してからそもそも2階建てが良かったんだけどなんて言われた日には、もう最初からやり直しです。
新規開発でまだコードが存在しない段階では、コードが仕様だと言いたくても、仕様となるコードがそもそもない。 何もないところにいい感じに作ってと言っても、いい感じの定義は人によって違います。
以前、新規プロダクトのプロトタイプを設計したとき、チーム内で もうAIの時代だしバイブコーディングで作りたいという空気がありました。 みんなAIコーディングツールに慣れてきた頃で、謎の自信があったんですね。じゃあということで、各自がClaude CodeやCursorを使ってそれぞれ思い思いにコードを書き始めました。
1日後、プルリクエストを突き合わせたらむちゃくちゃな惨状でした。APIのレスポンスのデータ形式が合わなかったり。エラーハンドリングの方針もバラバラ。
結局、その後、設計からやり直す羽目になりました。最初に半日かけて仕様を決めておけば、この手戻りは起きなかったはずです。
新規開発における仕様書は、チームの共通言語です。こういうものを作る、全体のアーキテクチャはこうで、APIはこの形式で返す、エラーはこう扱う。これがないと、各自が頭の中にある正解に向かってバラバラに走り出します。AIが優秀になっても、AIに渡すプロンプトの前提がチーム内で揃っていなければ、できあがるコードは揃いません。
一人で開発している場合でも同じです。まあだいたいこんな感じで、と曖昧なまま書き始めると、途中でこのエンドポイントって認証いるんだっけとか、このデータどのテーブルに入れるんだっけとか、自分自身との会議が始まります。最初に整理しておけば、その時間はゼロにできます。
ちなみに、ここで言う仕様書は何十ページもある大層なドキュメントではありません。マークダウンで1〜2ページ、APIのエンドポイント一覧とリクエストやレスポンスの形式、主要なビジネスルール、技術的な制約などを書いたSpecファイルのことです。これだけで十分です。精緻さより、チーム全員が同じ絵を見ていることのほうが大事です。粗くてもいいから認識を揃えるために作るのです。それが新規開発で仕様書を書く最大の理由です。
作ったら仕様書は捨てろ
ここは、本記事で最も私の主張したいことです。
新規開発では仕様書を書きますが、実装が終わったら捨てましょう。
せっかく書いたのに？と思うかもしれません。でも、実装が終わった時点で、仕様書の内容は100%コードに反映されているはずです。反映されていなかったら、それはバグです。つまり、実装完了後の仕様書はコードの劣化コピーでしかないです。
これは料理のレシピに似ています。レシピを見ながら料理を作るのは当然です。でも完成した料理の横にレシピを添えて出す必要はない。食べる人にとっては目の前の料理がすべてです。レシピを更新し忘れたまま味を変えてしまったら、次にレシピを見た人は間違った料理を作ることになります。塩小さじ1と書いてあるのに実際は大さじ1だった、みたいなことが起きる。それなら、作り終わったらレシピは処分して、味を知りたければ直接味見してもらった方がいいでしょう。
しもしさんの記事にもあった通り、ドキュメントとコードの二重管理はコストが高すぎます。 仕様書の役目が終わったら潔く消して、コードだけを生きたドキュメントとして残す。これが一番合理的じゃないですか。
私は、実装完了後に仕様書をアーカイブフォルダに移すか、PRのdescriptionに残す程度にしています。なぜこの設計にしたかという意思決定の経緯だけは、コミットメッセージやADRに軽く残しておく。仕様の詳細は残しません。コードを読めばわかるからです。
新しいメンバーが入ってきたときに困らないか？という声が聞こえてきそうですが、正直、それはコードの可読性とテストの充実度でカバーすべき話だと思っています。仕様書があっても古ければ新メンバーは余計に混乱します。コードを読めば設計がわかる構造にしておく方がずっと健全な気がしてます。AIにお願いしてコードから仕様書を逆作成してもらってもよいのです。
仕様書を消さないとどうなるか、二重管理という地獄
捨てろと言われても踏ん切りがつかない人のために、仕様書を残し続けるとどうなるか書いておきます。
以前いたプロジェクトでは、Confluenceに詳細な仕様書を残す文化がありました。API仕様、画面仕様、データベース設計、全部です。最初はうまくいきます。新しいメンバーにはまずこのページを読んでと案内すれば済み便利だなと思います。
ところがどっこい、問題は、開発が進むにつれて、この仕様書の内容とコードが違うんですけど、という質問がSlackに飛んでくるようになるんですよ。最初は更新忘れてた直すねで済んでいました。でも段々とその頻度が増えていく。あるフィールドが仕様書では必須になっているのに、コードではオプショナルになっている。仕様書にはエンドポイントが10個載っているのに、実際には3個削除されて2個追加されている。ステータスコードの定義も微妙にずれている。。。まじでこうなると地獄です。
こうなると、仕様書を読むたびにこれ今も正しいのかなと疑いながら読む羽目になります。結局コードを確認しないと安心できない。疑心暗鬼状態。それなら最初からコードだけ読めばいい話で、仕様書を経由する分だけ時間の無駄です。
もっとつらかったのはバグ対応のときで、仕様書ではこうなっている、でもコードはこう動いている。どっちが正しいのか判断できない。PMに聞いても仕様書通りに動くべきだと思うけど...と歯切れが悪い。結局、過去のSlackのやり取りやPRのコメントまで遡って、この変更は意図的だったのかを調査する。こういう 遺跡を掘り起こして検証する考古学みたいな発掘作業、経験がある人も多いんじゃないでしょうか。
この苦しみの根っこは、真実のソースが二つあることです。ソフトウェア開発において真実のソースは一つであるべきで、これはSingle Source of Truthという概念としてデータベース設計でよく言われますが、仕様書にもそのまま当てはまります。仕様書とコードの両方を正として扱おうとした瞬間に、必ず矛盾が生まれる。矛盾が生まれた瞬間に、チームの認知コストが跳ね上がります。
そしてこの二重管理の問題は、AIエージェントを使った開発ではさらに深刻になります。人間なら仕様書とコードが食い違っていても、経験や文脈から「たぶんコードの方が正しいだろう」と判断できることがあります。でもAIにはそれができない。AIは渡された情報をすべて等しく信頼します。仕様書に「このフィールドは必須」と書いてあってコードではオプショナルになっていたら、AIはどちらに従えばいいかわからない。あるいは仕様書の方を正として、わざわざコードを仕様書に合わせて書き換えてしまうこともある。それがバグの原因になります。
実際に私が経験したケースでは、古い仕様書をコンテキストに含めた状態でClaude Codeに改修を依頼したところ、すでに廃止されたAPIエンドポイントを復活させるコードを書いてきたことがあります。仕様書にはそのエンドポイントがまだ載っていたから、AIはそれが現役だと判断したわけです。人間なら「このエンドポイント、最近使った覚えがないな」と気づけるかもしれませんが、AIにはそういう肌感覚がない。与えられた文書を素直に読んで、素直に従います。だからこそ古い仕様書を残しておくことはAIにとって有害なノイズになるんです。
AIに正しい仕事をさせたければ、正しい情報だけを渡す必要があります。古い仕様書が混ざっていると、AIの出力の精度が落ちる。トークンも無駄に消費する。しもしさんの記事でも指摘されていた通りです。仕様書を消すことは、人間のためだけでなくAIのためでもあります。
だから私は仕様書を捨てろ派です。残しておきたい気持ちはわかるのですが。。。でも残した仕様書は、メンテされなければ負債になります。人間を混乱させるだけでなく、AIまで混乱させます。メンテし続けるコストはほとんどの現場で割に合わない。コードという唯一の真実だけを残す方が、長い目で見ればチーム全体が楽になります。
既存コードの改修に仕様書はいらない
じゃあ既存コードの改修はどうかというと、これは明確に、仕様駆動開発は不要だと思っています。
理由は単純で、既存のコードベースにはすでに動く仕様書であるコードとテストが存在しているからです。コードとテストそのものが仕様にあたります。
たとえばAPIのレスポンスにフィールドを一つ追加してほしいという要件があったとして、わざわざ仕様書を書き起こしますか？ 既存のコードを読めば現在のレスポンス形式がわかる。テストコードを読めば期待される振る舞いがわかります。そこにフィールドを追加して、テストを直し、これで終わりです。
ここで仕様書を書くと何が起きるかというと、仕様書の更新忘れというリスクが新たに生まれます。改修のたびに仕様書を更新する運用は、長期的にはほぼ確実に破綻します。最初の3ヶ月はみんな真面目に更新する。半年経つと更新頻度が落ちる。1年後にはもう誰も見ていない。
AIエージェントを使った開発でも同じです。Claude CodeにCLAUDE.mdやコードベースを読ませれば、既存の設計方針を理解した上で改修してくれます。中途半端に古い仕様書を食わせるより、コードを直接読ませた方がよっぽど正確です。
仕様駆動開発というアプローチ自体が既存コードの改修と相性が悪い
そもそもの話をすると、仕様駆動開発というアプローチ自体が既存コードの改修と相性が悪いんです。 仕様駆動開発は、まず仕様を定義して、その仕様に沿ってコードを書くという順序で進みます。ゼロからものを作るときはこの順序が自然に成り立ちます。でも既存コードの改修では、すでに動いているシステムがあって、その一部を変えるという作業です。出発点がコードであって、仕様ではないのです。
既存のコードには、仕様書に書かれていない暗黙の振る舞いが山ほどあります。他のモジュールとの依存関係、過去のバグ修正で入った例外的な分岐、パフォーマンス上の理由で入れた回り道。こういうものは仕様書に書こうとしても書ききれないし、書いたところでコードを読んだ方が早いでしょう。仕様書を起点に改修しようとすると、こうした暗黙知を拾いきれずに既存の振る舞いを壊してしまうリスクがあります。
改修の起点はコードであるべきです。 今どう動いているかをコードから理解して、そこに変更を加えて、テストで壊れていないことを確認する。このサイクルの中に仕様書を挟む余地はないし、挟むと逆に危ない。コードという現実を見ずに仕様という理想から入ると、現実と理想のギャップがそのままバグになります。
じゃあドキュメントに何を書けばいいのか
仕様書は捨てろと言うと、じゃあ何もドキュメント書かなくていいのか？
そうではありません。
私が残す価値があると思っているのは三つです。
一つ目は、なぜそうしたかの記録です。コードには何をしているかは書いてありますが、なぜそうしたかは書いてありません。なぜMySQLではなくPostgreSQLを選んだのか。なぜここだけ非同期処理にしているのか、技術選定の理由や設計のトレードオフ、却下した代替案。これはコードから読み取れないのでADRやコミットメッセージに残す価値があります。
二つ目は、開発の手続きを定めたドキュメントです。しもしさんも言及されていた通り、CLAUDE.mdやskills、rulesのような開発プロセスを定義するものは必要です。テストはこう書く、ブランチはこう切る、PRのレビューはこうする。これらは仕様ではなく手続きであり、仕様書とは性質がまったく違います。
三つ目は、ビジネスの文脈です。この機能はどういうビジネス要件から生まれたのか。半年後にこの機能って何のためにあるんだっけとなったとき、コードだけでは答えが出ないことがある。ただしこれも、できればコード内のコメントやdocstringとしてコードと一体化させるのが理想です。
何を作ったかはコードに任せて、なぜそう作ったかとどう開発するかだけ人間が管理する。 この分担が今の開発スタイルとしてはちょうどいいバランスだと感じています。
AIエージェント時代の仕様書の在り方
Claude CodeのようなAIエージェントが開発の中心になりつつある今、仕様書の位置づけは確かに変わりました。モデルの能力は飛躍的に上がっています。AIはコードを直接読めるし、テストもgit logも読める。人間のために書かれた自然言語のドキュメントを、わざわざAI向けに用意し直す必要はありません。
ただし新規開発の初期段階、まだコードが一行もない状態ではAIもコードを読みようがない。この段階ではプロンプトとして仕様書を渡すことに意味があります。AIにこういうものを作ってくれと伝えるための仕様書。これはまさに使い捨てであり、AIがコードを生成した時点で役目を終えます。
仕様書は短期的に使い、実装後は破棄する。むしろAI時代だからこそ、この使い捨ての仕様書が大事になっていると思います。AIに的確な指示を出すには、自分の中で要件が整理されている必要がある。その整理のプロセスこそが仕様書を書くことであり、書いたものが使い捨てだとしても、考える行為そのものに価値があるのです。
まとめ
新規開発では仕様書を書きましょう。ただしチームで認識を揃えるため、AIに初期指示を与えるための一時的なもので、実装が終わったら捨てましょう。コードが仕様になるから消しても問題ありません。既存コードの改修では必ずしも仕様書は必要ありません。コードとテストが仕様であり、余計なドキュメントは負債にしかならないからです。
仕様駆動開発は不要か？と聞かれたら、答えはイエスです。
なぜなら、仕様駆動開発しようとするとコードと仕様書の二重管理の問題に苦しむことになるからです。
ただし、仕様書は必要です。
「Spec(仕様書)を固めてからコーディングに取り掛かる開発手法」という広い意味での仕様駆動開発は必要です。
不要なのは仕様書を永遠にメンテし続ける運用であって、仕様を考えることそのものは決して不要ではないです。仕様を考え、書き、共有し、実装し、そして捨てる。このサイクルが、AI時代における仕様との付き合い方だと思っています。
仕様書は書くこと自体に意味があるのではなく、考えることにより重要な意味があります。書いた結果のドキュメントは一時的な成果物にすぎません。書く過程で頭が整理されて、その思考がコードに結実したら、仕様書の役目は終わりです。
皆さんはどうでしょうか。仕様書、残してますか、捨ててますか。
追記
この記事自体がまさに「使い捨ての仕様書」と同じ構造をしていることに気づきました。頭の中にあったモヤモヤを言語化して、整理して、文章にした、その過程で自分の考えがはっきりした。もしかすると、公開した瞬間にこの文章の役目はもう終わっているのかもしれません。
半年後にこの記事を読み返したら、たぶん考えが変わっている部分もあると思います。AIの進化は速いし、開発の常識もどんどん塗り替わっていきます。そのとき私は、この記事をメンテするのではなく、また新しい記事を書くでしょう。古い記事を直し続けるより、そのときの考えをそのときの言葉で書いた方が価値があると考えています！
Discussion
実体験や考察の詰まった楽しい記事をありがとうございます！
この記事で言う「仕様」にはシステム仕様やソフトウェア仕様だけではなく、設計も含まれていますか？
「仕様を定義して、その仕様に沿ってコードを書く」
ソフトに対して、「こういう機能が欲しい」という要求があり、その実現方法を考えた結果として設計書を書き（ ここには、記事にあるように設計判断も残すと良いです）、その設計に従ってコード実装をしますね。
この流れに沿って開発することを仕様駆動開発と呼ぶと理解しました。この方法はウォーターフォール型でもアジャイル型でも、成立はすると思っています。
おっしゃるとおり、ドキュメントのメンテは大変です
コメントありがとうございます。励みになります。
はい、含まれます
開発をしている方の面白い記事で参考になりました。３点意見とコメントさせてください。
＞ AIに仕様書を渡して実装すると、確率的にどこかの時点でズレが発生するんですよ。(仕様書を100%反映して実装してくれるとは限らない)
しかもそのズレはコードが大規模になればなるほど、指数関数的にズレが大きくなります。
これはコードバグなので、PR で修正すべきという話だと思います。AI がコード書こうが人が書こうが。なので、仕様書からずれるからは、特に理由にはならないと思いますがいかがでしょうか。
＞そもそも実装の前に完璧な仕様書を用意すること自体がかなり難しい場合が多いです。
これはまさにその通りで、結果 PM や開発者が「勝手に予想して」実装することで齟齬が生まれ後から問題になる事があります。こちら気付いた内容について仕様を更新し、チームで同意することで対処するだけだと思いますがどうでしょうか。
＞既存のコードには、仕様書に書かれていない暗黙の振る舞いが山ほどあります。
これは事実で山のようにそういうプロジェクトはありますよね。AIがある今こそ仕様を再現できると思う反面、ご指摘の通りコードには反映できない根拠は書けないので、難しいですね。
コメントありがとうございます。
AI がコード書こうが人が書こうが、バグはバグなので修正すればよいというのはその通りです。
ただ大規模であるほど、仕様とコードの把握が難しくなっていき、ズレたときの検知が難しくなってくるのではないかなと思います。それも全部AIでやればいいじゃん、という意見もありそうですが。
気付いた内容について対処すればよいというのはその通りです。
仕様書を捨てたら仕様駆動開発と言えるのだろうか？
コードが仕様書に依存していないとそれはただのAI駆動開発やちょっと手の込んだPlanモードな気がする
元の記事も仕様書無しで新規開発という話では無さそうで、単に同じ事を詳細に述べているだけのような気がします。
コメントありがとうございます
仕様書を捨てたら仕様駆動開発ではないですね。
おっしゃる通り同じです。違うことを述べてるわけではないです。
記事で指摘されている「仕様をSingle Source of Truthとして維持するのは無理ゲー」という点はかなり本質的で、実務でも破綻しやすい部分だと思います。
特にAIを前提にした場合、仕様と実装のズレが確率的に発生するという指摘は納得感があります。
一方で、この議論は「仕様を常にコードと同期し続ける」という強い前提を置いた場合の話に見えました。
例えばOpenAPIやProtocol Buffersのように「仕様からコードを生成する」領域に限定すれば、仕様がSingle Source of Truthとして機能するケースも現実には存在します。
つまり問題は仕様駆動開発そのものというより、
の設計に依存していて、「すべての仕様をSSOTにする」前提がスケールしない、という整理の方が近いのではないでしょうか。
その意味で、仕様は合意形成と境界の定義に限定し、内部はコードとテストに寄せるというハイブリッドな運用が現実的に感じました。
コメントありがとうございます。
はい、まさにおっしゃる通りだと思います😀
面白い議論ですね
私の場合、バイブコーディングは一切行わない、SDDを実施しているので、仕様書はAIとの関係で契約書と見立てているので、コード修正は自ら実施しないで、仕様書更新でコードをFixさせていきます。
単体レベルでコードがFixすると、真実はコードに変化しますが、このタイミングDocStringsを再度付けなおして、コードから仕様書を自動作成で作り直しを行います。必ず仕様書の更新を義務ずけた運用を行っています。
この結果詳細設計書を、基本設計書や要件定義に逆流させて、仕様書を最新に維持します（この間に仕様バグが叩けます）。
そして結合試験や、受入試験で正しい試験ができる様になります。
コメントありがとうございます。
まさに理想的な仕様駆動開発を実践できていて凄いと思います
こんにちは。
私と全くの同意見で思わずコメントさせていただきました。
現在仕様駆動を取り入れていますが全く同じ課題感、全く同じ解決策に、帰着しました。
設計書には意図は残りにくいですが、コードのコメント、コミット履歴に細かく残せます。AI前提だとそれを簡単に辿り、設計書に復元できます。
人はドキュメントを読むよりAIに聞く方が楽なのでそういう面でもドキュメントを残さない方が自然に感じます。それに機能ごとに特化した設計書の方が見やすいです。
仕様とコードのずれについては確率的に発生するだけではなく、構造的にも発生するものだと感じます。モデルや画面のようなユースケースを横断的して使われるものは一方の機能改修をした際にもう一方が古いままになる問題があります。これを避けるにはコードで行われるように綺麗に依存関係を整理しなければいけませんが無理です。
とはいえ今までと全く違うアプローチなので実際にやってみると何か大きな問題が発生しそうとも思っています。