[生成AI] 2025/10 中旬時点での Spec Driven バイブコーディングフローを整理してみた

こんにちは。

2025年10月時点で、Claude Code や Codex と一緒に「Spec Driven × Vibe Coding」というドキュメント先行フローをチームで回しています。

特徴は、SpecレビューとPRレビューの二段階で認識合わせを挟み、ズレを潰しながら開発を進めること。この記事では、その型と運用の勘所を整理します。

TL;DR

• フローは Spec記載 → Specレビュー → テスト作成 → コーディング → リファクタ → PR の二段階レビューでズレを潰す
• Specのクオリティと視点の多さがエンジニアの勝負所。なぜこの開発をするのか、どんな設計を想定しているかを言語化する力が効く
• ドキュメント整備が肝。Specだけでは補えない全体像を伝える補助資料をどれだけ揃えられるかが、チームの地力になる

全体像：従来プロセスとの違いを並べて見る

図では「従来の開発プロセス」と「Spec Driven × Vibe Coding」を横並びで比較しています。

• 従来：PMや顧客がまとめた要件をそのままテストケースとコーディングに流し込み、終盤のレビューでズレが噴出しがち
• 新フロー：担当エンジニアが SPEC.md と補助ドキュメントで要件を再構成し、Specレビューで認識を合わせてからテスト・実装へ進む
• 実装フェーズ：バイブコーディング（実装＋リファクタ）を一塊で回し、最後のチームレビューはAIレビューを併用してスピードと証跡を両立

2025年の前提

• IDE／CLI／エージェントは成熟してきたが、完全自動の評価フローはまだ模索中
• 一方で、回帰テストやPRレビューにAIを組み込むことで開発速度は引き上げられる
• もっともズレやすいのは要求の理解。Specを事前に書き込み、合意する時間を確保するのが一番効く

エンジニアの勝負所はSpecの厚み

• なぜ今この開発をするのか、どこまでをスコープにするのか、どの設計をベースにするのか――を文章と図で言い切れる人が強い
• 「想定していた設計の撮影角度」をSpecで固定しておくと、AIも人も迷子にならない

この結果、「Spec（要件）＋ 補助ドキュメント」で文脈を固め、Specレビュー → コードレビューの二段階で合意を積む運用に落ち着きました。

Step 1：Problem Statement を SPEC.md に落とす

「この開発は何のためか」「どんな設計で着地させたいか」を言語化する工程です。ここでの情報量と視点の多さが、エンジニアとしての説得力そのものになります。

ここで書く最低ライン

• 背景と目的：なぜ今これをやるのか。成功指標は数値で（例：CVR 8%→10%、p95 < 300ms）
• スコープ／非スコープ：やること・やらないことを箇条書きで
• 完成イメージ：UIモックや主要フローのシーケンス図、既存機能との接続図
• アーキテクチャ方針：コンポーネント構成、依存サービス、データフロー
• DB・データ契約：テーブル差分、マイグレーション段取り、イベント/スキーマの変更点
• 非機能（NFR）：SLO/SLI、セキュリティ、レイテンシ、コスト上限
• テスト観点と運用：自動テストの粒度、アラート・メトリクス、オープン課題
• 受け入れ基準（AC）：入力→処理→出力を、正例・反例・境界値で網羅

ミニテンプレ

# SPEC.md
## 背景 / 文脈
- 直近の課題や顧客インサイト
- 既存機能との関係（影響範囲）

## 目的 / KPI
- 〜のCVRを8%→10%へ（90日）
- エラー率 < 0.5% / p95 < 300ms

## スコープ / 非スコープ
- スコープ: xxx（採用する機能と理由）
- 非スコープ: yyy（やらない理由と代替策）

## 完成イメージ
- 画面モック・ユースケース図
- シーケンス図（主要ケース／退避ルート）

## アーキテクチャ方針
- コンポーネント構成と責務（図を添付）
- 外部サービス・依存ライブラリ
- 失敗時の縮退策 / フォールバック

## データ / DB
- 追加・変更テーブル（DDL差分、インデックス方針）
- マイグレーション手順（段階適用、ロールバック案）
- 契約変更（API / Event / Schema）

## 非機能 / 運用
- SLO/SLI: ...
- セキュリティ: PII扱い/ログ方針/権限
- コスト: 月$X以内（上限時の縮退策）
- 監視・アラート: 監視項目 / ダッシュボード / 閾値

## 受け入れ基準（AC）
- 正例: 入力A→出力B（境界値含む）
- 反例: 入力C→エラーD（理由・メッセージ指針）

## テスト観点
- 自動テストの種類（契約 / プロパティ / E2E）
- 手動テストが必要な観点と理由

## オープン項目 / リスク
- 未決事項、検証タスク、依存チームとのToDo

依存と契約の書き方

• APIやDBはSPECを一次ソースにして、OpenAPI/JSON Schemaへ落とし込む
• マイグレーションは後方互換の段取りとセットで記述する
• 外部APIのレート制限・失敗時リトライ・フォールバックも明文化しておく

ACの作り方のコツ

• 正例は通常系・境界・例外の最低3パターン
• 反例で「やらないこと」「許容しない入力」を明示
• テーブル化すると、後でテストにそのまま食わせられる

Step 2：SPEC.md をレビューする（1つ目のゲート）

ここで「やるべきこと／やらないこと」「設計の撮影角度」に合意が取れているかを確認します。以降の工程はこの合意を前提に進むので、レビュー時に引っかかった仮説はここで全部吐き出すのが鉄則です。

