Spec-Driven Development徹底ガイド：AI時代の開発手法

目次

• まずソフトウェアが何をすべきかを書き、その後にコードを書く
• なぜSDDが再び注目されているのか：AIがコードを書き、あなたは仕様を書く
• 1. Behavior-Driven Development（BDD）：実行できる仕様
• 2. Domain-Driven Design（DDD）：ビジネスモデルを仕様として使う
• 3. Model-Driven Engineering（MDE）とModel-Driven Architecture（MDA）：モデルから生成されたコードへ
• 4. API-FirstとContract-Driven Development（CDD）：契約がすべてを決める
• 比較：どのアプローチが自分に合うか
• AIとSDD：明日から使えるワークフロー

  • OpenSpecでの実践方法
• SDDを始めるときによくある失敗
• まとめ
• よくある質問
• 参考資料

まずソフトウェアが何をすべきかを書き、その後にコードを書く

きっと経験があるはずです。クライアントが「予約を管理するボット」を依頼し、チームは開発を始め、3週間後には「予約する」の意味について誰も合意できていない、という状況。キャンセルはできるのか？　希望の時間帯がすでに埋まっていたらどうなるのか？　コードは存在するのに、アイデアは一度も書かれていなかったのです。

Spec-Driven Development（SDD）、日本語では仕様駆動開発と呼ばれる手法は、まさにこの問題を解決します。ルールはシンプルです。仕様こそがプロジェクトの中心的な成果物であり、コード・テスト・ドキュメントはすべてそこから導かれます。ビジネスが変われば、まず仕様が変わり、コードはその後に続きます。

単一の手法ではありません。仕様やモデル、契約をソフトウェア開発ライフサイクル（SDLC）全体の中心に置く、一連のアプローチの総称です。この記事では、最もよく使われる4つの手法——BDD、DDD、MDE/MDA、API-First——を取り上げ、その比較と、コードの多くをAIが書くようになった今、どう実践するかを解説します。

なぜSDDが再び注目されているのか：AIがコードを書き、あなたは仕様を書く

「書く前に仕様を定める」という考え方自体は何十年も前からあります。新しいのは、誰がコードを書くかです。Copilot、Claude Code、CursorのようなAIエージェントの登場で、コードを生成することは安価になりました。コストがかかるのは、何を生成するべきかを知ることです。

AIエージェントに文脈もなく「ログイン機能を作って」と頼めば、得られるのはあるログイン機能であって、あなたのログイン機能ではありません。この直感頼みの開発スタイルには名前が付きました。vibe codingです。プロトタイプには有効ですが、実際のプロジェクトでは破綻します。

だからこそ、仕様をAIとの協働の中心に置くツールが登場しました。

• OpenSpec：私のおすすめ。軽量で、30以上のAIアシスタント（Claude Code、Cursor、Copilotなど）に対応し、ゼロから始めるプロジェクトだけでなく、既存プロジェクト向けに設計されています。
• Kiro：AWSのIDE。各機能をrequirements.md、design.md、tasks.mdの3ファイルに変換します。
• GitHub Spec Kit：フェーズごとにより厳格なプロセスを持つオープンソースのキット。GitHub Copilotを使っている場合に特に有用です。

仕様は、誰も読まないドキュメントからプロジェクトで最も重要なプロンプトへと変わりました。

1. Behavior-Driven Development（BDD）：実行できる仕様

BDDはTDDの考え方をビジネスの言語に持ち込みます。仕様とは、構造化された自然言語で書かれた振る舞いのシナリオです。ほとんどの場合、Gherkin形式（Given / When / Then）で記述します。

Feature: WhatsAppで予約を取る

  Scenario: 希望した時間帯がすでに埋まっている
    Given クリニックのボットにメッセージを送っているクライアントがいる
    And 火曜日の10:00にはすでに予約が入っている
    When クライアントが火曜日の10:00の予約を希望する
    Then ボットはその時間帯が利用できないと回答する
    And 最も近い空いている時間帯を3つ提案する

ライフサイクルとの関わり方は次のとおりです。

• 分析と設計： ビジネス側・開発側・QAが「Three Amigos」のミーティングで一緒にシナリオを書きます。
• 開発とテスト： 各シナリオは自動テスト（Cucumber、Behave、SpecFlow/Reqnroll）に接続され、機能を実装する前に失敗します。
• メンテナンス： .featureファイルはliving documentation（生きたドキュメント）です。記述が現実と合わなくなれば、テストが失敗します。

向いているのは、プロジェクト最大のリスクが「クライアントの要求の誤解」である場合です。

2. Domain-Driven Design（DDD）：ビジネスモデルを仕様として使う

