0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@pekopugu

【AIエージェント比較実験】#03 AIエージェントに最高のコードを書かせる「FastAPI + Vue 3 仕様書」の設計技術

0
Last updated at Posted at 2026-06-29

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

1. はじめに

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

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

2. 背景・課題

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

  1. 実装のブレとバグの多発: データベースのデータ型やAPIのパス、エラー時のステータスコードを明示しないと、AIエージェントごとに実装が異なり、フロントエンドとバックエンドの連携部分でバグが多発する。
  2. 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エージェントは強力な開発パートナーですが、その能力は「仕様書の設計」に強く依存します。

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

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

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

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

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?