Spec-Driven Development

生成AI × マルチエージェントアーキテクチャ

Project: CalcioA Unity移植（Cocos2d-x → Unity）
Agents: 24種類の専門エージェント
Architecture: 自己修復型ワークフロー（検出 → 修正 → 再検出ループ）

自己修復型開発フロー

背景：従来の開発の課題

通常のソフトウェア開発では、仕様書（設計書）は一度書いたら更新されず、実装との間に差分が生まれるという問題がありました。これにより、「仕様書に書いていない機能」や「実装漏れ」が発生します。

解決策：AIエージェントによる自動検証

本プロジェクトでは、仕様書を「検証の基準」として位置づけ、24種類の専門AI（エージェント）が自律的に仕様漏れを検出・修正するループを構築しています。

エージェントとは？: 特定の役割を持つAIプログラム。例えば「仕様書とソースコードの差分を検出する専門AI」のように、それぞれが明確な責務を持ちます。

産業規模の移植における課題

課題	従来の対処	本プロジェクトの解決策
仕様書の不在	人間が手動で要件定義書を作成	AIが既存ソースコードから自動的に機能一覧を抽出
仕様漏れ	人間がレビューで発見	AIが元のコードと仕様書の差分を自動検出
手戻り	人間が手動で修正	AIが不足している仕様を自動で仕様書に追加
品質保証	人間が手動でテスト	自動テスト作成 + AIによる画面検証

マルチエージェントアーキテクチャ（24種）

なぜ24種類ものAIが必要なのか？

生成AIには以下の限界があります：

コンテキスト制限: 一度に処理できる情報量に上限がある
局所的理解: システム全体を同時に把握することが困難

これを克服するため、役割を細分化し、24種類の専門AIエージェントが協調動作する仕組みを構築しました。

人間の組織に例えると、「設計チーム」「テストチーム」「修正チーム」のように役割分担しているイメージです。

CalcioA Multi-Agent Architecture - 24 Agents

エージェント構成

役割	数	代表例	責務
指揮役（Orchestrator）	6	`spec-migration-checker`	検出→修正ループの制御
検出役（Detector）	4	`spec-migration-detector`	ソースコードとspec.mdの差分検出
修正役（Fixer）	4	`spec-migration-fixer`	不足FRをspec.mdに自動追加
実装役（Implementer）	6	`impl-test-writer`, `impl-code-writer`	TDDサイクル実行

オーケストレーターパターン

各checkerエージェントは、検出→修正→再検出を100%カバレッジ達成まで繰り返すループを自律的に実行します。

自己修復型ループ：Spec-Loop

「自己修復」とは？

このシステムの最大の特徴は、AIが自分で問題を見つけて、自分で直すことです。

仕様検証ループの動作：

AIが元のソースコードを分析
仕様書に書かれていない機能を自動検出
仕様書に不足項目を自動追加
再度確認（100%になるまで繰り返す）

このループにより、手動レビューでは見逃されがちな仕様漏れを機械的に検出・修正できます。

実績（001-title-graphics）

繰り返し回数	網羅率（カバレッジ）	未実装の機能数	結果
1回目	88.6%	3件	不足している機能要件を発見
2回目	100%	0件	✅ すべての機能を網羅

効果: 人間がソースコードを読み込んで要件を抽出する必要がなく、AIが自律的に仕様書を完成させる。

TDD-Loop：実装品質保証

TDD（テスト駆動開発）とは？

TDD (Test-Driven Development) は、「先にテストを書いてから、コードを書く」という開発手法です。

通常の開発：コードを書く → テストを書く
TDD：テストを書く → コードを書く

こうすることで、「テストされていないコード」が生まれることを防ぎます。

本プロジェクトでは、AIに対して**「テストなしの実装は絶対に禁止」というルール（憲法）**を設定し、AIがこれを逸脱できないようにしています。

TDDサイクル

Red Phase（レッド）: まず「失敗するテスト」を作成
Verify (Fail): そのテストがちゃんと失敗することを確認（重要！）
Green Phase（グリーン）: テストを通すための最小限のコードを実装
Verify (Pass): すべてのテストが成功することを確認

