# Spec駆動開発 × Claude Code：AIに大規模実装を任せても壊れない本番ワークフロー

> Vibe codingの対極にあるSpec駆動開発（仕様駆動）で、AIコーディングエージェント（Claude Code）に大規模な実装を任せても本番品質を保つワークフローを解説。仕様を唯一の真実源にし、AIに『決定』ではなく『実装』をさせ、検証ゲートで固める——探索→計画→実装→検証の4フェーズと、機械検査可能な受け入れ条件の設計を、実プロジェクトの知見から体系化します。

- 公開日: 2026-06-25
- 著者: 友田 陽大
- タグ: Claude Code, 生成AI, AI駆動開発, 型安全, テスト, アーキテクチャ設計
- URL: https://tomodahinata.com/blog/spec-driven-development-claude-code-ai-agent-production-workflow

## 要点

- Vibe codingの対極がSpec駆動開発。仕様を唯一の真実源にし、AIには『実装』をさせるが『仕様の決定』はさせない
- ワークフローは探索→計画→実装→検証の4フェーズ。1ショット成功率は『計画』にどれだけエネルギーを注ぐかで決まる
- 受け入れ条件は散文ではなく『機械検査可能なテスト』にする——AIの出力が合格か不合格かを人間の主観に頼らず判定する
- AIの速度を安全にするのは検証ゲート（型・テスト・静的解析・セキュリティ）。AIの出力をそのまま信用しない
- コンテキストは最も希少な資源。仕様・規約をファイル化し、無関係なタスクは分離して、AIの精度を保つ

---

最初に結論を述べます。**AIコーディングエージェントに大規模な実装を任せても本番品質を保つ鍵は、「仕様（Spec）を唯一の真実源にし、AIには『実装』をさせるが『仕様の決定』はさせない」ことです。** 行き当たりばったりにAIへ指示を出す「vibe coding」の対極にあるのが、この**Spec駆動開発（仕様駆動開発）**です。仕様を先に固め、それを機械検査可能な受け入れ条件（テスト）に落とし、AIに実装させ、検証ゲートで合否を機械的に判定する——この規律が、AIの圧倒的な実装速度を、本番運用に耐える品質と両立させます。

GitHubのSpec Kitが短期間で数万のスターを集め、「最も急成長しているAIコーディングのアプローチ」と評されるなど、2026年のソフトウェア開発はこの方向へ大きく動いています。本記事は、私が**一人 × 生成AI（Claude Code）で、経済産業大臣賞を受賞したB2B SaaSや本番二重課金0件の決済基盤を作ってきた**実際のワークフローを、再現可能な形で公開します。

---

## 1. なぜ「vibe coding」は大規模で破綻するのか

「AIにこう作って、と話しかけて、出てきたものを使う」——この vibe coding スタイルは、プロトタイプでは驚くほど速いです。しかし、規模が大きくなると破綻します。理由は単純で、**仕様（何を作るべきか）がAIとの会話の中にしか存在せず、消えていく**からです。

| vibe coding の症状 | 根本原因 |
|---|---|
| 「さっきと違う実装になった」 | 仕様が会話に依存し、再現性がない |
| 修正のたびに別の箇所が壊れる | 受け入れ条件（テスト）がなく、退行を検知できない |
| 全体の整合性が崩れる | 各部分が局所的に生成され、設計が一貫しない |
| 「動くが、本番に出せない」 | 検証ゲート（型・セキュリティ）が抜けている |

vibe coding は「AIに考えさせる」アプローチです。しかし**AIに任せるべきは『実装』であって、『何を作るべきかの決定』ではありません**。仕様の決定を人間が握り、それを永続的な真実源にすることが、Spec駆動開発の出発点です。([AIで作ったコードの本番化](/blog/vibe-coding-ai-generated-code-production-hardening-guide) も参照)

---

## 2. 4フェーズのワークフロー：探索 → 計画 → 実装 → 検証

私が一貫して用いるのは、次の4フェーズです。これは Anthropic 自身が推奨する Claude Code の使い方とも一致し、**1ショットでの成功率は「計画」フェーズにどれだけエネルギーを注ぐか**でほぼ決まります。

```text
1. 探索（Explore）  既存コード・制約・規約を読む。まだ書かない。
   ↓
2. 計画（Plan）     仕様と段取りを固める。受け入れ条件を機械検査可能にする。← ここが勝負
   ↓
3. 実装（Implement）計画に沿ってAIに実装させる。仕様から外れたら止める。
   ↓
4. 検証（Verify）   型・テスト・静的解析・セキュリティを機械的に通す。緑でなければ未完了。
```

