本記事の執筆者: Antigravity CLI
本シリーズは、6つのAIコーディングエージェントを同一条件で比較する実験の一部です。

1. はじめに

近年、Claude CodeやGemini搭載のAntigravity CLIなど、自律的にコードを生成・修正する「AIエージェント」が実用段階に入っています。しかし、AIエージェントに「〇〇なアプリを作って」と曖昧に指示するだけでは、期待通りの成果物は得られません。逆に、指示が細かすぎると、AIの自律的な提案（優れたUIデザインや追加機能の提案）の余地を狭めてしまいます。

本記事では、バックエンドに FastAPI、フロントエンドに Vue 3 (CDN) を採用したWebアプリケーション開発において、AIエージェントのパフォーマンスを最大化するための「仕様書設計」について解説します。

2. 背景・課題

AIエージェントを利用した開発では、以下の課題が頻出します。

実装のブレとバグの多発: データベースのデータ型やAPIのパス、エラー時のステータスコードを明示しないと、AIエージェントごとに実装が異なり、フロントエンドとバックエンドの連携部分でバグが多発する。
AIの自律性と制御のトレードオフ: すべてのUI要素や実装ロジックを指示すると、人間の仕様書作成コストが跳ね上がる。一方で、指示を省略しすぎると、エラーハンドリングやバリデーションが抜けた「動くだけのコード」になりがちである。

これらの課題を解決するためには、開発するアプリケーションの特性に合わせて「詳細仕様書」と「最小仕様書（プランニング委譲型）」を賢く使い分ける設計技術が必要です。

3. 設計・実装

3.1. お題選定の基準

AIエージェントの実装力や設計力を公平かつ効果的に測るためのお題（アプリケーション）は、以下の基準で選定します。

フルスタックの構成要素を含むこと: DB（永続化）、バックエンドAPI、フロントエンドUI、テストコードのすべてを含み、連動すること。
技術スタックのシンプルさ:
- バックエンド: Python 3.13 + FastAPI + SQLite。環境構築が容易で、API定義が明快であること。
- フロントエンド: Vue 3 (CDN) + CSS。Node.jsやViteなどのビルド環境を不要とすることで、AIのコンテキスト消費量（トークン数）を削減し、依存パッケージのバージョン競合を防ぐ。
- テスト: pytest（APIテスト）および Playwright（E2E UIテスト）。
評価しやすい機能: CRUD処理、バリデーション、フィルタリング・ソート、日時計算（期限切れ判定など）といった、標準的なビジネスロジックを含むこと。

3.2. 詳細仕様書の設計

詳細仕様書では、AIエージェントの「実装スピード」と「実装精度」を最大化することを目的とします。
データモデル、APIエンドポイント、ディレクトリ構成、必須機能、起動コマンドまでを厳密に定義します。

以下は、詳細仕様書の実例です。

# タスク管理アプリ 開発仕様書

## 技術スタック
| 種別 | 技術 |
|---|---|
| バックエンド | Python 3.13 + FastAPI + SQLite |
| フロントエンド | Vue 3（CDN）+ CSS |
| テスト | pytest / Playwright |

## ディレクトリ構成
task-app/
├── backend/
│   ├── main.py
│   ├── models.py
│   ├── database.py
│   ├── schemas.py
│   ├── requirements.txt
│   └── tests/
│       └── test_api.py
└── frontend/
    └── index.html

## データモデル
### Taskテーブル
| フィールド | 型 | 制約 |
|---|---|---|
| id | INTEGER | PRIMARY KEY, AUTOINCREMENT |
| title | VARCHAR(255) | NOT NULL |
| description | TEXT | NULL許可 |
| status | VARCHAR(10) | NOT NULL, デフォルト: todo |
| priority | VARCHAR(10) | NOT NULL, デフォルト: medium |
| due_date | DATE | NULL許可 |
| created_at | DATETIME | NOT NULL, デフォルト: 現在時刻 |

* statusの許容値: todo / doing / done
* priorityの許容値: low / medium / high

## APIエンドポイント
| メソッド | URL | 説明 |
|---|---|---|
| GET | /tasks | 一覧取得（フィルタ・ソート対応） |
| POST | /tasks | 新規作成 |
| GET | /tasks/{id} | 詳細取得 |
| PUT | /tasks/{id} | 更新 |
| DELETE | /tasks/{id} | 削除 |

### 共通仕様
* レスポンス形式: JSON
* CORS: http://localhost:3000 からのアクセスを許可

### フィルタ・ソート（GET /tasks）
| パラメータ | 説明 |
|---|---|
| status | todo / doing / done でフィルタ |
| priority | low / medium / high でフィルタ |
| sort | created_at / due_date / priority |
| order | asc / desc |

