Spec-Driven Development詳解：「Prompt and Pray」から「Spec and Steer」へ

1. 問題の出発点

Coding agentの能力が高まるにつれて、一つのpatternが現れました。目標を説明すると大量のコードが返り、おおむね正しそうに見えるものの、完全には正しくありません。この「vibe coding」は、短時間のprototypeには優れていますが、重要で本格的なアプリケーションには信頼性が足りません。

9万人以上の開発者を対象にしたStack Overflowの2025年開発者調査では、66%が「ほぼ正しいが、完全には正しくない」ことをAIツールへの最大の不満として挙げ、45%がAI生成コードのdebugに多くの時間を使っていると回答しました。[1]

問題はAgentのコーディング能力ではなく、私たちが与える入力にあります。Coding agentを検索エンジンのように扱っていますが、実際には極めて字義どおりに動くpair programmerです。pattern matchingを得意とする一方で、明確かつ曖昧さのない指示を必要とします。

2. 中核的な定義

Spec-Driven Developmentでは、コードではなく仕様書、つまりspecをsource of truthとして扱います。AIは、自由度の高いpromptより、構造化されたタスクを実行するときにはるかに高い性能を発揮します。[2]

Spec-driven workflowでは、specが実装、テスト、タスク分解を駆動します。specを検証するまで、コードを書き始めません。[3]

一文で言えば、AIにいきなりコードを書かせず、最初にspecを書かせます。specに問題がないと確認してから、そのspecに従ってコードを書かせます。

3. Vibe Codingとの比較

具体例で違いを説明します。Vibe codingのpromptは「Build a rate limiter middleware for Express」です。Spec-firstのpromptは「Implement the rate limiter defined in .spec/features/rate-limiter.md, which specifies a sliding window algorithm, 100 requests per minute per API key, 429 responses with Retry-After headers, and Redis-backed state for horizontal scaling」です。後者では、Agentが即興で判断する余地がありません。自分が行うべき判断をAgentに代行させないようにします。[4]

重要な洞察は、二つの方法にかかる総時間は多くの場合ほぼ同じでも、時間を使う場所が異なることです。Vibe codingは生成後にコードを繰り返し修正することへ時間を使い、SDDは生成前にspecを書くことへ時間を使います。specは再利用でき、プロジェクトの提供後も文書として使えます。[4]

従来の開発では初期の判断に固定されますが、spec-drivenなら方向転換が容易です。specを更新し、planを再生成し、残りをAgentに処理させます。[5]

4. 四段階のWorkflow

GitHubのSpec KitとAddy Osmaniのガイドは、ほぼ同じ四段階のmodelを説明しています。

Phase 1：Specification（specを書く）

「Build a web app where users can track tasks, with user accounts, a database, and a simple UI」のような高レベルのpromptから始めます。Agentは、概要、feature list、技術スタックの提案、データモデルなどを含む構造化されたspec案を返します。このspecが、自分とAgentの両方が参照できるsource of truthになります。[3]

SpecはPRDでもSRSでもなく、両者を組み合わせたものです。PRDのように書くと、ユーザー中心のcontext、つまり各featureの背後にある「なぜ」を含められ、AIが誤った方向を最適化することを防げます。SRSのように詳しくすると、どのデータベースやAPIを使うかなど、AIが正しいコードを生成するために必要な具体的情報を固定できます。[3]

通常、specには目標と動機、user story、テスト可能なacceptance criteria、技術的制約、明示的なnon-goal、integration pointを含めます。

Phase 2：Plan（技術計画を書く）

Agentにrequirements.mdを読ませ、plan.mdを生成させます。これは要件を設計判断へ対応させる技術実装計画です。重要なのは、まだコードを書かせていないことです。[1]

Planは「どのように実装するか」へ答えます。ファイル構造、モジュール分割、API設計、データモデル、依存関係の選択を記述します。

Phase 3：Tasks（タスクを分解する）

Coding agentがspecとplanを実際の作業単位へ分解します。それぞれが具体的な下位問題を一つ解決する、小さくレビュー可能な塊です。AI agentへTDDを適用するように、各タスクを独立して実装、テストできるようにします。「build authentication」ではなく、「create a user registration endpoint that validates email format」のような具体的タスクにします。[3]