チェックリスト

• 曖昧語を排除：「適切に」は数値に置き換える
• 前提が衝突していないか：非機能と外部制約の擦り合わせ
• データ契約：型・必須・enum・ID命名をSchemaで表現
• 失敗時の振る舞い：ユーザ通知、リトライ回数、DLQ、監視

合意の残し方

• PRテンプレに「Spec差分」欄を用意して必ず埋める
• SPEC末尾にADR風の決定記録（日時・参加者・保留事項）を追加
• 「Specを変えたらテストも変える」を自動化（CIで差分をチェック）

Step 3：Spec からテストを起こす

Specレビューで固めた内容を、そのまま検証ロジックに落とし込むステップです。ここまでのドキュメントが厚いほど、生成AIに任せられるテストの範囲が広がります。

契約テストはSpecがソース

• SPECから OpenAPI / JSON Schema を生成し、Pact/Contractテストに活用
• 変更があればスナップショット差分をPRに貼り付ける

テスト種類の分担

• 契約テスト：API境界の破壊を防ぐ（型・必須・HTTPコード）
• プロパティテスト：可換性・単調性などの性質をランダム検証
• E2Eテスト：ユーザ価値に直結する経路だけを抑える（数は絞る）

ゴールデンデータと回帰

• 期待出力（ゴールデン）をリポジトリに置き、更新はPRで差分確認
• コストやレイテンシの閾値もテスト化して「性能が壊れた」を検知

Step 4：Vibe Coding（実装）を回す

ここからがバイブコーディングの前半。Specレビューで握った内容を小さなループで形にし、必要に応じてAIに task.md のようなタスクリストを出してもらうと迷子になりにくいです。命名・例外・UIトーンといった雰囲気は、リポジトリ内のガイドライン集（命名規約やコンポーネント規約など）を常に参照するようにします。

Red → Green → Refactor

• 一番小さいACをRedにしてからGreen、最後に整える
• プロンプトは1関数・1コンポーネント単位で局所化し、SPEC.mdと関連ガイドラインを添付
• 生成結果の根拠や意図をAIに説明させ、読み合わせの材料にする

セッション運用のコツ

• 迷ったらタスクリストを再生成し、作業単位をリセット
• 依存が重い箇所はスタブやフェイクで切り出し、契約部分だけ先に固める
• 生成がぶれ始めたら、ガイドライン集に命名・例外ルールを追記して再実行

Step 5：Vibe Coding（リファクタとSpec/テスト同期）

バイブコーディングの後半戦。実装で得た学びを設計とドキュメントに反映し、Specとテストを揃える工程です。

整流化するところ

• 関心の分離（I/O・ドメイン・ビュー）を物理的に分割
• 例外方針は「再試行すべき」「即座に落とす」で型やクラスを分ける
• 命名やUIトーンがガイドライン集とずれていないかを点検

逆流修正

• 新しく得た前提・制約はSPEC.mdと補助ドキュメントに追記
• テストには意図コメントを添え、未来の自分とAIへ文脈を残す
• リファクタ専用のセッションを設け、差分を入力にAIへ改善案を出させる

Step 6：チームレビュー（AI併用のPR運用）

図の最後にある「チームレビュー w/ AI」に該当。Specレビューで握った前提どおりに実装されているか、リスクが潰されているかを最終確認します。現時点でAIレビューは補助的な位置付けですが、1,000行級の修正では観点漏れを減らす強力な保険になります。

AIに投げる観点例

• 「SPEC.mdのAC一覧と差分を照合し、未カバーテストを列挙」
• 「命名規約集と例外方針の逸脱を指摘」

人が見る観点

• 安全性：データ破壊・漏えい・権限
• 可読性：意図が見えるか、副作用が隔離されているか
• 妥当性：計測結果、回帰リスク、ロールバック手順

PRテンプレ（抜粋）

# PR_TEMPLATE.md
- 目的（SPEC.mdリンク）
- 変更点（コード/スキーマ/契約）
- Spec差分（ACの追加/変更/削除）
- テスト（E2E/契約/プロパティ）と結果
- 計測（p95/コスト）の比較
- ロールバック手順（Feature Flag/DB巻き戻し）

運用メモ：Docs as Code を根付かせる

Specを書くだけでは全体像は伝わりません。背景・判断・実装方針をつなぐ補助ドキュメントをどこまで整備できるかで、チームの強さが決まります。

テンプレ運用

• SPEC_TEMPLATE.md と PR_TEMPLATE.md をリポジトリに常備
• 全更新はPR経由にし、レビューチェックリストを自動付与
• ドキュメントもCI対象（リンク切れ・スキーマ整合をチェック）

コンテキストドキュメントを用意

• デザイン：採用技術・ライブラリ・アーキテクチャ方針
• UI：コンポーネント設計や文言ルール
• インタラクション/進行：テスト駆動の進め方、進捗更新のフォーマット
• プロジェクト前提：役割分担、禁止事項、エスカレーション経路

履歴と指標の一元化

• SPEC末尾にADRを追記して意思決定を保管
• READMEに性能・コスト・品質ダッシュボードへのリンクを常設

よくある失敗と対策

• 曖昧Spec：数値と境界値をテーブル化して強制
• テスト観点の偏り：E2Eだけに寄らず、契約・プロパティを組み合わせる
• 自動化しすぎ：合意のプロセスを飛ばさない。PRで意思決定を残す

こんな感じで、SpecとVibe Codingをセットで運用すると生成AIが扱いやすくなります。引き続きアップデートしたら追記します。