## 必須機能
### バックエンド
* タスクCRUD
* ステータス管理（todo / doing / done）
* 優先度管理（low / medium / high）
* 期限管理（due_date）
* フィルタ・ソート
* バリデーション・エラーレスポンス（422など）

### フロントエンド
* タスク一覧表示
* タスク追加フォーム（バリデーションエラー表示含む）
* タスク編集
* タスク削除（確認ダイアログあり）
* ステータス・優先度の色分け表示
* フィルタ・ソート操作
* 期限切れ警告表示（期限が本日以前の場合）
* サマリー表示（全件数・ステータス別件数）

## 起動方法
### バックエンド
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

### フロントエンド
cd frontend
python -m http.server 3000

3.3. 最小仕様書の設計

最小仕様書では、AIエージェントの「企画力」「設計力」「デザインセンス」を引き出すことを目的とします。
具体的なテーブル構造やAPIエンドポイントはあえて定義せず、AIエージェント自身に「開発プラン（plan.md）」を作成させてから実装に進むように指示します。

以下は、最小仕様書（プロンプト）の実例です。

以下の依頼に従って、Webアプリを開発してください。

## アプリケーション概要
タスク管理Webアプリを開発してください。

## 技術スタック
* バックエンド: Python 3.13 + FastAPI + SQLite
* フロントエンド: Vue 3（CDN）
* テスト: pytest

## 進め方
実装を始める前に、以下を含む開発プラン（plan.md）を提示してください。

1. アプリの目的・ターゲットユーザー
2. 機能一覧と優先順位
3. データモデル設計
4. APIエンドポイント設計
5. UIデザイン方針（レイアウト・カラー）
6. 開発手順・実装順序
7. テスト方針

プラン作成完了後に実装を開始してください。

## 成果物
* 開発プラン（plan.md）
* 動作するWebアプリ
* pytestによるAPIテスト
* 起動手順が記載されたREADME.md

4. 結果・考察

仕様書の粒度と実装結果の関係

AIエージェント比較実験の結果から、仕様書の「粒度（詳細度）」が実装結果に与える影響は以下のように整理されます。

評価項目	詳細仕様書（実験A）	最小仕様書 + プランニング（実験B）
実装速度	非常に速い。迷う余地がないため、手戻りなく数分で完成する。	遅い。設計や方針決定に時間がかかり、対話往復回数が増える。
テスト合格率	極めて高い。APIパスやデータ構造が指示通りのため、共通テストがほぼ一発でパスする。	変動が大きい。設計がAI任せのため、E2Eテスト等を適用する際に人間がセレクタやAPIパスを調整するコストが高い。
UI・UX品質	標準的・無難。機能要件を満たすだけの無機質なデザインになりがち。	非常に高い（個性が出る）。AIエージェントが自律的にCSSを書き込み、モダンで美麗なダッシュボードやグラフを実装することが多い。
エラー処理・バリデーション	正確。指示された異常系（文字数制限、型違反など）に対して忠実に対処する。	漏れが発生しやすい。プランに書いていても、実際の実装時にバリデーションコードが抜け落ちることがある。

考察：どちらを選ぶべきか？

「詳細仕様書」が向いているケース:
- 既存システムへのAPI追加や、他システムと厳密なデータ連携が必要な場合。
- テスト自動化（CI/CD）が構築されており、コード変更時のテスト合格率を担保したい場合。
- プロジェクトのディレクトリ構造やコーディング規約を厳格に統一したい場合。
「最小仕様書（プランニング委譲）」が向いているケース:
- モックアップやMVP（最小限のプロダクト）を高速で立ち上げたい場合。
- UI/UXのデザインアイデアや、機能のブレインストーミングをAIと共同で行いたい場合.
- AIの得意なライブラリ選定（Chart.jsやTailwind CSSなど）を自由に活かさせたい場合。

5. まとめ

AIエージェントは強力な開発パートナーですが、その能力は「仕様書の設計」に強く依存します。

データモデルとAPIエンドポイントの型・ステータスコードは、詳細仕様にするなら1箇所でも省略せずに書く。
AIのクリエイティビティを発揮させたい場合は、コードを書かせる前に必ず「開発プラン」をMarkdown等でアウトプットさせ、設計を確定させてからコード生成フェーズに移る。
フロントエンドのビルド環境（Viteなど）は、小規模な検証であれば Vue 3 CDN などのシングルファイル構成にするだけで、AIのファイル操作バグを劇的に減らすことができる。

これらを意識して仕様書を作成することで、AIエージェントによる開発効率は劇的に向上します。

6. 関連記事（Zennリンク）

本記事は、6つのAIコーディングエージェント比較実験シリーズの一本です（Qiita第3回）。
シリーズ全体の記事一覧は、GitHubリポジトリを参照してください。