edit_square

ブログ

Posts

考察 テクノロジー・ＡＩ

バイブコーディングの一形態、AI主導の仕様駆動開発

AIエージェントの発展により、自然言語による指示だけでアプリを構築する「バイブコーディング」が広まりつつあります。しかし、仕様の明文化を伴わないまま高速に試作を続けると、次第に全体の辻褄が合わなくなり、プロジェクトが崩壊するケースが少なくありません。

本記事では、この課題を解決するためにAIと議論を重ねて構築した、AI時代向けの「仕様駆動開発（Specification-Driven Development: SDD）」のワークフローを提案します。

※本記事では「自然言語主体でAIに実装を委譲する開発スタイル」を便宜的にバイブコーディングと呼び、AIエージェントを活用した個人・小規模開発を対象としています。

序論：人間が「WHAT」を、AIが「HOW」を担うAI時代向けの個人開発ワークフロー

AIエディタやAIエージェントの爆発的な進化により、個人開発を取り巻く環境は激変しました。しかし、多くの開発者が「AIエージェントに指示を出してコードや仕様を自動で書き換えさせているうちに、コンテキスト外の推測実装を行い、全体の辻褄が合わなくなってプロジェクトが崩壊する」という壁に直面しています。

本記事では、AI時代向けに再構成した「仕様駆動開発（Specification-Driven Development: SDD）」を提案します。ここでいうSDDとは、「仕様を唯一の基準としてAIに実装を行わせる開発手法」を指します。

本ワークフローの核心は、人間は主に「WHAT」の設計と意思決定に集中し、AIに「HOW（実装とテスト）」という泥臭い作業を正確かつ爆速で代行させることにあります。特に、最高法規である「ビジョン」や「仕様書」「スキーマ」といったWHATの領域は、AIエージェントに自動書き換え（Apply：AIがファイルを直接編集する機能）をさせず、人間がチャットAIと対話しながら自らの手でコントロールします。

ドキュメントをプロジェクトの「唯一の正しい情報源」として厳格に管理し、コードよりも先に仕様を確定させることで、個人開発のスピードと持続可能性を極限まで高めます。

第1章：ドキュメントの構造

プロジェクトの破綻を防ぐための最重要原則は、ドキュメントの「多重管理（同じような内容が複数のファイルに散らばっている状態）」を徹底的に排除することです。本ワークフローでは、情報の抽象度に応じて役割を明確に分離し、ドキュメント間の齟齬（ズレ）が発生しない構造を構築します。

 specs/
 ├── vision.md             # 【ビジョン】プロダクトの方向性を定義する最上位ドキュメント（Why / What）
 ├── architecture.md       # 【技術仕様書】全体の技術土台・システム制約
 ├── story_map.md          # 【羅針盤】最初の一回限りの全体ロードマップ
 ├── 1_auth/               # 【ステップフォルダ】行動ステップごとの分類
 │   ├── spec_v1.md        # 【個別仕様書】ストーリーごとの受入基準・機能制約
 │   └── spec_v2.md        
 └── schemas/
     └── openapi.yaml      # 【データ規約】1ファイル集約のAPIスキーマ

1. ビジョン（vision.md）

  • 抽象度：最高（不変の魂）
  • 役割： 人間の熱量とプロダクトのコア価値を言語化し、AIにアプリの軸をインストールする最高法規。
  • 記述内容： 純粋なユーザー視点の「Why」と「What」。技術的な話や開発都合の「やらないこと」などは1文字も入れず、人間がすべて手書きします。アプリのコンセプト自体が180度変わらない限り、原則として頻繁には変更しない、中長期的な指針となるファイルです。

2. 技術仕様書（architecture.md）

  • 抽象度：中（システムの土台）
  • 役割： システム全体の共通ルールと技術的な制約を縛るドキュメント。
  • 記述内容： 使用するフレームワーク、データベース、外部API、インフラ環境、およびシステム全体の非機能要件。技術スタックの変更やリプレイスが発生した際のみ更新します。

3. ユーザーストーリーマップ（story_map.md）

  • 抽象度：中（全体ロードマップ）
  • 役割： 最初の一回限り、アプリ全体のビジョンを可視化し、リリースの境界線を引くための「地図」。
  • 記述内容： Markdown形式で表現された二次元のストーリーマップ。

4. 個別仕様書（spec_v1.md などの各仕様ファイル）

  • 抽象度：低（具体的な挙動）
  • 役割： ストーリー単位で、システムが満たすべき具体的な挙動とスコープ（引き算の思想）を定義するファイル。
  • 記述内容： 構造化された「受入基準（Given-When-Then形式）」と、その機能において「やらないこと（Not-To-Do）」。