### 探索：書く前に読む

最初に、関連するコード・既存の規約・制約を**読むだけ**のフェーズを置きます。ここでAIに実装させないのが肝心です。大規模なコードベースほど、いきなり実装させると既存の規約を無視した「浮いたコード」が生まれます。探索の負荷が高いときは、調査専用のサブエージェントに任せ、メインの文脈（コンテキスト）を汚さないようにします。

### 計画：受け入れ条件を「テスト」にする

ここが最重要です。「ユーザーが正しくログインできること」のような**散文の仕様**は、合否がAIにも人間にも曖昧です。Spec駆動開発では、受け入れ条件を**機械検査可能なテスト**に落とします。

```ts
// 仕様を「散文」ではなく「実行可能な受け入れ条件」として書く。
// AIの実装が「合格」か「不合格」かを、人間の主観ではなくテストが判定する。
describe("注文金額の確定（仕様）", () => {
  it("税率は 0 / 8% / 10% のみ許容し、それ以外は拒否する", () => {
    expect(() => resolveTotal({ lines, taxRate: 0.05 })).toThrow(InvalidTaxRateError);
  });

  it("合計は明細の積み上げ＋税で決定し、クライアント値を信用しない", () => {
    // サーバ側で再計算する（金額改ざんを構造的に排除）
    expect(resolveTotal({ lines, taxRate: 0.1 }).totalJpy).toBe(expectedTotal);
  });

  it("同一の冪等キーでの再実行は二重課金しない", async () => {
    await charge(req);
    await charge(req); // リトライ
    expect(await countCharges(req.idempotencyKey)).toBe(1);
  });
});
```

このテストが先に存在すれば、AIの実装は「テストを緑にする」という明確なゴールに向かいます。私が手がけたプロジェクトでは、決済の料金解決・状態機械・冪等性といった中核ロジックを**純粋関数として隔離し、ゴールデンベクタ（入力と期待出力の固定セット）で単体テスト**しています。仕様がテストとして固定されているので、AIが実装を変えても、退行は即座に検知されます。

---

## 3. AIに「決定」させない：仕様と規約をファイル化する

Spec駆動開発の中核は、**AIに渡す「真実源」をファイルとして永続化する**ことです。会話に埋もれさせない。具体的には、

- **プロジェクト規約（コンスティチューション）**——コーディング原則、禁止事項（`any`禁止など）、アーキテクチャの層分離、テスト方針を、リポジトリ直下のファイル（例: `CLAUDE.md`）に明文化する。AIは毎回これを読み、規約に沿って実装する。
- **機能仕様**——作るべき機能の振る舞いと受け入れ条件を、実装前に文書化する。
- **設計判断の記録（ADR）**——「なぜこの選択をしたか」「受容したリスクは何か」を残す。

このリポジトリ自体も、ルートに `CLAUDE.md`（プロジェクトの憲法）を置き、ローカルな規約ファイルをディレクトリごとに配置しています。AIエージェントは、実装前に必ず該当する規約を読み込みます。**「規約を破ったらどうなるか」を口頭で祈るのではなく、ファイルに明文化し、さらにCIで機械的に強制する**——これが、AIの速度を規律あるものに変える仕組みです。

> **設計思想**: AIは優れた「実装者」だが、放っておくと「その場で最適化」して全体の一貫性を崩します。仕様・規約・受け入れ条件という3つの真実源をファイルに固定し、AIをその制約の中で走らせる。これにより、AIの速度を享受しながら、設計の一貫性を人間が握り続けられます。

---

## 4. 検証ゲート：AIの速度を「安全」にする最後の砦

実装が終わっても、それは「完了」ではありません。**型・テスト・静的解析・セキュリティの検証ゲートを機械的に通って、初めて完了**です。AIの出力を「動いているように見えるから」で信用しないのが、本番品質との分かれ目です。

私のプロジェクトの検証ゲートは、たとえば次のように多層です。

| 層 | 内容 |
|---|---|
| **型** | `mypy --strict` / `tsc --noEmit`。`any` を排除し、不正な状態を表現不能にする |
| **テスト** | 純粋ロジックの単体テスト＋ゴールデンベクタ。CIでカバレッジを強制 |
| **静的解析** | Lint・未使用検出・依存の健全性チェック |
| **セキュリティ** | 秘密情報スキャン・依存の脆弱性監査・コンテナCVEスキャン |

