仕様駆動開発 — Specsを中心とした開発フロー

はじめに

2025年、**仕様駆動開発（Spec-Driven Development）**が話題になり、関連ツールを試してみました。しかし、従来のSDDには「ドキュメント過剰」の課題を感じ、直近の開発で試行錯誤する中での、私なりのアプローチを整理します。

1. 仕様駆動開発の理想と現実

2025年、AIコーディングエージェントの登場により**仕様駆動開発（Spec-Driven Development）**が再注目されています¹。

SDDの理想

SDDの理想では、Specレビュー → 実装 → テスト/検証 → フィードバックのサイクルが日単位で回転し、AIにより爆速化されるはずでした²。

flowchart LR
    A[📝 Spec作成] --> B[🔍 Specレビュー]
    B --> C[💻 AI実装]
    C --> D[✅ テスト/検証]
    D --> E{フィードバック}
    E -->|修正| A
    E -->|OK| F[🎉 リリース]

現実の課題

しかし、実際にSDDを試してみると、いくつかの課題が見えてきました。

開発手法の歴史 — 振り子の揺れ

開発の歴史は、「重すぎる文書化」と「軽すぎる文書化」の間で振り子のように揺れ動いてきました。³

flowchart LR
    subgraph 歴史の振り子
        A[📚 ウォーターフォール
重すぎる文書化] -->|反動| B[🏃 アジャイル
軽すぎる文書化]
        B -->|反動| C[📝 SDD
再び仕様重視?]
        C -->|課題| D[🎯 バランスを探る]
    end

アジャイル開発は「重すぎる文書化」の反動として生まれましたが、別の課題も生まれました。

2. Feature Branchのアプローチ — 「100%の仕様は作れない」前提

Feature Branchでは、仕様駆動とアジャイルのハイブリッドを試しています⁴。その根底にあるのは、**「100%の仕様書は絶対に作れない」**という前提です。

なぜ100%の仕様は作れないのか

flowchart LR
    A[📄 初期情報] --> B[🔍 想定できる範囲]
    B --> C[📝 仕様書 v1]
    C --> D[💻 実装開始]
    D --> E[⚠️ 未知のリスク発見]
    D --> F[👀 画面を見せる]
    F --> G[🔄 要件変更]
    E --> H[📝 仕様書 更新]
    G --> H
    H --> D

Feature Branchの開発サイクル

flowchart TD
    A[📄 初期インプット
顧客資料・プライム依頼] --> B[🔍 FitGap分析
コードベースとの整合性確認]
    B --> C[📝 Specs作成
**想定できる範囲で**落とし込む]
    C --> D[💻 実装
バイブコーディング]
    D --> E{発見}
    E -->|未知のリスク| F[⚠️ リスク洗い出し・対策]
    E -->|画面FB| G[🔄 要件修正]
    E -->|問題なし| H[✅ 進捗反映]
    F --> I[📝 Specs更新]
    G --> I
    H --> J{次のタスク}
    I --> D
    J -->|あり| D
    J -->|完了| K[🎉 リリース]

    style C fill:#e6f3ff
    style E fill:#fff3e6
    style F fill:#ffcccc
    style G fill:#ffcccc

粒度のコントロール: 全体の仕様を柔らかく保ちつつ、機能単位では細かくFixさせるのがコツです。小さく固まった部品を組み合わせて「動くもの」を見せることで、変動リスクを限定しながら顧客フィードバックを得られます。

ポイント: AIエージェントと一緒にバイブコーディングしながら、未知のリスクを洗い出し、潰していく。画面を見せたら要件がひっくり返ることも織り込み済みで、仕様書を都度更新していくのがFeature Branchのスタイルです。

Feature Branchの開発サイクル v2 — AI活用の具体フロー

新しく開発に入るメンバー向けに、AIを使用した開発の具体的な流れを図解します。