5. APIスキーマ（openapi.yaml）

  • 抽象度：低（データ規約）
  • 役割： フロントエンド、バックエンド、そしてAIが解釈できるデータの契約書。
  • 記述内容： エンドポイント、リクエスト/レスポンス構造、エラー定義。ツールの利便性とデータモデルの再利用性を最大化するため、個人〜小規模開発では分割せず「1つのファイルに一元管理」します。

第2章：立ち上げフェーズ（最初の一回限りのプロセス）

アプリのゼロイチ開発におけるスタート地点であり、全体の方針と「フォルダ構成という目次」を決定するためのフェーズです。

ステップ1：人間の手による「ビジョン（vision.md）」の執筆

開発のすべての源泉です。人間がテキストエディタを開き、頭の中にある熱量を「Why」と「What」に特化して詳しく書き出します。

ステップ2：最初の一回限りの「ユーザーストーリーマッピング」

作成したビジョンをインプットとしてチャットAI（ChatGPTやClaudeなど）に渡し、全体のロードマップとなるストーリーマップをMarkdown形式で生成させます。

Markdownによる表現の定義は以下の通りです。

  • 通常のマッピングでは横軸（ユーザーの行動ステップを時系列で書く）： ##（大見出し）で表現
  • 通常のマッピングでは縦軸（各ステップにおける具体的なユーザーストーリー）： -（箇条書き）で表現。「誰が・何のために・何をしたいか」をシンプルに記述します。
  • リリースライン（優先度の境界線）： ###（中見出し）や水平線（---）で区切り、「リリース1（MVP）」と「リリース2（後回しにする機能）」に明確に配置を分けます。異常系は含めず、ハッピーパス（最も一般的で障害のない正常系シナリオ）を中心に構成します。

人間はAIが吐き出したMarkdownテキストをレビュー・調整し、specs/story_map.md としてリポジトリのルートに保存します。このマップは最初の一回限りの羅針盤であり、以後の機能追加では原則更新しません。

ステップ3：ストーリーマップに基づく「フォルダ構成」の構築

確定したストーリーマップのステップ（## の見出し）に基づき、specs/ 配下にステップ単位のフォルダを作成します（例：1_auth/や2_article_summary/）。フォルダがそのままドキュメントの目次となり、開発が巨大化しても破綻しない構造を作ります。

ステップ4：個別仕様書とAPIスキーマの作成

該当するフォルダ内に、最初のMVPストーリーに対応する個別仕様書（spec_v1.md）を作成します。チャットAIを活用し、背景、概要、そしてテストコードに直結する「受入基準（Given-When-Then）」を徹底的に洗い出させます。バリデーションや異常系をこの段階で網羅します。仕様書（WHAT）ができたら、それを元にAIに specs/schemas/openapi.yaml を生成させます。

第3章：運用・拡張フェーズ（チャットAIを用いた「WHAT」の更新プロセス）

アプリのリリース後、あるいは開発中盤以降のワークフローです。ストーリーマップには戻らず、仕様書とスキーマを直接更新していく「差分開発」へとシフトします。

ここでの鉄則は、「仕様書やスキーマの変更に、AIエージェントによる自動書き換え（Apply）は絶対に使わない」ことです。自動書き換えは既存の構造を破壊したり、人間の意図しない変更を巻き込んだりするリスクが非常に高いためです。仕様の変更は、必ずチャットAIに修正案を出させ、人間が確認しながら自らの手でドキュメントを更新・コピペするアプローチを徹底します。

【パターンA：新しい機能を追加する場合】

  1. 新規の仕様書ファイルの作成:

    新しいステップフォルダ（例：specs/3_folder_management/）を切り、チャットAIと壁打ちしながら、その中に新しい仕様書（folder_create.md）を新規作成します。既存の仕様書をいじらないため、既存機能の破壊（デグレード）が起きません。

  2. APIスキーマの追記:

    チャットAIに新しい仕様書を読み込ませ、「OpenAPIに追加すべきYAMLのコードブロックだけ」を出力させます。人間がその内容を確認し、openapi.yaml の末尾に手動でコピペ（追記）します。

【パターンB：既存の機能を修正・変更する場合】

  1. 既存仕様書の修正:

    該当するユースケースの仕様書（spec_v1.md）をチャットAIに渡し、変更したい条件部分（Given-When-Then）のみの修正案を出力させます。人間は関係のない記述が破壊されていないか確認した上で、手動で仕様書を更新し、末尾に「変更履歴（Changelog）」を記録します。

  2. APIスキーマの修正:

    仕様書の変更に合わせて、チャットAIに openapi.yaml の該当箇所の修正案を出させ、人間がピンポイントで書き換えます。