これらを `pre-commit`（変更分のみ・数秒）と `pre-push`（CIのフルミラー）の二段で回し、`main` への直接 push と検証スキップを禁止します。検証ゲートの具体的な設計は[AI駆動開発の品質ゲート](/blog/ai-driven-development-quality-gates-ci-type-safety-test-security)で詳説します。重要なのは、**「AIが速く書く」と「検証で固める」をワークフローとして一体化させる**ことです。速度と安全はトレードオフではなく、設計で両立できます。

---

## 5. コンテキストは最も希少な資源

AIコーディングで見落とされがちな、しかし決定的に重要な原則が——**コンテキスト（文脈）は最も希少な資源だ**、ということです。AIエージェントの精度は、与えられた文脈の質と量に強く依存します。文脈が無関係な情報で汚れると、精度が落ちます。

実務上の規律は次の通りです。

- **無関係なタスクは分離する**——別の作業に移るときは、文脈をリセットする。1つのセッションに複数の無関係なタスクを詰め込まない。
- **重い調査はサブエージェントに逃がす**——大量の検索結果やログの解析は専用エージェントに任せ、メインの文脈を汚さない。
- **同じ修正が2回続けて失敗したら、文脈が汚染されている**——長い修正の連鎖を続けるより、文脈をリセットして、洗練したプロンプトでやり直す方が、ほぼ常に速い。

「長い1つの会話で粘る」より「クリーンな文脈で要点を渡す」方が、結果の質が高い。これは、人間のレビューでも、AIエージェントでも同じです。

---

## よくある質問（FAQ）

### Q. Spec駆動開発とvibe codingの違いは何ですか？

vibe codingは「AIに話しかけて出てきたものを使う」スタイルで、仕様が会話の中にしか存在せず、再現性がありません。Spec駆動開発は、仕様を先に固めてファイルとして永続化し、機械検査可能な受け入れ条件（テスト）に落とし、AIには実装をさせて検証ゲートで合否を判定します。プロトタイプではvibe codingが速いですが、大規模・本番品質ではSpec駆動が必要です。

### Q. AIに任せると品質が下がりませんか？

任せ方次第です。AIに「何を作るかの決定」まで委ねると一貫性が崩れます。Spec駆動開発では、仕様・規約・受け入れ条件という真実源を人間がファイルで固定し、AIはその制約内で実装します。さらに型・テスト・静的解析・セキュリティの検証ゲートをCIで機械的に強制するため、AIの速度を享受しながら本番品質を保てます。

### Q. 「計画」フェーズには、どれくらい時間をかけるべきですか？

1ショットでの成功率は、計画フェーズにどれだけエネルギーを注ぐかでほぼ決まります。実装を急いで計画を飛ばすと、手戻りで結局遅くなります。特に、受け入れ条件を機械検査可能なテストに落とす作業は、計画フェーズで行うべき最重要の投資です。仕様がテストとして固定されていれば、AIの実装は明確なゴールに向かい、退行も即座に検知できます。

### Q. 受け入れ条件を「テスト」にするとは、具体的にどういうことですか？

「ユーザーが正しくログインできること」のような散文ではなく、「この入力に対してこの出力を返すこと」「同一冪等キーの再実行で二重課金しないこと」のように、実行して合否が機械的に判定できるテストとして書くことです。これにより、AIの実装が仕様を満たしているかを、人間の主観ではなくテストの緑/赤で判定できます。

### Q. Claude Code以外のAIエージェントでも使えますか？

使えます。Spec駆動開発は特定ツールの機能ではなく、「仕様を真実源にし、AIに実装させ、検証で固める」という方法論です。探索→計画→実装→検証の4フェーズ、受け入れ条件のテスト化、規約のファイル化、検証ゲートのCI強制——これらはどのAIコーディングエージェントでも適用できる原則です。

---

## まとめ：仕様を握り、実装を任せ、検証で固める

AIに大規模な実装を任せても本番品質を保つために、押さえるべきは次の通りです。

1. **仕様を唯一の真実源にし、AIには『実装』をさせるが『決定』はさせない**——vibe codingの対極。
2. **ワークフローは探索→計画→実装→検証**——1ショット成功率は「計画」への投資で決まる。
3. **受け入れ条件は機械検査可能なテストにする**——合否を主観に頼らない。
4. **AIの速度を安全にするのは検証ゲート**——型・テスト・静的解析・セキュリティをCIで強制。
5. **コンテキストは最も希少な資源**——仕様・規約をファイル化し、無関係なタスクは分離する。

「AIを使って速く作りたいが、品質も担保したい」——この両立こそ、私が一人 × 生成AI で実践してきたことです。Spec駆動開発と検証ファーストのワークフローで、速さと本番品質を両立させる開発を、要件定義から運用までお引き受けします。