DDDでは、仕様はリッチなドメインモデルとユビキタス言語です。クライアントとの打ち合わせでも、タスクボードでも、コードでも、同じ言葉が同じ意味で使われます。ビジネスが「予約」と言うなら、クラス名はReservationであり、BookingItemDTOではありません。

ライフサイクルとの関わり方は次のとおりです。

• 分析と戦略： Event Stormingのようなワークショップでビジネスイベントを洗い出し、Bounded Contexts（たとえばスケジュール、請求、通知）に分割し、コンテキストマップで結びます。
• アーキテクチャと実装： タクティカルデザイン（エンティティ、値オブジェクト、集約、ドメインイベント）がモデルを直接コードに変換します。
• 進化： ビジネスルールが変わったら、まずモデルを更新し、その後にアーキテクチャとコードを更新します。

ユビキタス言語がコードになった例：

// Bounded Context: スケジュール
class Reservation {
  reschedule(newSlot: TimeSlot) {
    if (this.status === "cancelled") throw new Error("キャンセルされた予約は再スケジュールできません");
    this.slot = newSlot;
    this.record(new ReservationRescheduled(this.id, newSlot));
  }
}

向いているのは、複雑さが技術ではなくビジネスルールにある場合です。

3. Model-Driven Engineering（MDE）とModel-Driven Architecture（MDA）：モデルから生成されたコードへ

ここでの仕様は形式的なモデルです。UMLダイアグラム、ドメイン固有言語（DSL）、その他のモデリング言語など。MDAはOMGが標準化した変種で、プラットフォーム非依存モデル（PIM）とプラットフォーム固有モデル（PSM）を分けます。

ライフサイクルとの関わり方は次のとおりです。

• 設計： 特定の言語やフレームワークに縛られない抽象的なモデルを構築します。
• 構築とデプロイ： 変換エンジンがモデルをソースコード、データベーススキーマ、インフラのスクリプト、テストに変換します。
• メンテナンス： 高レベルのモデルを変更して再生成することでシステムを更新します。生成されたコードを手で触ることはありません。

実は、思っている以上に使っています。データベースとクライアントを生成するschema.prismaや、インフラを定義するTerraformファイルは、この哲学の小さな例です。ローコードプラットフォームはこの考え方を極限まで押し進めています。

向いているのは、よく似たシステムが多い場合や、生成したほうが書くより良い、高度に規制されたドメインの場合です。注意したいのは硬直性です。変換ツールがついてこなければ、チームは生成コードを手で編集するはめになり、モデルは真実ではなくなります。

4. API-FirstとContract-Driven Development（CDD）：契約がすべてを決める

サービスアーキテクチャ、マイクロサービス、インテグレーションにおける、SDDの最も実践的な応用です。仕様はAPIの契約であり、実装前にオープンな標準で記述します。RESTにはOpenAPI（Swagger）、イベントにはAsyncAPI、gRPCにはProtobufです。

openapi: 3.1.0
info:
  title: 予約API
  version: 1.0.0
paths:
  /reservations:
    post:
      summary: 予約を作成する
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [clientId, timeSlot]
              properties:
                clientId: { type: string }
                timeSlot: { type: string, format: date-time }
      responses:
        "201": { description: 予約を作成しました }
        "409": { description: その時間帯はすでに埋まっています }

ライフサイクルとの関わり方は次のとおりです。

• 設計： APIを提供する側と利用する側の間で契約を合意します。
• 並行開発： 契約からモックサーバー、クライアントSDK、コードのスケルトンを生成できるため、フロントエンドとバックエンドが互いを待たずに同時に進められます。
• インテグレーションとデプロイ： 契約テスト（PactのようなツールによるConsumer-Driven Contracts）がCI/CDパイプラインで実行され、利用者を壊す変更をブロックします。

向いているのは、WhatsApp、CRM、決済ゲートウェイとの連携のように、複数のチームやシステムが同じAPIに依存している場合です。

比較：どのアプローチが自分に合うか

これらは互いに競合しません。リスクの種類が違い、うまく組み合わせられます。

手法	中心的な成果物	SDLCでの主な焦点	主に解決する問題
BDD	振る舞いのシナリオ（.feature）	ビジネス・開発・QAのアライメントと検証	「クライアントが求めていないものを作っていた」
DDD	ドメインモデルとユビキタス言語	アーキテクチャ、複雑さ、ビジネス	「ビジネスルールがコード中に散らばっている」
MDE / MDA	抽象モデル（UML、DSL）	自動生成と抽象化	「同じものを何度も手で書いている」
API-First / CDD	API契約（OpenAPI、AsyncAPI、Protobuf）	インテグレーション、マイクロサービス、並行開発	「デプロイのたびに連携が壊れる」

実際のプロジェクトでよくある組み合わせは、DDDでシステムをコンテキストに分割し、API-Firstでそのコンテキスト同士のやり取りを定義し、BDDで各機能をユーザーの視点から検証する、というものです。

