AIで進める仕様駆動開発:コードの前にプランを書く(2026年版)

仕様駆動開発とは?

仕様駆動開発とは、仕様(spec)を唯一の信頼できる情報源として扱う手法です。最初の1行のコードを書く前に「何を、なぜ作るのか、そして完成とはどういう状態か」を書き出し、そのうえでAIエージェントにその仕様に従ったコード・テスト・ドキュメントを生成させます。ひとことで言えば、AIがあなたの意図を推測するのではなく、仕様がAIを動かすということです。

核心はあの言葉、「唯一の信頼できる情報源」です。従来のやり方では、要件はあなたの頭の中、いくつかのチャットメッセージ、そして薄いチケットにばらばらに散らばっています。AIはそのごく一部しか読めないので、残りを推論するしかありません。そして推論こそがバグの生まれる場所です。SDDは、人間もエージェントも読める1つのドキュメントに、重要な制約をすべて集めることを強制します。目的、スコープ、受け入れ基準、そしてあえてやらないことにした事柄(非目標)まで含めてです。

これはウォーターフォールの「コードを書く前に巨大なドキュメントを書く」への逆戻りではありません。SDDにおける仕様は短く、生きていて、たいてい画面1〜2枚分の長さしかありません。それはコードの前のコンテキストです。賢いエージェントが一発で正しく仕上げるのにちょうど十分なだけのコンテキストであり、あなたが後から3〜4回も手作業で直す代わりになります。Thoughtworks はこれを、AIによるソフトウェアの書かれ方を作り変えつつあるパターンだと述べています(Thoughtworks, 2025)。

なぜ先にプランを書くほうが「バイブだけ」に勝るのか?

「バイブだけ」の中心的な問題に、覚えやすい名前を付けましょう。「あいまいさ税(ambiguity tax)」です。要件がまだぼんやりしている箇所すべてで、AIは空白を埋めることを強いられます。AIはそれを、あなたの実際の意図ではなく、学習データから導いた平均的な推測で埋めます。あなたはその税金を手戻りループという形で払い戻すことになります。「いや、そういう意味じゃない」「このケースが抜けている」「なぜ関係ないファイルまで丸ごと書き換えたの?」というふうにです。

AIに任せて主導させるハンズオフなスタイルが初めてなら、まず文脈としてvibe coding とは何かを読んでください。SDDは vibe coding を否定するものではなく、その上に規律を乗せるステップです。「バイブだけ」は素早い探索には最高です。しかしタスクに明確な要件がある瞬間、それは3つのリスクをさらけ出します。

• 要件ドリフト: AIは動くけれど必要だったものではないものを出してしまう。エッジケースの抜け、ビジネスロジックの誤読、あなたの規約を壊す命名やインターフェースなどです。
• アーキテクチャドリフト: すべてのプロンプトが場当たり的な設計判断になります。10回もプロンプトを重ねれば、コードベースは誰も意図して設計していないつぎはぎになります。
• 膨れ上がるトークンコスト: 「もう一度これを直して」というループのたびに、エージェントはコンテキストを読み直してコードを再生成します。3〜4回の手戻りは、最初に良い仕様を1つ書くよりも何倍ものトークンを消費します。

仕様駆動は順序を逆にします。まだ安いうちに、先頭で「考えるコスト」を一度だけ払うのです。受け入れ基準を書くことは、AIが本来なら推測するしかない問いにあなた自身が答えることを強制します。いったんコンテキストが明確になれば、エージェントには間違って推測する余地がほとんど残りません。だからこそ、成熟したvibe coding ワークフローには、ノンストップでプロンプトを投げ続ける代わりに、必ず途中にプランを書くステップが織り込まれているのです。

spec・plan・task ― 何が違うのか?

この3つの言葉はよく混同されますが、その間にきれいな線を引くことがSDDの鍵です。ひとことで言えば、spec は「何を・なぜ」に、plan は「どうやって、どの順で」に、task は実行の最小単位に答えます。

よくある取り違え:「どうやって」を spec に詰め込む(仕様が早すぎる段階で細かく管理されすぎ、柔軟性を失う)か、受け入れ基準を飛ばした plan を書く(エージェントはいつ完了と呼んでよいのか分からない)。線引きを保つコツ:答えが「ユーザーやシステムが必要とすること」についてなら spec に、「何をタイプするか、どのファイルを最初に編集するか」についてなら plan に属します。

本物の例:コードの前の spec + plan

理屈はもう十分です。ここに、これを説明するのに私がよく使う小さな機能の本物の成果物があります。ログインエンドポイントへのレート制限の追加です。この2つのファイルをコピーし、あなたのプロジェクト向けに数行だけ調整すれば、準備完了です。まずspec.mdです。これは「何を・なぜ」だけを述べ、どうやってかは決して述べません。

