spec-kitで始めるSpec-Driven Development完全ガイド｜AIエージェント時代の仕様駆動開発

はじめに：なぜ今「仕様駆動開発」なのか

Claude CodeやGitHub Copilot AgentをはじめとするAIエージェントが開発の現場に浸透するにつれ、ある共通の問題が浮上しています。「AIが生成したコードが、昨日の仕様と微妙にズレている」「指示を出し直すたびに過去の決定が上書きされる」——こうした経験を持つ開発者は少なくないはずです。

その根本原因は、仕様がコードベースのどこにも明示されていないことにあります。AIエージェントはコンテキストウィンドウの範囲でしか文脈を保持できません。仕様が人間の頭の中や散在したドキュメントにしか存在しない限り、AIは毎回「白紙から推測」するしかないのです。

Spec-Driven Development（SDD）と、そのツール実装である spec-kit は、この問題を根本から解決するアプローチです。本記事では、SDDの概念からspec-kitの実践的な使い方まで、段階的に理解を深めていきましょう。

第1章：Spec-Driven Development（SDD）とは何か

SDDの定義と基本概念

Spec-Driven Developmentとは、機械可読な仕様ファイル（Spec）を開発サイクルの起点に置く開発手法です。コードを書く前に仕様を定義し、その仕様からテスト・スタブ・ドキュメントを自動生成するというアプローチを取ります。

既存の手法と比較すると、その位置づけが明確になります。

これらは競合する概念ではなく、むしろ補完関係にあります。実際の開発現場では、SDDをベースに据えながら、TDDやBDDの実践を組み合わせるパターンが効果的です。

AIエージェント時代にSDDが重要な理由

AIエージェントが「仕様を理解した上でコードを書く」ためには、仕様が構造化されたデータとして存在していなければなりません。Markdownのドキュメントやコメントは人間が読むには優れていますが、AIがプログラム的に参照・検証するには不向きです。

SDDでは仕様を Single Source of Truth（唯一の真実の源泉） として扱います。仕様ファイルさえ正確であれば、AIエージェントはそこから実装の指針を得て、テストで仕様への適合を確認し、ドキュメントを最新に保つ——という一連の自律的なサイクルを回せるようになります。

第2章：spec-kit の概要と特徴

spec-kit とは何か

spec-kit は、Spec-Driven Developmentを実践するためのNode.js製ツールキットです。TypeScriptファーストの設計で、仕様ファイルの作成・検証・コード生成・AIエージェントとの連携までをカバーします。

解決しようとしている課題は明確です。

• 仕様がコード・ドキュメント・テストの間で分散・矛盾する「仕様の三重管理問題」
• AIエージェントがコンテキストを失い、過去の決定を破壊する「Spec Drift」
• 仕様変更が影響範囲に伝播せず、デグレが発生する「サイレント破壊」

対象ユーザーは、AIエージェントを積極的に活用するフロントエンド・バックエンド開発者、およびテックリードです。

spec-kit のコアコンセプト

spec-kitの中心には .spec.yaml（または .spec.ts）形式の Specファイル があります。このファイルには以下の情報を記述します。

# user-auth.spec.yaml
meta:
  id: user-auth
  version: 1.2.0
  status: stable

interface:
  input:
    email:
      type: string
      format: email
      required: true
    password:
      type: string
      minLength: 8
      required: true
  output:
    token:
      type: string
      format: jwt
    expiresAt:
      type: string
      format: iso8601

constraints:
  - "パスワードは平文で保存してはならない"
  - "トークンの有効期限は24時間とする"
  - "5回連続失敗でアカウントをロックする"

このSpecファイルが、コード生成・テスト・ドキュメント・AI連携の全ての起点となります。

類似ツールとの比較

よく混同されるツールとの住み分けを整理しておきます。

OpenAPI / AsyncAPIとの違い： OpenAPIはHTTP APIのインターフェース定義に特化していますが、spec-kitはAPIに限らずコンポーネント・ビジネスロジック・UIの振る舞いまで含む包括的な仕様管理を扱います。また、AIエージェントとのネイティブ統合がspec-kitの大きな差別化点です。

Storybook / Playwrightとの住み分け： StorybookはUIカタログ、PlaywrightはE2Eテストの実行ツールです。spec-kitはこれらの上流に位置し、仕様からStorybookのストーリーやPlaywrightのテストスクリプトを生成する役割を担います。

第3章：環境構築とセットアップ

前提条件

• Node.js 18.x 以上
• npm / yarn / pnpm（いずれか）
• TypeScript 5.0 以上（推奨）

エディタはVS Codeを推奨します。spec-kit公式のVS Code拡張機能を導入することで、Specファイルのスキーマ補完・バリデーションのリアルタイム表示が有効になります。

インストールと初期設定

# インストール
npm install -D spec-kit

# プロジェクト初期化
npx spec-kit init

initコマンドを実行すると、インタラクティブなウィザードが起動し、spec.config.ts が生成されます。

// spec.config.ts
import { defineConfig } from 'spec-kit';

export default defineConfig({
  specDir: './specs',           // Specファイルの格納ディレクトリ
  outputDir: './src/generated', // コード生成先
  aiContext: {
    claudeMd: './CLAUDE.md',    // Claude Code連携設定
    agentsMd: './AGENTS.md',    // 汎用AIエージェント設定
  },
  validation: {
    strict: true,               // 厳格な仕様検証
    breakingChangeDetect: true, // 破壊的変更の検出
  },
});