Phase 4：Implement（実装を実行する）

Agentはタスクを一つずつ、または並行して処理します。ただし、数千行のコードdumpをレビューするのではなく、特定の問題を解決する、焦点の絞られた変更をレビューします。Agentは何を作るかをspecificationから、どう作るかをplanから、今何をするかをtaskから理解します。[5]

各段階での役割は、指示だけでなく検証です。 specは本当に求めているものを捉えているか、planは現実の制約を考慮しているか、AIが見落としたedge caseはないかを確認します。

5. AI時代にSpec-Drivenが従来開発より重要な理由

従来の開発ではspecが不十分でも、人間の開発者が実装途中にdebugし、適応できます。認証serviceに別の方法が必要だと分かった場合や、packageのversionにbreaking changeがある場合も、柔軟に対応できます。

現在のAI agentには、このような適応的なdebugと調査能力が不足しています。specを字義どおりに実行するため、調査の不足が雪だるま式に実装失敗へつながります。[6]

もう一つ重要なのは、AI支援開発によって曖昧さの代価が大きく増えることです。AI Agentが参加すると、不明確な意図は進捗を遅らせるだけでなく、積極的にriskを作り出します。Specは有用な提案ではなく、制約条件になります。[7]

6. 「生きた文書」としてのSpec

Specを生きた文書にし、書いたまま忘れないようにします。Agentと判断を行ったときや新しい情報を発見したときに更新します。AIがデータモデルを変更しなければならない場合や、featureを削除すると決めた場合はspecへ反映し、常にground truthにします。version管理された文書として扱います。[3]

AI支援開発では、優れたversion管理習慣がさらに重要です。specファイルをrepoへcommitします。履歴を保存するだけでなく、AgentがGit diffやblameで変更を理解できるようになります。[3]

これはharnessの記事の中核的な主張と直接対応します。ファイルシステムはAgentの持続的な記憶層です。 Specは、その記憶層で最も重要なファイルの一つです。

7. 三つの成熟度level

2026年初頭のarXiv論文は、三つの異なるlevelを説明しています。[1] 業界の実践も、おおむねこの三層に分かれます。

Level 1：Spec-First（specを先に書き、手動で実行）。 AGENTS.mdで定義しているprocessです。要件を明確にし、specを書き、確認後に実装します。自動化ツールはなく、Agentの規律に依存します。2026年の多くのチームにとって、ここが出発点です。

Level 2：Spec-Validated（specの検証を自動化）。 自動drift検出を追加します。実装がspecからずれるとCIがfailします。GitHub Spec KitやAmazon Kiroのようなツールが、このlevelに属します。

Level 3：Spec-as-Code（spec自体がコード）。 より急進的な考え方です。保守が必要な唯一の成果物はspecであり、コードは自動生成される中間成果物とみなします。SQLがquery planを生成することや、Terraformがインフラを生成することに似ています。まだ実験段階です。

8. 現在のツール環境

2026年を代表するspec-driven開発ツールは二種類に分かれます。Agentが作業する間、文書とコードを同期し続けるliving-spec platformと、前半で要件を構造化するものの、実装がずれた場合は手動で調整するstatic-spec toolです。[8]

主なツール：

GitHub Spec Kit（open source、MIT）。Python CLIでspec-driven workflowのscaffoldingを提供し、72.7k starsを獲得し、22以上のAI Agent platformに対応しています。[9] Greenfieldプロジェクトに適しています。

Amazon Kiro。 EARS（Easy Approach to Requirements Syntax）を使ってspec-drivenを実装し、AWSエコシステムと深く統合します。

AGENTS.md / CLAUDE.md + 手動process。 現在行っている方法です。特定のツールへ依存せず、MarkdownファイルとAgentの行動規範でspec-first workflowを実現します。CursorやClaude Codeのように方法論に中立なツールを使う場合は、自分に合うworkflowを見つける必要があります。SDDの中核は、vibe codingを超え、設計段階と実装段階を分離することです。[10]

9. すでに持っている知識との関係

Harness Engineeringとの関係。 SpecはharnessのContext Injection層の一部であり、Agent contextへ注入する最も重要な構造化情報です。良いspecが、作業cycle全体でのAgentの振る舞いの品質を直接決めます。