第4章：仕様の「先行マージ」とGit/GitHubライフサイクル管理

コード（HOW）を1文字でも書く前に、決定・修正した仕様をリポジトリ上で「絶対の正義」として確定させます。

  1. 仕様専用ブランチの作成とプッシュ:

    人間は、追加・修正したドキュメント類（仕様書、OpenAPI）をコミットするための専用ブランチ（例：feat/issue-12-specs）を切り、GitHubにプッシュします。

  2. 仕様PRの作成とマージ:

    GitHub上で「仕様確定Pull Request」を作成します。AIにPRの差分を読み込ませて設計の穴をレビューさせた後、実装コードを書く前に、この仕様PRを main ブランチにマージします。これにより仕様が「マスターデータ」として固定されます。

第5章：AIエディタと並走する「HOW」の実装・テストフェーズ

仕様が main に確定したら、ようやくここからAIエージェント（CursorのAgentモードなど）による自動生成・自動書き換え（HOWの代行）を全面解禁します。実装用のブランチ（feat/issue-12-impl）を切り、AIエディタを立ち上げます。

  1. スキーマからのコード自動生成:

    Orval等のツールを使い、 openapi.yaml からフロントエンド用の型定義（TypeScript）やAPIクライアントを src/generated/ へ自動出力させます（ここはスクリプトまたはAIによる自動実行）。

  2. AIによる技術的なタスク分割（WBS化）:

    AIに、確定した「1つの仕様書」「1つのスキーマ」「技術仕様書（architecture.md）」だけを読み込ませます。AIにファイル単位の具体的な修正手順（ToDoリスト）を分解させ、人間はこれを TODO.md に貼り付けます。

  3. テストコードの先行作成・修正（TDDアプローチ）:

    AIエージェントに指示を出し、仕様書の【受入基準】（シナリオ1、2、3...）と1対1で対応する自動テストコードをファイルに直接自動生成（または修正）させます。この段階でテストを実行すると、ロジックが未実装のため必ず「Fail（赤色）」になります。

  4. AIエージェントによるロジックの実装:

    タスクリストに沿って、AIエージェントにロジックを自動書き換え（Apply）させます。「仕様書に書かれていること以外のコードは絶対に書くな」という制約をかけ、ローカルでテストを実行して、すべてのテストが 「Pass（緑色）」 になるのを確認します。

第6章：CIによる自動検証とOpenAPIの保護戦略

すべてのタスクが完了したら、GitHubへプッシュして実装PRを作成します。ここではCI（GitHub Actions）と人間の目によって、openapi.yaml とプロジェクト全体の品質を強固にガードします。

PRが作成されると、CI環境で以下の検証が強制実行され、1件でも落ちればマージがブロックされます。

  1. OpenAPI Lint: スキーマファイルに構文エラーやインデントのズレがないかチェック。人間が手動コピペした際のミスをここで高い確率で検知します。
  2. 同期チェック（Diff検証）: CI環境で自動生成コマンドを再実行し、リポジトリ内の生成コードと差分が出ないか（手元での生成忘れがないか）を検証。
  3. 全件テスト実行: 既存の全テストを自動実行し、AIエージェントのコード書き換えによる既存機能へのデグレードの検知と抑止を強化します。

すべてのCIチェックが「緑色」になったら、PRを main ブランチにマージし、開発ライフサイクルが完了します。

結論：AIコントロールの3大鉄則

  1. AIへの指示は常に「個別仕様書ファイルのパス」をコンテキストとして渡す

    その場の思いつきの自然言語ではなく、「この仕様書（@filename）の受入基準を実装して」という指示に徹することで、AIの出力精度が極限まで高まります。

  2. 仕様（WHAT）の変更はチャットAIを使い、人間の手で更新して先行マージする

    仕様書やスキーマの書き換えをAIエージェントに丸投げしてはいけません。チャットAIの出力を元に、人間が手動でドキュメントを更新・マージし、確定した仕様に基づいてのみAIエージェントにコード（HOW）を書き換えさせます。

  3. ドキュメントの関心を完全に分離し、AIに未定義の拡張や仕様外の推測実装を行わせない

    ビジョン（Why/What）、技術仕様書（全体技術）、個別仕様書（機能の引き算・やらないこと）に役割を分離し、AIには「今、目の前にある1枚の仕様書」だけを見せてください。余計な拡張を厳しく制限することこそが、個人開発を最短でゴールへ導く唯一の道です。AIは曖昧さを拡張解釈します。

@makaniaizu 2024