# spec.md - Rate limit for the login API

## Goal
Block brute-force against POST /api/login by limiting the number of
attempts per IP + email, returning a clear error when the limit is passed.

## Why
Login currently has no limit -> passwords are easy to guess and the DB
can be overloaded.

## Acceptance criteria
- Max 5 failed attempts / 15 minutes per (IP, email) pair.
- Over the limit -> HTTP 429 + body { error: "too_many_attempts", retry_after }.
- A SUCCESSFUL login resets the counter for that (IP, email) pair.
- Automated tests for: under the limit, at the limit, over the limit, and reset.

## Non-goals
- NO CAPTCHA (deferred to a later phase).
- NO rate-limiting other endpoints this time.

## Edge cases
- Many users behind the same NAT/IP -> key on (IP, email), not IP alone.
- Clock/timezone: use UTC for the time window.

次はplan.mdです。今、そして今こそ、「どうやって、どの順で」を述べます。触るファイルの列とロールバックのセクションに注目してください。

# plan.md - Implementing login rate limit

## Steps (in order)
1. Add an attempt-counter store (Redis, key = login:{ip}:{email}, TTL 15m).
 -> File: src/lib/rate-limit.ts (new)
2. Write a checkLoginRateLimit middleware that reads/increments the counter.
 -> File: src/middleware/login-rate-limit.ts (new)
3. Attach the middleware to POST /api/login BEFORE the auth handler.
 -> File: src/routes/auth.ts (edit)
4. On successful login -> delete the counter key for that (IP, email).
 -> File: src/routes/auth.ts (edit)
5. Write tests for the 4 cases in the acceptance criteria.
 -> File: tests/login-rate-limit.test.ts (new)

## How to test
- npm test tests/login-rate-limit.test.ts
- Manual: send 6 wrong requests in a row -> the 6th must return 429.

## Risk & rollback
- Redis down -> fail-open (let it through) or fail-closed? Choose fail-open +
 log a warning, so infra failures do not lock out every user.
- Rollback: removing the middleware in step 3 returns the system to its
 original state.

このプランに沿ってAIを走らせると何が起きるか: エージェントは正しい順序で作業し、すべてのファイルを作成し、そして受け入れ基準が「完了」の意味を明示しているので、正しいところで止まります。認証モジュール全体を気軽にリファクタリングしたり、カウンターのリセットケースを忘れたりすることはもうありません。同じエージェント、同じタスク――違いは地図を持っているかどうかだけです。

AIによる仕様駆動ワークフロー(6ステップ)

これは私がほぼすべての中〜大規模の機能で使うループです。brainstorm -> plan -> cook -> ship ワークフローにほぼ一対一で対応します。

1. アイデアとコンテキスト: 解くべき問題と本当の制約(スタック、規約、触ってはいけないもの)を述べます。ここがプロジェクトの「真実」を集める場所です。
2. 仕様を書く: 目的/非目標/受け入れ基準/エッジケースを埋めます。受け入れ基準では具体的であることを自分に強制してください。あいまいなところはどこでもAIが推測します。
3. 仕様をレビューする(人間+AI): 1行のコードも存在しないうちに、エージェントに仕様を読ませ、矛盾・抜けているケース・実現不可能な要件を指摘させます。
4. プランを書いてタスクに分割する: 仕様を、触るファイル・テスト方法・ロールバックを名指しした順序立てた手順に変えます。各タスクが1回で検証できるようになるまで薄く刻みます。
5. エージェントにタスクごとにコードを書かせる: 一度に1タスクずつ走らせ、先回りさせません。各タスクの後、エージェントに自分の仕事をプランと照合させます。
6. 受け入れ基準に対して検証する: テストを走らせ、基準を1行ずつ追います。すべての基準が緑になったときだけ機能は完了です――「動いているように見える」ときではありません。

肝心なのは、ステップ3と6こそSDDが最も助けてくれるところだということです。仕様段階でバグを捕まえるのは、コードで捕まえるより何十倍も安上がりです。

Claude Code の中で仕様駆動を正しくやる

始めるのに特別なツールは要りません。Claude Code にはすでに、身軽なSDDループを立ち上げるのに十分な3つのものが備わっています。

• Plan Mode: Claude Code はプランを下書きし、どのファイルに触れる前にもあなたに承認させます――まさに「まず計画、コードは後」の精神です(Anthropic docs, 2026)。最大限に活かす方法はClaude Code で計画を立てる(Plan Mode)を参照してください。
• 常設のガードレールとしての CLAUDE.md: 長く使う規約・境界・非目標をこのファイルに入れておけば、エージェントは常にそれを読みます――繰り返される制約を、リポジトリの固定された「真実」に変えるのです。これは最もシンプルな形のcontext engineeringです。
• GitHub Spec Kit: SDDを明示的なワークフロー /specify -> /plan -> /tasks に変えるオープンソースのコマンド群で、Claude Code をはじめ多くのエージェントで使えます(GitHub Blog, 2025)。

