仕様書駆動開発のすすめ — AIに完璧な指示書を渡す方法

なぜ仕様書が重要か

バイブコーディングの初心者が最初に気づくことの一つが、「いきなりコーディングを依頼すると、意図と違うものができる」ことです。

その解決策が 仕様書駆動開発（Specification-Driven Development） です。

仕様書の種類

レベル1: 最小仕様（小さなタスク向け）

## 機能: ダークモード切り替え
- トグルボタンをヘッダー右端に配置
- localStorage に保存（キー: 'theme'）
- 値: 'dark' | 'light'（デフォルト: 'dark'）
- 切り替え時に html[data-theme] 属性を変更

レベル2: 機能仕様書（中規模の機能向け）

## 機能: 検索フィルタ

### 概要
プロンプト一覧ページにリアルタイム検索機能を追加する

### 入力
- テキスト入力: タイトル・説明・タグ・プロンプト本文を対象
- カテゴリフィルタ: チェックボックス（複数選択可）
- 難易度フィルタ: ラジオボタン（単一選択）

### 処理
- debounce 300ms でリアルタイム絞り込み
- URLパラメータと同期（?q=xxx&cat=setup）
- ブラウザバックで状態を復元

### 出力
- フィルタ後のプロンプトカード一覧
- 「○件見つかりました」のカウント表示
- 0件時: 「条件に合うプロンプトが見つかりません」

### 制約
- クライアントサイドのみ（SSG のため）
- 全データを JSON で事前埋め込み

レベル3: プロジェクト全体仕様書（新規プロジェクト向け）

メタプロンプトを使って自動生成します。

→ メタプロンプト（仕様書自動生成）

仕様書を書く順序

1. 「何を作るか」を決める（What）

ユーザーが〇〇できる機能

2. 「誰が使うか」を決める（Who）

- 初心者ユーザーが直感的に使える
- モバイルからも操作できる

3. 「どう見えるか」を決める（UI）

アスキーアートでも良いので、レイアウトを描きます:

┌─────────────────────┐
│  [🔍 検索バー]       │
├────────┬────────────┤
│ フィルタ│  カード × n │
│ □ 初級 │  [カード]   │
│ □ 中級 │  [カード]   │
│ □ 上級 │             │
└────────┴────────────┘

4. 「どう動くか」を決める（Behavior）

- 検索バーに入力 → 300ms後に絞り込み
- フィルタをチェック → 即座に絞り込み
- 0件の場合 → 空状態のイラストと「見つかりません」

5. 「エラーをどう扱うか」を決める（Edge Cases）

- API 取得失敗 → エラーメッセージと再試行ボタン
- 検索文字数 > 100文字 → 入力を100文字でカット

仕様書の共有とレビュー

チーム開発では、実装前に仕様書をレビューします:

1. AIに仕様書を生成させる
2. 自分でレビューして修正する
3. チームメンバーに確認する
4. 承認後にコーディングを依頼する

仕様書駆動開発の効果

指標	仕様書なし	仕様書あり
一発で意図通りの実装	30%	85%
手戻りの発生	多い	少ない
実装後の仕様変更	頻繁	まれ

まとめ

仕様書を書く時間は「無駄」ではありません。実装が速くなるほど、仕様の曖昧さが問題になります。仕様書を先に書くことで、実装の質と速度が同時に上がります。