AIとSDD：明日から使えるワークフロー

始めるのに4つの手法すべてを採用する必要はありません。このワークフローは、どんなAIエージェントでも、リポジトリ内の少数のMarkdownファイルがあれば機能します。後半ではOpenSpecでの自動化方法を紹介します。

1. 仕様を書く： spec.mdに、機能が何をすべきか、なぜ必要かを、受け入れ基準とともに書きます。BDDのシナリオやDDDのユビキタス言語がここで活きます。
2. 計画する： アーキテクチャ、スタック、契約（OpenAPIはここに置きます）を含むplan.mdをエージェントに作らせます。先に進む前に必ず自分でレビューします。
3. タスクに分解する： 計画を、小さく検証可能なステップに分割したtasks.mdにします。1コミットにつき1ステップです。
4. 実装する： エージェントは仕様と計画を常にコンテキストとして読みながら、1度に1つのタスクを実行します。
5. 検証する： タスクが完了したかどうかを判断するのは直感ではなく、仕様から導かれたテストです。

黄金律はこうです。要件が変わったら、仕様を編集し、変更を下流へ流す。コードだけを直接直すと、仕様は真実ではなくなり、vibe codingに逆戻りします。

OpenSpecでの実践方法

OpenSpecは、このワークフローを実践するためにおすすめするツールです。Spec Kitと比べて3つの実用的な利点があります。

• 儀式が少ない： 厳格なフェーズを強制されません。提案が明確になるまで反復できます。
• 既存プロジェクト向けの設計： 各変更は独自のフォルダに、現在のspecに対するデルタとして格納されます。始める前にシステム全体をドキュメント化する必要はありません。
• 特定のエージェントに縛られない： Claude Code、Cursor、Copilot、Amazon Qなど数十のツールで動作します。

インストールにはNode.js 20.19以上が必要です。

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

その後、AIエージェントからは3つのコマンドでサイクルを回せます。

1. /opsx:propose：提案、影響するspec、デザイン、タスクを含むフォルダをopenspec/changes/に作成します。先に進む前にレビューと調整を行います。
2. /opsx:apply：エージェントが仕様に従ってタスクを実装します。
3. /opsx:archive：完了した変更はアーカイブされ、そのspecはプロジェクトの真実の源であるopenspec/specs/に追加されます。

アイデアがまだ固まっていなければ、/opsx:exploreで提案を作る前に、エージェントと一緒に要件を考えることができます。コマンドの正確な構文は、使うアシスタントによって異なる場合があります。

SDDを始めるときによくある失敗

• 仕様を書きすぎる： 40ページのspecを誰も保守しません。1機能につき1ページから始めましょう。
• WhatではなくHowを仕様に書く： 「Redisを使う」は計画に書くことであり、仕様に書くことではありません。
• 検証されないspec： テストも契約も検証してくれないspecは、数週間で陳腐化します。
• コードだけ変えてspecを放置する： SDDを死んだドキュメントに変えてしまう失敗です。

まとめ

Spec-Driven Developmentは官僚主義ではありません。どうせ説明することになる内容を、先に書いておくだけです。BDD、DDD、MDE、API-Firstはそのための4つのやり方であり、それぞれに得意な成果物とリスクがあります。AIエージェントが書くコードが増えるほど、仕様は「本当に必要な結果を得るための最良のツール」になりました。

次のステップ： 次に着手する機能のspec.mdを、Given/When/Thenのシナリオ3つつきで書き、コードを1行も頼む前にAIエージェントに渡してみてください。うまくいったかどうか、コメントで教えてください。

よくある質問

SDDはTDDと同じですか？ いいえ。TDDは開発者が書くユニットテストから始まります。SDDはより高レベルな仕様から始まり、そこからテスト・コード・ドキュメントが生まれます。BDDはその両者を繋ぐ橋です。

小規模なチームや個人プロジェクトでも使えますか？ はい。spec.mdとtasks.mdがあれば、たとえ1人のチームでも、AIエージェントにはるかに集中して仕事をさせられます。

4つの手法をすべて使う必要がありますか？ いいえ。最大のリスクに応じて選びましょう。クライアントとの誤解（BDD）、複雑なビジネスルール（DDD）、繰り返しの多いコード（MDE）、壊れやすいインテグレーション（API-First）。

始めるのに必要なツールは何ですか？ エディタ、Markdown、そしてお気に入りのAIエージェントです。整った構造が欲しいならOpenSpecから始めましょう。コマンド1つでインストールでき、今使っているエージェントでそのまま動きます。

参考資料

• OpenSpec（リポジトリ）
• Kiro：Specsのドキュメント
• GitHub Spec Kit（リポジトリ）
• Pact：Consumer-Driven Contract Testing