既存プロジェクトへの導入

既存プロジェクトへの導入はスモールスタートが鉄則です。ベストプラクティスとして、最も変更頻度が高いか、最もバグが多いモジュールから着手することを推奨します。

Phase 1（1週間）：最重要機能1つのSpecを書き、バリデーションを通す
Phase 2（1ヶ月）：CI/CDにSpec検証を組み込み、PR時に自動チェック
Phase 3（3ヶ月）：チーム全体のワークフローに組み込み、Spec-Firstを標準化

第4章：最初の Spec を書いてみる

ハンズオン：ユーザー認証機能を定義する

Step by Stepで実際の仕様を書いてみましょう。題材はシンプルなユーザー認証機能です。

Step 1: Specファイルを作成する

npx spec-kit create feature/user-auth
# → specs/feature/user-auth.spec.yaml が生成される

Step 2: インターフェースと制約を記述する

前述のYAML例をベースに、ビジネス制約を constraints セクションに自然言語で記述します。spec-kitの重要な設計思想として、制約は人間が読める形で書くことが挙げられます。これにより、AIエージェントが文脈を理解しやすくなります。

Step 3: バリデーションを実行する

npx spec-kit validate
# ✓ specs/feature/user-auth.spec.yaml — valid
# ✓ 2 specs validated, 0 errors

Step 4: コードを生成する

npx spec-kit generate
# → src/generated/user-auth.types.ts
# → src/generated/user-auth.schema.ts
# → src/generated/user-auth.test.ts（スケルトン）

生成されたテストスケルトンにはSpecの制約が自動的にテストケースとして展開されています。「5回連続失敗でロック」という制約は、対応するテストケースとして生成されるため、仕様とテストのズレが構造的に防止されます。

第5章：AIエージェントと spec-kit を連携させる

CLAUDE.md / AGENTS.md にSpecを組み込む

spec-kitの真価が発揮されるのは、AIエージェントとの連携です。spec.config.ts で設定した aiContext に基づき、spec-kitは自動的に CLAUDE.md や AGENTS.md を更新します。

npx spec-kit sync-ai-context
# → CLAUDE.md にアクティブなSpec一覧と要約を書き込み
# → AGENTS.md に制約・インターフェース情報を構造化して出力

これにより、Claude CodeなどのAIエージェントはセッションの開始時から現在の仕様を「知った状態」でスタートできます。

AIが仕様逸脱を自動検知するCI/CDパイプライン

GitHub Actionsを使ったSpec検証パイプラインの例を示します。

# .github/workflows/spec-check.yml
name: Spec Validation

on: [pull_request]

jobs:
  spec-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Validate Specs
        run: npx spec-kit validate --strict
      - name: Check Breaking Changes
        run: npx spec-kit diff --base origin/main --fail-on-breaking
      - name: Sync AI Context
        run: npx spec-kit sync-ai-context --check
        # → CLAUDE.md が古ければCIを失敗させる

このパイプラインにより、「Specを変更したのにAIコンテキストファイルを更新し忘れる」というヒューマンエラーが防止されます。

第9章：よくある課題とアンチパターン

Spec Drift：仕様の陳腐化問題

最も頻繁に起きる問題は、実装が進むにつれてSpecファイルが現実と乖離していく「Spec Drift」です。防止策は2つです。

1. CI/CDでSpec整合性チェックを必須にする：PRがSpec更新なしで実装変更を行った場合にCIを失敗させます。
2. spec-kit watchモードを活用する：npx spec-kit watch でSpecと実装の差分をリアルタイムで警告します。

過剰な仕様記述による開発速度低下

Specに何でも書こうとすると、仕様記述自体がボトルネックになります。「どこまで書くか」の判断基準はシンプルです。

• 書くべきもの：他のモジュール・AIエージェント・外部チームが参照するインターフェース、ビジネス上の制約
• 書かなくてよいもの：実装の詳細、変更頻度が極めて高い内部ロジック

AIへの過信と仕様検証の省略

AIエージェントが「Specに従って実装した」と言っても、必ず spec-kit validate での検証を挟んでください。AIは仕様を解釈して実装しますが、型の微妙なズレや制約の抜け漏れは自動生成物の検証でしか発見できません。

おわりに：仕様が資産になる時代へ

spec-kitとSpec-Driven Developmentは、AIエージェントを「便利な補助ツール」から「信頼できる開発パートナー」へと昇格させる鍵です。仕様が機械可読なファイルとして存在することで、AIはコンテキストを失わず、チームは「AIに壊された」という体験から解放されます。

1週間のロードマップとして、まず最重要モジュール1つのSpecを書き、CIに組み込むことを目標にしてください。仕様を書く習慣が根付いた段階で、AIエージェントとの連携設定（CLAUDE.md統合）へとステップアップすれば、スムーズに導入できます。

仕様は消費されるドキュメントではなく、プロジェクトの資産です。spec-kitを使ってその資産を積み上げていくことが、AIエージェント時代の競争優位につながります。

付録：spec-kit CLI コマンドリファレンス