バイブコーディングの一形態、AI主導の仕様駆動開発
AIにコードを書かせたら、最初は速かったのに、機能が増えるにつれてコードがスパゲッティ化して破綻した――そんな経験はありませんか？このマニュアルは、AIの『暴走』と『仕様のズレ』を仕組みで解決します。
【フェーズ1】森を見る：Markdownによるユーザーストーリーマッピング
開発のスタート地点です。ここではアプリ全体のビジョンを可視化し、「何を作って、何を後回しにするか（スコープ管理）」を決定します。
人間がやること
テキストエディタ（VS Code、Notion、Obsidianなど）を開き、ユーザーの行動時系列（横軸）を「見出し（##）」、具体的なストーリー（縦軸）を「箇条書き（-）」、そして優先度（リリースライン）を「水平線（---）」やカテゴリで表現したマップを作成します。
AIの活用方法
「こういうアプリを作りたい」というアイデア段階のフワッとした状態から、ストーリーマップの原案をAIにブレインストーミングさせます。
AIへのプロンプト例
あなたは優秀なプロダクトマネージャーです。これから「[アプリの概要、例: 技術記事の要約とクイズ化をしてくれる学習効率化アプリ]」を個人開発しようと考えています。
このアプリの「ユーザーストーリーマップ」を、Markdown形式で出力してください。
横軸（ユーザーの時系列の行動ステップ）を ## の見出しとし、それぞれのステップの下に縦軸となる具体的なユーザーストーリー（誰が何のために何をしたいか）を箇条書きで並べてください。
また、ストーリーは「リリース1（最小限のMVP）」と「リリース2（後回しにする機能）」の2つの優先度に分けて配置してください。異常系は含めず、ハッピーパス（正常系）を中心に構成してください。
成果物（specs/story_map.md）
人間は、AIが吐き出したマップをレビューし、自分の理想に合わせて微調整してリポジトリのルートに保存します。
【フェーズ2】木を見る：ユースケース単位の仕様書作成
ストーリーマップから「リリース1」のアイテムを1つ選び、具体的な仕様書に昇格させます。アプリが大きくなっても破綻しないよう、フォルダは技術単位ではなく「ユースケース（ユーザーの行動）単位」で分割します。
1. フォルダ構成の構築（人間）
specs/
├── auth/ # 認証ステップのフォルダ
├── article_summary/ # 記事要約ステップのフォルダ
│ └── summary_basic.md # 📄 今回作成する個別の仕様書ファイル
└── schemas/
2. 仕様書の作成（人間 ➔ AI）
仕様書には「WHY（背景）」「WHAT（概要）」「受入基準（Given-When-Then）」を書きます。特に「受入基準」のフェーズで初めて、バリデーションや異常系を徹底的に洗い出します。
AIへのプロンプト例
あなたはシニアビジネスアナリストです。ストーリーマップにある「タイトルだけでシンプルにタスクを登録したい」というストーリーを、詳細な仕様書（Markdown）に落とし込みたいです。
以下の構成で仕様書を作成してください。
- WHY（なぜ作るのか、ビジネス・ユーザー視点の目的）
- WHAT（何を作るのか、機能の概要）
- 受入基準（システムがどう動くべきか。テストコードに直結するよう、Given-When-Thenの形式で書くこと。正常系1パターンだけでなく、空欄エラー、文字数オーバー、通信エラーなどの異常系・バリデーションも考えられる限り網羅してください）
- 関連リンク（APIスキーマへのプレースホルダーリンク）
成果物（specs/task_registration/task_create_simple.md）
人間は、AIが提案した「受入基準（異常系のパターンなど）」に漏れがないかを確認し、仕様を確定させます。
【フェーズ3】規約を作る：スキーマ定義（OpenAPI）
日本語の仕様書（WHAT）ができたら、次はそれをフロントエンドとバックエンド、そしてAIが解釈できるデータの規約（インターフェース）に翻訳します。仕様書（Markdown）とは完全に別ファイルとして specs/schemas/openapi.yaml を作成します。
OpenAPIをゼロから書くのはAIでもたまに構文エラーを出すため、「Swagger Editor等でのリアルタイムチェック」や「AIへの構文チェック指示」に一言触れると親切です。
AIの活用方法
Markdownの仕様書（特に受入基準のインプット/アウトプット、エラーの条件）をAIに渡し、OpenAPIのYAMLコードを生成させます。
AIへのプロンプト例
添付の仕様書（task_create_simple.md）を読み込み、この機能で必要となるAPIの設計図を、OpenAPI 3.0 (YAML形式) で作成してください。
- エンドポイント: POST /api/v1/tasks
- 受入基準にある正常系のリクエスト/レスポンスの構造（JSON）を定義すること。
- 受入基準にある異常系（空欄、文字数オーバー）の際に返すステータスコード 400 Bad Request とエラーメッセージの構造も定義に含めてください。
- 再利用可能なデータモデル（Task型やError型など）は components/schemas に切り分けて定義してください。
成果物（specs/schemas/openapi.yaml）
これで、人間が考えるべき「WHAT（設計）」の成果物がすべて揃いました。
【フェーズ4】Git & GitHubによる仕様の「先行マージ」
コードを書く前に、決定した仕様をGitHub上で「絶対の正義」として確定させます（仕様ファーストの徹底）。
1. 仕様専用ブランチの作成（人間）
Bash
git checkout -b feat/issue-12-specs
新しく作成・修正した story_map.md、task_create_simple.md、openapi.yaml をコミットし、GitHubにプッシュします。
2. 仕様PR（Pull Request）の作成とマージ（人間）
GitHub上で「仕様確定Pull Request」を作成します。個人開発であっても、ここで一度自分の仕様を客観的に見直します（AIに「この仕様に矛盾や、セキュリティ・パフォーマンス上の懸念がないかレビューして」とPRの差分をレビューさせるのも効果的です）。
問題がなければ、実装コードを書く前に、この仕様PRを main ブランチにマージします。
【フェーズ5】土台を作る：プロジェクト初期化と自動生成
ここから「HOW（実装）」のフェーズに入ります。最新の main ブランチから、今度は実装用のブランチ（feat/issue-12-impl）を切り、開発環境を準備します。
1. プロジェクトの初期化（人間がコマンド実行）
フレームワークの初期化コマンド（例: npx create-next-app@latest など）を使用して、標準的なフォルダ構造（src/ など）を作成します。
2. スキーマからのコード自動生成（ツール & AI）
人間が手動で型定義ファイルを作るのは禁止です。OpenAPIの自動生成ツール（Orval、OpenAPI Generator、またはAI）を使い、openapi.yaml からフロントエンド用の型定義（TypeScript）やAPIクライアントを src/generated/ フォルダへ自動出力させます。
AIへのプロンプト例（Orval等の設定ファイルをAIに作らせる場合）
specs/schemas/openapi.yaml から、Next.js (TypeScript) 向けに型定義とAPIクライアントコードを自動生成したいです。Orval（またはopenapi-generator）の設定ファイル（orval.config.js 等）のコードを生成し、実行コマンドを教えてください。生成先は src/generated/ としてください。
人間は、出力されたコマンドを実行し、型定義を自動生成します。
🧠 【フェーズ6】AIと並走する：タスク分割・実装・自動テスト
開発用AIエディタ（Cursorなど）を立ち上げます。ここでの鉄則は、「スコープを1つの仕様書（1ファイル）に極限まで絞り、AIに主導権を握らせないこと」です。
1. AIによるタスク分割
実装を始める前に、仕様書をAIに読み込ませて、実装ステップを細かく分解（WBS化）させます。
AIへのプロンプト例（Cursor等のAIチャット）:
@task_create_simple.md (仕様書) と @openapi.yaml (スキーマ) をインプットとして読み込んでください。
これからこの機能を実装するための、具体的な開発タスク（ToDoリスト）をステップバイステップで書き出してください。
タスクは「バックエンド」「フロントエンド」「テストコード」のカテゴリに分け、1タスクあたり1〜2時間以内で終わる最小単位に分解してください。
人間は、出力されたタスクリストをGitHubのIssue、またはリポジトリ内の TODO.md にチェックリストとして貼り付けます。
2. AIによるロジックの実装（1タスクずつ）
タスクリストの上から順に、AIにファイルを「新規作成」または「修正」させます。
AIへのプロンプト例:
仕様書 @task_create_simple.md の【受入基準（シナリオ1, 2, 3）】を完全に満たすように、src/handlers/task_handler.ts というファイルを新規作成し、バックエンドのビジネスロジックを実装してください。
先ほど自動生成された src/generated/ の型定義をインポートして、型安全に実装してください。
正常系だけでなく、空欄、101文字以上の時の400エラーとエラーメッセージの返却ロジック（異常系）も漏れなく書いてください。
💡 【重要】この仕様書に書かれていること以外の機能（期日の設定やメモなど）のコードは、たとえ簡単であっても絶対に書かないでください。
AIがコードを出力したら、人間はコードレビューを行い、意図通りか確認します。
3. AIによる受入基準のテストコード化
ロジックができたら、即座にテストコードを書かせます。仕様駆動開発において、テストが通るまではコードは未完成です。
AIへのプロンプト例:
先ほど作成した src/handlers/task_handler.ts に対して、仕様書（ @task_create_simple.md ）の【受入基準】（シナリオ1、2、3）と1対1で対応する自動テストコードを tests/task_handler.test.ts に新規作成してください。
各テストケース（it や test）のタイトルは、仕様書の「シナリオ1: ○○」という文言をそのまま使用してください。テスティングフレームワークは [Jest / Vitest / Playwright等] を使用してください。
人間は、ローカル環境でテストコマンド（npm run test）を実行し、すべてのテストが 「Pass（緑色）」 になるのを確認します。フロントエンドも同様のステップで、UIの実装とコンポーネントテスト（またはE2Eテスト）を行わせます。
🚀 【フェーズ7】マージとCIによる自動検証
すべてのタスクのチェックが埋まり、ローカルでのテストが通過したら、GitHubへプッシュして実装Pull Request（PR）を作成します。
1. 実装PRの作成（人間）
PRの概要欄には、必ずベースとなった仕様書へのリンクを記載します。
Markdown
## 🔗 関連仕様書* specs/2_task_registration/task_create_simple.md* Closes #12## 🎯 受入基準の検証ステータス- [x] シナリオ1 (正常系登録) -> テスト通過- [x] シナリオ2 (空欄エラー) -> テスト通過- [x] シナリオ3 (文字数オーバー) -> テスト通過
2. GitHub Actionsによる「嘘（ズレ）」の自動検知（CI）
PRが作成されると、GitHub Actions（CI）が自動的に起動し、以下の検証を強制します。
OpenAPI Lint: スキーマファイル（openapi.yaml）の記述に構文エラーがないかチェック。
同期チェック（Diff検証）: CI環境で自動生成コマンド（npm run generate）を再実行し、リポジトリ内のコードと差分が出ないか（＝人間が手元で型定義の更新を忘れていないか）を検証。差分があればビルドを失敗させる。
テスト実行: AIが書いた受入基準のテストを全件実行し、1件でも落ちればマージをブロックする。
3. mainへのマージ（人間）
すべてのCIチェックが「緑色（Pass）」になったら、PRを main ブランチにマージします。これで、1つのユーザーストーリーの開発ライフサイクルが完全に完了しました。
📝 仕様駆動開発を成功させる「AIコントロールの鉄則」
個人開発でAIにコードを書かせるとき、この仕様駆動開発のプロセスを踏まないと、AIはすぐに「独自の解釈」で暴走し、コードの辻褄が合わなくなってプロジェクトが崩壊します。以下の3つの鉄則を脳裏に刻んでください。
AIへの指示は常に「仕様書ファイル（Markdown）のパス」を渡す
チャット欄に「〜な機能を作って」と自然言語でその都度指示を打ち込んではいけません。必ず「この仕様書（@filename）の受入基準を実装して」という指示の出し方を徹底します。これにより、プロンプトのブレがなくなり、AIの出力精度が極限まで高まります。
仕様（WHAT）の変更は、絶対にコードから先にやらない
開発途中で「やっぱりこういう挙動にしたい」と思ったら、コードを直接書き換えるのではなく、必ず【フェーズ4】に戻り、仕様書やスキーマを修正して main に先行マージするプロセスを踏んでください。ドキュメントを「正（Single Source of Truth）」とすることで、過去のコードとのデグレードを完全に防げます。
AIに「未来の予測」をさせない（スコープの限定）
AIは親切心から「将来のために、この拡張性も持たせておきました！」と余計なコード（期日やカテゴリーの枠組みなど）を書きがちです。これはバグと複雑さの温床になります。「仕様書（リリース1）に書いていないコードは1文字も書くな」と厳しく制約をかけ続けることが、個人開発のスピードを最速に保つ秘訣です。