作り込み済みの仕様駆動ワークフローが欲しいですか? CLAUDE.md + Plan Mode + Spec Kit を自分で手配線したくないなら、Claude Code 向けのAgentKit バンドル ― 現在 $149(定価 $198)は、同じ spec -> plan -> code -> verify の流れに従う brainstorm/plan/cook/ship のスキルとレビュー用サブエージェントをまとめています。AgentKit とは何かに詳しくまとめてあります――自分で判断するために読んでください。購入を急ぐ必要はありません。

2026年の仕様駆動ツール

軽量なものからフルパッケージまで、人気の選択肢をいくつか。

唯一「正しい」ツールというものはありません。ほとんどの機能には素のMarkdown+Plan Modeで十分です。重量級のキットが報われるのは、SDDを頻繁に行い、それをチーム全体で標準化したいときだけです。

仕様駆動が要らないのはいつか?

SDDはツールであって宗教ではありません。何にでも仕様を強制すると裏目に出ます。次のときはSDDを飛ばしましょう。

• 使い捨てのスクリプトや捨てるためのタスク――仕様を書くほうが、ただやってしまうより時間がかかります。
• 探索的なプロトタイプ/スパイク: 目的は速く学ぶことで、まだ正しく仕上げることではありません。この段階では「バイブだけ」のほうが合います。
• 原因がすでに分かっている1行のバグ修正――1文字を変えるのに受け入れ基準は要りません。
• 1時間ごとに変わる要件: 仕様は、書くそばから古くなっていきます。

SDDが合う場合でも警戒すべき罠が2つ:過剰仕様(over-spec)(詳細すぎる仕様を書いて硬直させ、柔軟性を殺す)と仕様の腐敗(spec rot)(コードが変わっても仕様が更新されず、嘘をつくドキュメントになる)です。良い仕様とは、エージェントが正しく仕上げるのにちょうど十分で、なお変更しやすいもの――いちばん長いものではありません。

よくある質問(FAQ)

仕様駆動開発は vibe coding とどう違うのですか?

vibe coding はプロンプトを投げてAIに主導させるやり方で、素早い探索に向いています。仕様駆動は、どんなコードよりも先に、受け入れ基準付きの仕様を信頼できる情報源として据えるやり方で、要件が明確な機能に向いています。SDDは vibe coding を否定するのではなく、それに規律を加えるステップです。

spec は plan とは違うのですか?

はい。spec は「何を・なぜ」(目的、スコープ、受け入れ基準、非目標)に答えます。plan は「どうやって、どの順で」(手順、触るファイル、テスト方法、ロールバック)に答えます。spec のほうが安定していて、plan はやり方が変われば変わります。

専用のツールが必要ですか、それとも Markdown で十分ですか?

始めるには素のMarkdownで十分です――spec.mdとplan.mdがあればいいのです。GitHub Spec Kit や Kiro のようなツールは、SDDを定期的に、あるいはチーム全体で行うようになって初めて、プロセスの標準化に役立ちます。

仕様駆動は開発を遅くしますか?

最初は遅く、全体では速くなります。仕様を書くのに数分よけいに使いますが、AIが逸れていたはずの手戻りループを大きく減らせます。小さな/使い捨てのタスクには本当に見合いません――そのときはバイブで行きましょう。

仕様駆動を Cursor や Copilot で使えますか?

はい。SDDは手法であって、1つのツールに縛られません。spec.md/plan.md をリポジトリに置き、どのエージェント(Claude Code、Cursor、Copilot)にもそれらに従わせられます。GitHub Spec Kit はそもそもマルチエージェントで使えるように設計されています。

仕様はどのくらいの長さであるべきですか?

エージェントが重要なことを何も推測しなくてよい程度の長さ、たいていは画面1〜2枚分です。仕様がそれの生むコードより長いなら、過剰仕様です。本当の試金石は、明確な受け入れ基準と明確な非目標があることです。

まとめと次のステップ

原則は短くまとめられます。まず仕様、コードは後。考えるコストを、いちばん安い先頭で一度だけ払う――そうすればAIは、高くつく手戻りループであいまいさ税を返してこなくなります。次は、SDDが完全な作業ループのどこに位置するかを見るためにbrainstorm -> plan -> cook -> ship ワークフローを、そしてすぐ手を動かすためにClaude Code で計画を立てる(Plan Mode)を読んでください。