flowchart TD
    subgraph PHASE1[📥 Phase 1: インプット収集]
        A[📄 初期インプットを受け取る] --> A1[箇条書きベース]
        A --> A2[Jiraベース]
        A --> A3[PowerPoint等の資料ベース]
        A --> A4[etc...]
    end

    subgraph PHASE2[📝 Phase 2: AIでSpec作成]
        B1[🔄 テキストベースに変換
Excel→Markdown table
PDF→ChatGPTでMarkdown化] --> B2[📂 リポジトリ配下に配置]
        B2 --> B3[🤖 AIと壁打ちしながらSpec完成]
        B3 --> B4{確認事項あり?}
        B4 -->|あり| B5[📋 確認事項をSpecに記載
コミットして時点を残す]
        B4 -->|なし| C
        B5 --> C
    end

    subgraph PHASE3[✅ Phase 3: 承認]
        C[👤 リーダーにSpec承認依頼] --> C1{承認OK?}
        C1 -->|確認事項あり| C2[🔧 リーダーが仕様確認・Fix]
        C2 --> B3
        C1 -->|OK| D
    end

    subgraph PHASE4[💻 Phase 4: 実装]
        D[🚀 Specを元に実装開始] --> D1{新たな確認事項?}
        D1 -->|あり| D2[📝 仕様書を更新]
        D2 --> C
        D1 -->|なし| D3{規模が大きい?}
        D3 -->|大規模| D4[📊 途中進捗をSpecに記録]
        D4 --> D1
        D3 -->|完了| E
    end

    subgraph PHASE5[🎉 Phase 5: 完了]
        E[👤 リーダーへ完成確認] --> E1{手戻り?}
        E1 -->|あり| B3
        E1 -->|なし| F[✅ 完了]
    end

    PHASE1 --> PHASE2

    style A fill:#e8f5e9
    style B3 fill:#e3f2fd
    style C fill:#fff3e0
    style D fill:#fce4ec
    style F fill:#c8e6c9

AIとの具体的なやり取り例:

3. なぜ仕様駆動がAIエージェントと相性が良いのか

プロジェクトによっては、一般的なSDD（Software Design Document）のように要件・設計・タスクリストにドキュメントを分解することもあります。

4. Specs作成の流れ

実際に specs/anken-tag-specification.md を作成した際の流れです。

sequenceDiagram
    participant U as ユーザー
    participant AI as AIエージェント
    participant C as コードベース

    U->>AI: 📄 keyword-search.pdf を読み取って
    AI->>AI: PDF解析・内容要約
    AI-->>U: 仕様書の概要を報告

    U->>AI: 📝 specs/に仕様を起こしたい
実装候補も出して
    AI->>C: 既存データモデルを調査
    AI->>C: カスタムメタデータ使用状況を確認
    AI-->>U: 実装候補A1/A2/A3を比較表で提示

    U->>AI: ⚠️ 追加制約：ガバナ制限対策が必要
    AI->>C: 既存メール送信パターンを調査
    AI->>AI: 制約を反映して仕様更新
    AI-->>U: 更新版specs完成

5. Specsでの進捗管理

仕様書に実装ファイルパスとステータス列を追加することで、進捗管理も仕様書内で完結できます。

例: メール通知仕様書の進捗管理

1
2
3
4
5

| No  | 通知件名           | 実装ファイル            | ステータス         |
| --- | ------------------ | ----------------------- | ------------------ |
| 3   | ユーザー登録通知   | `touroku-tsuuchi.tsx`   | ✅完了             |
| 4   | 申込審査通知       | `moushikomi-shinsa.tsx` | ✅完了             |
| 15  | アンケート回答依頼 | ※機能未実装             | 🔜次イテレーション |

例: ボタン制御対応のタスク管理

1
2
3
4
5

| No  | タブ名 | ボタン名 | 対応状況   | ファイルパス        | 行番号 |
| --- | ------ | -------- | ---------- | ------------------- | ------ |
| 1   | 申請   | 申請登録 | ✅対応完了 | `shinsei/index.tsx` | L230   |
| 2   | 申請   | 送信     | ✅対応完了 | `shinsei/index.tsx` | L238   |
| 3   | 請求書 | 提出     | ✅対応完了 | `seikyuusho.tsx`    | L407   |

6. 仕様駆動開発のメリット

mindmap
  root((仕様駆動開発))
    コンテキスト共有
      AIが毎回参照可能
      新メンバーのオンボーディング
      顧客との認識合わせ
    進捗可視化
      ステータス列で一目瞭然
      残タスクの把握
      ブロッカーの特定
    変更追跡
      Git履歴で変遷を追える
      なぜこの設計になったか
      意思決定の記録
    品質向上
      FitGap分析の自動化
      既存パターンとの整合性
      レビューの効率化

実践Tips:

• 仕様書は /specs/ ディレクトリに集約
• ファイル名は 機能名-specification.md で統一
• 変更履歴セクションを末尾に追加（日付・バージョン・変更内容・作成者）
• AIに「この仕様書を更新して」と言えば、差分だけ更新してくれる

参考文献