Ralph Loopとの関係。 Ralph Loopの中核的な前提は、明確な「完了条件」（completion criteria）があることです。specにacceptance criteriaがなければ、Ralph Loopのverification stepはタスクが本当に完了したか判断できません。Ralphの記事で「良いAgentの結果は、モデルの賢さではなく、良いspecを書くことから生まれる」と述べているのは、この意味です。

AGENTS.mdとの関係。 追加したSpec-Driven Development sectionは、Level 1でSDDを実現しています。Agentの行動規範（AGENTS.md）+ specファイル（specs/FEATURE_NAME.md）+ acceptance criteria + 確認機構で、軽量ながら完全なspec-driven workflowを構成します。

10. 誠実なcaveat

経験豊富なプログラマーは、過度に形式化されたspecが不要な手間を生み、変更とフィードバックのcycleを遅らせると感じるかもしれません。初期のwaterfall開発で経験した問題と同じです。[10]

Martin Fowlerも、「neither Kiro nor spec-kit are suited for the majority of real-world coding problems」と指摘しています。[11]

SDDの主な問題はAIではなく、人にあります。SDDは開発者へ意図の正確な指定を求めますが、それこそ最大の課題です。10年以上のソフトウェア開発を見ても、実装前に要件が完全に明確だったプロジェクトはほとんどありません。[12]

これは現実のriskです。SDDは中程度以上の複雑さを持つfeatureに最も適しています。1行の修正、単純なrefactor、短時間のprototypeに完全なspec processを適用するのはoverengineeringです。いつspecが必要で、いつ直接実装すべきかを判断する直感自体が、エンジニアリング経験の一部です。

引用元

推奨資料

topic別に分け、入門から高度な内容の順に並べます。

入門：SDDとは何か、なぜ必要か

• https://developers.redhat.com/articles/2026/02/17/uncomfortable-truth-about-vibe-coding
• https://www.scalablepath.com/machine-learning/spec-driven-development-guide
• https://dev.to/bobbyblaine/spec-driven-development-write-the-spec-not-the-code-2p5o

中核的方法論：Specの書き方

• https://addyosmani.com/blog/good-spec/ （https://www.oreilly.com/radar/how-to-write-a-good-spec-for-ai-agents/ にも掲載）
• https://medium.com/@haberlah/how-to-write-prds-for-ai-coding-agents-d60d72efb797
• https://carlytaylor.substack.com/p/ai-spec-driven-development

ツールとFramework：SDDの実施方法

• https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• https://developer.microsoft.com/blog/spec-driven-development-spec-kit
• https://www.augmentcode.com/tools/best-spec-driven-development-tools
• https://pasqualepillitteri.it/en/news/158/framework-ai-spec-driven-development-guide-bmad-gsd-ralph-loop

業界分析と傾向

• https://thoughtworks.medium.com/spec-driven-development-d85995a81387
• https://medium.com/@visrow/spec-driven-development-is-eating-software-engineering-a-map-of-30-agentic-coding-frameworks-6ac0b5e2b484
• https://thenewstack.io/vibe-coding-spec-driven/
• https://www.javacodegeeks.com/2026/03/spec-driven-developmentwith-ai-coding-agents-the-workflow-replacingprompt-and-pray.html

Vibe Coding完全ガイド（SDDを重要な段階として扱うもの）

• https://www.gauraw.com/vibe-coding-complete-guide-2026/
• https://www.sitepoint.com/vibe-coding-2026-complete-guide/

推奨する読書順

時間が限られる場合は、次の順に読みます。

1. Red Hat: The uncomfortable truth about vibe coding——5分。問題意識を作る
2. Addy Osmani: How to Write a Good Spec for AI Agents——30分。中核的方法論。最も重要な記事
3. GitHub Blog: Spec-driven development with AI——15分。四段階workflowとSpec Kitを理解する
4. Drew Maring: How to Vibe Code like a Google Engineer——20分。完全な実践例を見る
5. ThoughtWorks: Spec-driven development——15分。業界の議論とSDDの境界を理解する

合計2時間未満で、理念から実践、議論までの全体像を把握できます。