「AIにコードを書かせるな、仕様書を書かせろ」──Vibe Codingの二日酔いから始まる仕様駆動開発（SDD）
はじめに
「思いついたアイデアをプロンプトに投げたら、一瞬でアプリが動いた」
元OpenAIのAndrej Karpathy氏が提唱した「Vibe Coding」という言葉は、世界中のエンジニアを熱狂させました。エディタを開き、自然言語でやりたいことを呟くだけで、AIが数百行のコードを一気に書き上げる光景は、まさに新しい時代の到来を予感させるものでした。
しかし、その熱狂の裏で、多くの現場が深刻な「二日酔い」に直面しています。
数千行から数万行に及ぶ既存プロダクトのコードベースにAIコーディングツールを投入した途端、不整合な抽象化、重複したロジック、型定義の破壊といった問題が噴出し始めました。生成されたコードのPR（プルリクエスト）は数千行の巨大な差分となり、人間が到底レビューしきれないまま放置され、マージ率が低下するという現象が海外のテックコミュニティでも大きな議論を呼んでいます。
いま英語圏のエンジニアたちが辿り着きつつある答えは、非常に逆説的です。
「AIにいきなりコードを書かせてはならない。まずAIに仕様書を書かせよ。」
本記事では、Vibe Codingの限界を乗り越える新しい開発パラダイムである「仕様駆動開発（Specification-Driven Development: SDD）」の考え方と、明日から使える具体的な実践プロセスを解説します。
Vibe Codingの限界と「AI技術的負債」の正体
Vibe Codingが新規のプロトタイプ作成において圧倒的な威力を発揮するのは事実です。ゼロから使い捨てのスクリプトを作ったり、小規模なデモ画面を組んだりする場面では、厳密な設計を省いて動くものを最速で手に入れる価値があります。
一方で、持続的な保守やチーム開発が求められる本番システムにVibe Codingを持ち込むと、次の3つの壁に激突します。
1. レビュー不可能な巨大PR（プルリクエスト）
AIに「〜の機能を実装して」と大雑把に頼むと、AIは複数のファイルを跨いで一気にコードを生成します。
その結果として上がってくるPRは、数百行から数千行におよびます。レビューする人間は、AIが意図通りに実装したのか、エッジケースを考慮しているのか、既存の共通モジュールを無視して勝手な車輪の再発明をしていないかを一行ずつ確認しなければなりません。コードを書く時間はゼロになっても、レビューと手戻りのコストが倍増し、チーム全体のベロシティはむしろ落ちてしまいます。
2. コンテキストドリフトによるアーキテクチャの侵食
LLMは「局所的な整合性」を取るのが得意な反面、「リポジトリ全体の長期的な設計意図」を記憶し続けるのが苦手です。
プロンプトの対話を重ねるうちに、モデルは過去に決めた設計方針を少しずつ忘れていきます（コンテキストドリフト）。その結果、同じようなユーティリティ関数が別のディレクトリに再定義されたり、レイヤードアーキテクチャの依存関係が平気で逆転したりします。
3. 仕様の不在によるリグレッションの温床
Vibe Codingで作られたコードには、「なぜこのコードがこう書かれているのか」という意図（仕様）がドキュメントとして残りません。
後から別のエンジニアやAIが機能修正を試みた際、どの振る舞いが意図された仕様で、どの振る舞いが単なるバグなのかを判別できなくなります。結果として、少しの機能追加で既存機能が壊れる脆いシステムが完成してしまいます。
パラダイムシフト：仕様駆動開発（SDD）とは何か
こうした課題への反動として注目を集めているのが、仕様駆動開発（Specification-Driven Development: SDD）です。
SDDの核心は、人間のエンジニアの役割を「コードの執筆者」から「仕様とアーキテクチャの意思決定者・監査役」へ意図的にシフトさせる点にあります。人間が自然言語でAIに命令して直接コードを書かせるのではなく、人間とAIが協調して「仕様書（Markdown）」という明確な契約を先に策定します。
【従来のVibe Coding】
人間 ──(大雑把なプロンプト)──> AI ──(いきなり実装)──> 巨大な未検証コード
【仕様駆動開発（SDD）】
人間 ──(対話・壁打ち)──> AI ──(生成)──> 仕様書・テスト設計（人間がレビュー）
↓ 承認
AIがコード実装
人間がレビューすべき対象は、AIが吐き出した何千行ものプログラミング言語のコードではなく、日本語やMarkdownで書かれた「仕様書（PRD / ADR）」と「テストケース」です。
仕様とインターフェースが固まった段階で初めて、実装フェーズをAIに委託します。AIは明確な境界条件とテストがある環境下では、驚異的な精度とスピードで高品質なコードを出力します。
SDDを実践する3つのステップ
実際に既存のリポジトリや新機能開発において、SDDを回すための具体的なワークフローを3つのステップで紹介します。
ステップ1：AIと壁打ちして要件仕様書（PRD）を起こす
いきなり「コードを書いて」と命じるのではなく、まずは解決したい課題や目的をAIに伝え、要件仕様書をMarkdownファイルとしてまとめさせます。
AIに対して、次のように問いかけます。
以下の課題を解決する新機能の要件定義書（PRD）を作成してください。
まだコードは書かないでください。
# 解決したい課題
ユーザーが決済時にクーポンコードを誤入力した際、エラー理由が分からず離脱している。
# 出力項目
- 機能の目的と対象スコープ
- 満たすべき受入基準（Acceptance Criteria）
- 考慮すべきエッジケースと例外条件
この段階で人間が仕様をレビューします。「この受入基準は業務仕様と合っているか」「想定外のエッジケースが抜けていないか」を確認し、ドキュメントの差分だけを修正します。自然言語の仕様書であれば、コードレビューよりも何倍も高速かつ的確にレビューが完了します。
ステップ2：設計決定（ADR）とテスト仕様を固める
要件が定まったら、次に技術的なアプローチと契約（インターフェース・テスト仕様）をAIに整理させます。
このステップで重要なのは、アーキテクチャの選択理由（ADR: Architecture Decision Record）と、入出力の型定義、およびテストケースを先に確定させることです。
承認された要件仕様書に基づき、設計方針とテスト計画を作成してください。
実装コードはまだ不要です。
# 出力項目
- 変更が必要なモジュールとデータフローの概要
- インターフェース定義（TypeScriptの型またはAPIスキーマ）
- 単体テストおよび結合テストで検証すべきテストケース一覧
ここで人間は、既存のアーキテクチャ方針と整合しているか、命名規則やセキュリティ要件が満たされているかを確認します。テストケースが網羅されていれば、このあとの実装における品質の命綱が確保されたことになります。
ステップ3：テスト駆動開発（TDD）のループをAIに回させる
仕様書とテスト仕様が承認されたら、Claude Code、Cursor、Aiderといったコーディングエージェントに実装を委託します。ここで重要なのは、AIにいきなり実装コードを書かせるのではなく、テスト駆動開発（TDD: Red-Green-Refactor）の原則を適用することです。
エージェントには作成した仕様書へのパスと、テスト実行コマンドを与えます。
docs/specs/coupon-validation.md の仕様に従い実装してください。
1. 承認されたテスト仕様に基づき、まず失敗するテストコードを作成する
2. テストがすべて成功するまで実装コードを作成・修正する
3. 既存の全テストを実行し、リグレッションがないことを確認する
自然言語の仕様書にはどうしても微小な解釈の余地が残りますが、テストコードという「決定論的な制約」に変換することで、仕様のブレ（Specification Drift）を完全に排除できます。エージェントはテストの失敗ログを自己検証のフィードバックとして活用し、テストが通るまで自律的に試行錯誤します。
完成したコードは、作成した仕様書（docs/specs/）と一緒に同一のPRとして提出させます。Gitの履歴に「仕様と実装」が常にセットで記録されるため、後から参入したメンバーや別のAIにとっても最高のコンテキスト資料になります。
現場で破綻させないための2つの運用プラクティス
SDDを実際のチーム開発で継続運用するためには、さらに次の2つの工夫が不可欠です。
プラクティス1：リポジトリのルール設定で「仕様先行」を強制する
エージェントに対して毎回手動で「仕様書を先に書け」と指示するのは手間がかかり、抜け漏れも生じます。
そこで、Cursorの .cursorrules やClaude Codeの CLAUDE.md、Copilotの .github/copilot-instructions.md といった常時読み込みファイルに、次のようなガードレールを明記します。
# 開発ワークフローの基本原則
- 新機能や大規模なリファクタリングを行う際は、実装前に必ず docs/specs/ に仕様書を作成すること
- 人間の承認を得る前に実装コードを変更してはならない
- 実装時はテストコードを先行して作成し、全テスト通過を確認してから完了とすること
この一行を入れておくだけで、エージェントが勝手にコードの書き換えを暴走させる事故を防ぎ、開発プロセス全体を仕様駆動へと自動的に誘導できます。
プラクティス2：1機能1ファイルの「マイクロスペック（Micro-Specs）」に分割する
仕様書を作成する際、1つの巨大なファイルにすべての要件を詰め込んではなりません。仕様書自体が肥大化すると、エージェントのコンテキストウィンドウを過剰に消費し、かえって推論精度が落ちる原因になります。
推奨されるのは、1つの機能追加や修正ごとに100〜200行程度の小さなMarkdownファイル（docs/specs/2026-10-coupon-validation.md など）を作成する「マイクロスペック」の運用です。役目を終えた仕様書はアーカイブするか、PRマージ時にシステム全体の仕様集へ集約することで、常に軽量なコンテキストを保ち続けられます。
SDDを導入して得られる3つのメリット
このワークフローを導入することで、開発現場には次のような劇的な変化が訪れます。
1. PRレビューの劇的な軽量化
これまでのレビューは、「このコードは何をしているのか」「バグはないか」を暗中模索で探す作業でした。
SDDでは、事前に人間が合意した仕様書とテストケースが存在するため、レビュアーは「コードが事前に合意した仕様通りに書かれているか」「テストが網羅されているか」を確認するだけで済みます。レビューの心理的負担と時間が激減し、マージまでのリードタイムが短縮されます。
2. 「仕様と実装の乖離」の自然な解消
従来の開発では、「ドキュメントを書くのが面倒でコードだけ先行し、仕様書が形骸化する」という問題が常にありました。
SDDでは、コードを生成するための入力として仕様書が必要になるため、ドキュメントが最新の動く仕様として生き続けます。ドキュメントを書く主体もAIであり、人間はその編集と承認を行うだけなので、ドキュメント作成の心理的ハードルも大幅に下がります。
3. AIエージェントの自律稼働と精度の向上
AIコーディングエージェントが迷走したり、余計なコードを改ざんしたりする最大の原因は、「曖昧なプロンプトによる解釈のブレ」です。
仕様書によって明確なガードレールとゴールが定義されているため、エージェントは迷うことなく正確な実装に集中できます。結果として、プロンプトの往復回数や無駄なトークン消費も最小限に抑えられます。
まとめ
Vibe Codingは、個人開発やアイデア検証のスピードを劇的に変えました。その直感的な体験は素晴らしいものです。
しかし、ソフトウェア開発の本質は「コードを生成すること」ではなく、「システムの長期的な整合性を保ち、価値を届けること」にあります。コードを量産することが容易になった時代だからこそ、そのコードが何を目的としており、どんな制約のもとで動くべきかという「仕様」の価値がかつてないほど高まっています。
AIコーディングエージェントの真の力は、適当なプロンプトでコードを乱造させることではなく、人間の思考を整理し、堅牢な仕様を構築するための相棒として使うことで発揮されます。
「AIにコードを書かせる前に、まず仕様書を書かせる」
このシンプルな習慣を取り入れるだけで、あなたのAI開発体験は、不安定なガチャから再現性の高いエンジニアリングへと進化するはずです。