重要: Verify (Fail)ステップをスキップさせない厳格性が、品質保証の鍵です。

3層ドキュメント構造（Spec Kit）

各機能は、以下の3つのドキュメントで段階的に詳細化されます。

.specify/
├── spec.md     # 要件定義（何を作るか）
├── plan.md     # 設計書（どう作るか）
└── tasks.md    # タスクリスト（具体的作業）

ドキュメント	内容	検証エージェント
spec.md	機能要件(FR), 成功条件(SC)	`spec-migration-checker`
plan.md	アーキテクチャ設計, API設計	`plan-migration-checker`
tasks.md	具体的タスク, 依存関係	`task-migration-checker`

それぞれのドキュメントに対して、専用の検証ループが存在します。

スキル：AIの効率化テクニック

問題：大量の情報を読み込むとAIが遅くなる

機能一覧ドキュメント（8,058行）をすべて読み込むと、AIの処理能力の30%を消費してしまいます。

解決策：「スキル」による必要な情報だけの読み込み

人間が辞書を使うように、AIも「必要な時に、必要な部分だけ」参照する仕組みを構築しました。これを**「スキル」**と呼んでいます。

スキル名	用途	削減効果
feature-inventory	機能一覧の効率的検索	85-90%削減
tdd-workflow	テスト実行手順	-
screenshot-verification	VLM画面検証手順	-
migration-validation	仕様整合性検証パターン	-

例: python3 .claude/skills/feature-inventory/scripts/search.py "Match System" → 関連部分のみ500-800行で返却

VLM検証：Screenshot-Loop

VLM（画像認識AI）による自動UI検証

VLM (Vision Language Model) は、画像を見て内容を理解できるAIです。

本プロジェクトでは、UIの実装後に：

自動的にスクリーンショットを撮影
VLMが画像を分析
「タイトルが中央に配置されているか」などを自動チェック

これにより、人間が目視で確認する作業を自動化しています。

フロー

PlayModeテストでスクリーンショット撮影
screenshot-verifierエージェントが画像を分析
期待される表示と実際の表示を比較
問題があれば修正を提案

検出実績

✅ タイトルロゴが右上に寄っている問題を自動検出
✅ 背景が右半分だけに表示される問題を自動検出

憲法（Constitution）：絶対ルール

.specify/memory/constitution.mdで絶対に守るべきルールを定義し、すべてのエージェントがこれに従います。

主要ルール

Test-First Development - 全機能にテスト必須
Test Verification - テスト合格まで完了とみなさない
FEATURE_INVENTORY.md Reference - 全specは元ドキュメント参照
2-Try Limit - 2回失敗したらユーザーに報告

実績と効果

Phase 1での学び

問題: SS6アニメーションの仕様漏れによる手戻り

対策:

spec-migration-checkerによる自動検証導入
100%カバレッジ達成まで繰り返すループ設計

結果: 2イテレーションで仕様書完成、手戻りゼロ

知識の蓄積と再利用

座標変換問題で人間の介入が必要だったが、その知見をdocs/cocos-unity-mapping.mdに記録。次回以降はAIが自動対応可能に。

学習サイクル: 問題発生 → 人間が解決 → ドキュメント化 → 次回から自動化

まとめ：本アプローチの特徴

特徴	詳細
自己修復型ワークフロー	検出→修正→再検出のループにより、仕様漏れを自動で発見・修正
24種の専門エージェント	役割の細分化により、複雑なタスクを高精度で実行
VLMによるUI検証	スクリーンショットを自動分析し、人間の目視確認を代替
知識の蓄積と再利用	問題解決のたびにドキュメントを更新し、次回から自動対応可能に
コンテキスト効率化	スキルによるオンデマンド読込で、AIの処理能力を最大化
厳格なTDD	憲法で強制され、品質保証を担保

これらの手法により、産業規模の移植プロジェクトを生成AIで自律的に遂行する基盤を確立しました。