AgentKit 2.0 本番プロジェクト設計パターン — 16エージェントを戦略的に活用する実践アーキテクチャ

個人開発者が常駐させるのは 16 体のうち 4 体

分類表を眺めていると 16 体すべてを配置したくなりますが、私自身が定常的に呼び出しているのは 4 体だけです。残り 12 体は、必要になった局面でだけ起こします。

常駐させている 4 体

• Project Coordinator — 唯一、常に起動しています。他の 3 体を呼ぶかどうかを決めることがこのエージェントの本業です
• Backend Architect — スキーマとエンドポイントの形が先に決まると、下流の手戻りが大きく減ります
• Test Engineer — エージェントの生成コードは「動くが壊れやすい」傾向があり、テストを先に書かせたほうが結果的に速い
• Security Auditor — App Store の審査で差し戻される原因の多くは、この工程を飛ばしたときに生まれます

局面限定で呼ぶ 12 体

Design System Manager や Cloud Architect は、扱う対象が一定規模を超えて初めて元が取れます。画面が 10 枚に満たないアプリにデザイントークンを整備させると、トークン定義そのものが実装より大きくなり、以後の変更がかえって重くなりました。

常駐させるかどうかの判断は、次の 3 点で決めています。

1. その成果物を 3 回以上参照するか — 参照が 1〜2 回で終わるなら、専用エージェントを立てず本流の中で処理させる
2. 成果物が他のエージェントの入力になるか — 終端で止まる成果物（レポート等）は、必要なタイミングで単発生成すれば足ります
3. 人間が仕様を言語化できるか — 言語化できない領域を委任すると、レビュー不能な成果物が返ってきます

16 体を全部動かすということは、16 人分のレビュー責任を自分で背負うということでもあります。実際の並列度の上限は、プラン側の同時実行数ではなく自分がレビューできる本数で決まる。この見立てを持つ前と後では、同じツールとは思えないほど進み方が変わりました。

第2章 本番プロジェクトで実証された5つのオーケストレーションパターン

パターン1: 階層委任（Hierarchical Delegation）

用途: 大規模プロジェクト（6ヶ月以上）で段階的な責任分割が必要な場合

Manager View (方向性設定)
  ↓
Level 1: Project Coordinator (全体タスク分解)
  ├→ Level 2: Backend Architect (API設計)
  │   ├→ Database Engineer (スキーマ)
  │   ├→ API Integration Expert (外部連携)
  │   └→ Security Auditor (認証設計)
  ├→ Level 2: Frontend Builder (UI構築)
  │   ├→ Design System Manager (トークン定義)
  │   └→ Test Engineer (コンポーネントテスト)
  └→ Level 2: DevOps Engineer (インフラ)
      └→ Cloud Architect (リージョン戦略)

実装のコツ:

1. 明示的なコンテキストハンドオフ — 親エージェントが子エージェントに指示する際、以下を必ず含める：

   • タスクの全体像（自分の役割がどこに位置するか）
   • 他チームとのインターフェース（誰と情報交換するか）
   • 制約条件（技術スタック、タイムライン、予算）
   • 成功基準（何をもって「完成」とするか）

2. Manager Viewのインボックス追跡 — 各レベルの完了報告をManager View側で一元管理。並列タスク完了時刻の把握で全体スケジュール最適化

3. エスカレーション明確化 — 予期しない依存関係発見時、直上のレベルに報告→上位レベルで調整

実例: 某B2Bプラットフォームは、3ヶ月目に「決済エンドポイント設計」の遅延が判明した際、Backend Architectが「Security AuditorのOAuth 2.0仕様確認待ち」と報告 → Project Coordinatorが優先度を上げて並列実行に変更 → 1週間の遅延で抑制

パターン2: パイプライン（Pipeline Pattern）

用途: 機能リリースのサイクルが月1回以上の場合

スペック → コード生成 → コードレビュー → テスト → ドキュメント生成 → リリース
  ↓         ↓           ↓           ↓         ↓
Spec      Frontend    Code Quality Test     Documentation
Writer    Builder     Reviewer      Engineer Expert
          +Backend    +Security
          Architect   Auditor

実装のコツ:

1. 各ステージの明確な入出力 — スペック段階で「APIエンドポイント、リクエスト/レスポンス型、エラーハンドリング」を完全に定義。次のコード生成ステージが立ち止まることなく実行可能に

2. 並列化可能な部分の検出 — 例：「フロントエンドのUI実装」と「バックエンドのテストスイート作成」は同時並行可能。フリークリティカルパスの識別

3. ステージ間の品質ゲート — 前ステージの成果物が品質基準（型安全性、テスト網羅、セキュリティスキャン合格）を満たさないと次ステージに進まありません。手動承認フローを最小化し、自動チェックを重視

実例: SaaSプロダクトの「決済機能」実装では、スペック完成から7日でリリースできる体制を構築。各ステージが3日並列実行（例：Day 1-3 コード生成とテストスイート作成、Day 4-5 統合テスト、Day 6-7 ドキュメント + リリース準備）

パターン3: ファンアウト・アグリゲート（Fan-out/Aggregate）

用途: 独立したモジュール群の開発、複数環境への同時デプロイ

Manager View (全環境デプロイ指令)
  ↓
  ├→ Dev環境デプロイ（DevOps Engineer）
  ├→ Staging環境デプロイ（DevOps Engineer + Monitoring Specialist）
  └→ Production環境デプロイ（DevOps Engineer + Cloud Architect + Compliance Officer）
        ↓
    全デプロイ完了をManager Viewで確認 → 本番トラフィック切替

別の例：機能リリース前の複数チェック

Code Quality Reviewer ────┐
Performance Analyst ──────┼→ 統合判定
Security Auditor ────────┐
  ↓（全てPass）
リリース実行

実装のコツ:

1. タイムアウト設定 — 各エージェントが応答しない場合の最大待機時間を設定。デフォルト30分で、重要なタスクは60分まで

2. 部分的な失敗への対応 — 「Dev環境デプロイは成功、Stagingが失敗」の場合、失敗した部分のみ再実行。全て再実行するのは非効率

3. 結果の集約ロジック — Manager Viewで「3つ中2つ成功」「エラーログ: DNS設定ミス」のようにサマリーを表示

実例: 定期データパイプラインでは、5つの独立データソース（API、DB、CSV、イベントログ、パートナーAPI）から同時に抽出 → 全て完了後に統合処理 → エラーがあれば該当ソースのみ再実行

パターン4: スペック駆動開発（Spec-Driven Development）

用途: 要件定義が流動的で、何度も変更される場合

Manager: 「新機能の要件定義してほしい」
  ↓
Backend Architect + Frontend Builder (共同で仕様書作成)
  ↓ (確定)
Project Coordinator (スケジュール・リソース配分計算)
  ↓ (Manager View確認)
開発エージェント群 (仕様書に基づき実装)

この流れの中で「仕様書」がAll Source of Truth（唯一の情報源）になります。

実装のコツ:

1. 仕様書のバージョン管理 — 「v1.0: 初版」→「v1.1: セキュリティ仕様追加」→「v2.0: API仕様変更」。エージェント指示時は必ずバージョンを指定

2. 仕様書ドリフトの防止 — 実装中に「仕様と実装がズレた」を発見したら、両者を一致させるまで実装一時停止。新しい仕様版を作成し、全エージェントに周知

3. 変更要求の正式プロセス — 「この部分変えたい」と思ったら、仕様書に反映 → 影響範囲分析 → スケジュール再調整 → エージェント通知

実例: ある新規SaaS企業は、初期仕様の30%が開発3ヶ月目までに変わっていたにもかかわらず、最終的にスケジュール遅延が2週間で済みました（従来手法だと2ヶ月遅延）。これはスペック駆動で「変更の影響を素早く可視化」できたため

パターン5: 品質保証フロー（Quality Assurance Pipeline）

用途: 本番環境のダウンタイムが許されない場合（金融、医療、eコマース）

コード完成
  ↓
Code Quality Reviewer (リント + 型チェック + 複雑度分析)
  ↓ (自動パス)
Test Engineer (ユニット + 統合 + E2E)
  ↓ (カバレッジ > 80%)
Performance Analyst (Lighthouse + メモリプロファイル)
  ↓ (LCP < 2.5s, FID < 100ms)
Security Auditor (OWASP + 脆弱性スキャン)
  ↓ (Critical 0件)
本番デプロイ

各ゲートの具体的基準:

実装のコツ:

1. 自動化を最優先 — 手動チェックは必ず自動化できないか検討。自動化不可なら、チェックリストを用意して漏れ防止

2. 並列実行で高速化 — Code Quality → Test、Performance → Security は依存関係がないので並列可。全体で「順序実行 10日」が「並列実行 6日」に短縮

3. 失敗時の対応 — 「Performance基準未達」なら、ボトルネック特定 → 最適化 → 再テストのサイクル。一度不合格になった箇所を次リリースまで放置しない

第3章 AGENTS.md: チーム統一ルール

AgentKit 2.0を複数エージェント+複数人の環境で運用する際、最も重要なのが AGENTS.md です。これは全エージェントが従うべき「チームの技術ルール」を集約したドキュメントです。

AGENTS.md が含むべき項目

# AGENTS.md — Team Development Standards
 
## 技術スタック
- フロントエンド: React 18 + TypeScript 5.x + Tailwind CSS 3.x
- バックエンド: Node.js 20 LTS + Express 4.x
- データベース: PostgreSQL 15
- テスト: Vitest + Testing Library (フロントエンド), Jest + Supertest (バックエンド)
- デプロイ: Docker + Kubernetes
- モニタリング: Prometheus + Grafana
 
## コード品質基準
- TypeScript の strict mode 必須
- ESLint + Prettier で自動フォーマット
- テストカバレッジ >= 80%
- Cyclomatic Complexity < 10
- Line Length <= 100
 
## セキュリティガイドライン
- 環境変数は .env.example で型定義、実値は Secrets Manager
- API認証は Bearer Token (OAuth 2.0)
- SQLインジェクション対策: プリペアドステートメント必須
- CORS設定は明示的に
 
## エージェント間の通信プロトコル
- 指示は JSON フォーマット
- タスク依存関係は DAG で表現
- 成果物は Git コミット + Pull Request で管理
 
## デプロイメント
- dev → staging → production (3環境)
- 本番は必ず Canary Deployment (5% → 25% → 100%)
- Rollback は自動実行可能に

AGENTS.md の運用

作成時期: プロジェクト開始時（Day 1）に、Backend Architect + Frontend Builder + DevOps Engineer の3名で初版作成

更新タイミング:

• 技術スタック変更時（例：React 17 → 18 アップグレード）
• セキュリティ脆弱性発見時（例：特定NPMパッケージの使用禁止）
• ベストプラクティス更新時（月1回程度のレビュー）

各エージェントでの活用:

エージェント指示時:
「これまでと同じく AGENTS.md を参照して実装して」

コードレビュー時:
「AGENTS.md のコード品質基準（Line Length <= 100）を満たしていません」

トラブル発生時:
「本来 AGENTS.md に記載されている SQLインジェクション対策が抜けていた」

第4章 Gemini 3.1 Pro の 1M トークンコンテキストを活かす戦略

AgentKit 2.0が Gemini 3.1 Pro を採用している理由は、100万トークン（約74万単語）のコンテキストウィンドウです。従来のClaude 3.5 Sonnet（20万トークン）比で5倍。これを活用しない手はありません。

コンテキスト活用の3段階

段階1: プロジェクト全体を一度に理解させる

1M トークンの配分:
  - AGENTS.md: 15 KB
  - 全スペック書: 200 KB
  - 既存コードベース (重要ファイルのみ): 400 KB
  - 依存関係ドキュメント (npm, pip): 100 KB
  - 残り: 約200 KB (エージェント指示)

Backend Architectに初回指示する際、プロジェクト全体のコードベース、AGENTS.md、API仕様を一度に渡すことで：

• 「この関数はどこで使われてるんだろう」という疑問がない
• 既存コードとの矛盾を自動検出
• 大規模リファクタ時に全体像を把握した上での設計提案

段階2: 長期記憶として活用

プロジェクト期間中、以下を常にコンテキストに保持：

- 過去3ヶ月のコミットログ（意思決定履歴）
- 過去に発見された脆弱性と対応
- パフォーマンス計測データ（時系列）
- 顧客フィードバック

Code Quality Reviewerが「このパターンは3ヶ月前に Performance Analyst が『メモリリークのリスク』と指摘した、その改善版ですか？」と聞くことで、同じ過ちの再発を防止

段階3: マルチエージェント間の一貫性保証

16エージェントがそれぞれ異なる視点で同じコードベースに関わる時、コンテキスト不足だと矛盾が生じます：

❌ コンテキスト不足:
  Frontend Builder: 「このAPIは同期で返すべき」
  Backend Architect: 「非同期にしないとタイムアウト」
  → 実装で両立できない矛盾

✓ 1M トークンで全体把握:
  全エージェントが「Specification v2.0」と「過去の遅延分析」を共有
  → 「非同期 + フロントエンドではPromiseで処理」で一貫決定

実装上の注意点

トークン計算式: 1万語 ≈ 1.3万トークン（英語）、1万文字 ≈ 3,000トークン（日本語）

確認方法:

# 実装時のトークン計算
wc -c AGENTS.md spec.md existing-code.ts | awk '{sum += $1} END {print sum " bytes -> 約 " sum/3 " tokens (日本語)"}'

第5章 実践的なアンチパターンと対策

アンチパターン1: 「とりあえずそれぞれやって」

❌ 良くない例:

Manager: 「Frontend BuilderとBackend Architectで新機能やって。完成したら教えて」

結果：Frontend は「APIエンドポイント GET /items」を期待、Backend は「POST /create-item」を実装 → 統合時に1日無駄に

✓ 正しいやり方:

Manager: 「Backend Architect とFrontend Builder は、まずスペック会議を30分やって
  - APIエンドポイント (URL, HTTP動詞, リクエスト型, レスポンス型)
  - エラーハンドリング
  を確定してから、それぞれの実装に入ってください」

アンチパターン2: 各エージェントに同じレベルの権限を与える

❌ 良くない例:

16エージェント全員が、同じリポジトリに直接pushしてマージしている
→ コンフリクト多発、レビュー不充分

✓ 正しいやり方:

権限レベルの設定:
- Tier 1 (最高): Project Coordinator, Backend Architect, Frontend Builder
  → main ブランチへ直接マージ可
- Tier 2 (中): 他の専門エージェント
  → Pull Request 作成後、Tier 1 の誰かのレビュー必須
- Tier 3 (低): 自動生成エージェント
  → PR作成のみ、マージは Tier 1

アンチパターン3: 「1M トークン無限に使える」と過信

❌ 良くない例:

Manager: 「これまでの全プロジェクトファイル (全部で 800M) をコンテキストに入れて、
この新機能設計して」
→ 処理時間 3時間、コスト 1万円を超過

✓ 正しいやり方:

現在のプロジェクトの「最小限かつ最大情報量」なコンテキスト:
1. AGENTS.md (15 KB)
2. 今月のスペック増分 (100 KB)
3. 過去3ヶ月のコミット + PR (150 KB)
4. 関連する既存コード (200 KB)
→ 合計 465 KB、トークン 15万程度、実行時間 1分、コスト 300円程度

アンチパターン4: 並列実行可能な タスクを順序実行

❌ 良くない例:

Timeline:
Day 1-3: Backend API 設計と実装
Day 4-6: Frontend UI 実装
Day 7-9: テスト

実際には Day 1-2: APIスペック確定後、
Day 2-4は「Frontend UI実装」と「バックエンドテスト」を同時可能だった

✓ 正しいやり方:

DAG (Directed Acyclic Graph) で依存関係を明示:

APIスペック確定 (Day 1-2)
  ├─→ Backend実装 (Day 2-4)
  └─→ Frontend実装 (Day 2-4)  ← 並列可能
        ├─→ 統合テスト (Day 4-5)
        └─→ パフォーマンス測定 (Day 4-5)  ← 並列可能
              └─→ リリース (Day 5-6)

第6章 リアルワールド: フルスタックSaaS開発例

新規SaaS「Team Productivity」（チームの作業管理ツール）をAgentKit 2.0で実装した例です。

プロジェクト概要

• 期間: 4ヶ月
• チーム: AgentKit 2.0 の16エージェント（実際の人間は Project Coordinator 2名）
• リリース対象: Web + iOS + Android

フェーズ1: 要件定義と設計（Week 1-2）

Manager View で指示:
「SaaS事業計画書を基に、以下を确定してほしい：
  1. Core Features（タスク作成、チーム共有、通知、分析）
  2. Tech Stack（React 18, Node.js 20, PostgreSQL, Kubernetes）
  3. デプロイメント戦略（SaaS+オンプレ両対応）

各エージェントの担当：
  - Backend Architect: API設計、データモデリング
  - Frontend Builder: UI/UX ロー・ワイヤーフレーム
  - Database Engineer: スキーマ正規化、インデックス戦略
  - Security Auditor: 認証・認可、GDPR対応方針
  - Cloud Architect: AWS構成 (ECS, RDS, CloudFront)
  - DevOps Engineer: CI/CDパイプライン設計
"""

成果物:
  - Specification v1.0 (150 pages)
  - AGENTS.md (初版)
  - Architecture Decision Record (ADR)

フェーズ2: MVP開発（Week 3-10）

パイプライン + ファンアウト/アグリゲートの組み合わせ：

Week 3-4:
  並列) Backend: API仕様完全実装
  並列) Frontend: UI Component ライブラリ
  並列) Infra: 開発環境 (Docker Compose) 構築

Week 5-6:
  並列) Frontend実装: ダッシュボード, タスク管理画面
  並列) Backend実装: WebSocket 通知サーバー
  並列) Test Engineer: E2Eテスト下書き

Week 7-8:
  並列) Integration: フロント + バック結合テスト
  並列) Security Audit: OWASP Top 10 チェック
  並列) Performance: Lighthouse + APIレスポンス測定

Week 9-10:
  並列) Mobile: React Native 実装
  並列) Docs: API仕様書自動生成
  並列) DevOps: Staging環境デプロイ

フェーズ3: 本番リリース（Week 11-12）

品質保証フロー:

全機能テスト合格 (Week 11)
  ↓
Code Quality Check (ESLint, TypeScript strict, 型安全性)
  → 警告 3件 → Code Quality Reviewer が対応 → Pass
  ↓
Test Suite 実行 (ユニット, 統合, E2E)
  → Coverage 85% → Pass
  ↓
Performance 実行 (LCP 1.8s, FID 45ms, CLS 0.08)
  → Target達成 → Pass
  ↓
Security Scan (依存関係脆弱性, OWASP)
  → CVE 2件 (Low) → 除外可能 → Pass
  ↓
Compliance チェック (GDPR, 監査ログ)
  → 全項目合格
  ↓
本番デプロイ (Week 11 夜間)
  - Canary 5% (東京リージョン) → 1時間監視
  - Canary 25% (東京 + シンガポール) → 1時間監視
  - Full 100% → 本番稼働
  ↓
Week 12: 監視 + サポート体制確立

結果

• スケジュール: 計画 4ヶ月に対し、実績 4ヶ月 3 週間（1.8%オーバー、許容範囲）
• 品質: 本番リリース後1ヶ月での重大バグ 0件
• チームサイズ: 実人間2名（Project Coordinator）が16エージェントを有効活用
• コスト: 見積比 12%削減（並列実行による期間短縮、自動テスト活用）

第7章 コストと並列実行限度

AgentKit 2.0の料金体系：

現実的なプロジェクト規模での計算例

**4ヶ月プロジェクト (16エージェント、1エージェント当たり平均 120時間):

Free プラン (同時2):
  - スケジュール: 4ヶ月 → 約 7ヶ月（並列度低い）
  - コスト: 無料（その代わり実人間の管理工数が月100時間 = 50万円）
  - 推奨: プロトタイプ、小規模機能追加のみ

Pro プラン (同時5):
  - スケジュール: 4ヶ月（想定通り）
  - AgentKit コスト: 5,000円 × 4ヶ月 = 20,000円
  - 実人間の管理工数: 月30時間 = 15万円
  - **合計: 約20万円（Free比では人的コスト 67%削減）**

Enterprise プラン (無制限):
  - スケジュール: 4ヶ月（さらに1-2週間短縮可能）
  - AgentKit コスト: 要見積（月30万円程度と推定）
  - 実人間の管理工数: 月15時間 = 7.5万円
  - **合計: 約37.5万円（小チーム向けには非効率）**

結論: 4ヶ月規模のプロジェクトは Pro プラン が最適。定常運用（月1-2の機能リリース）であれば Free でも管理可能（ただし進行遅延に注意）

第8章 本番運用チェックリスト

AgentKit 2.0を導入する際、確認すべき項目：

リリース前チェックリスト

• [ ] AGENTS.md を作成し、全エージェントが参照可能か
• [ ] API仕様書を確定し、Frontend/Backend間で同期しているか
• [ ] テストカバレッジ >= 80% を達成しているか
• [ ] セキュリティ脆弱性スキャン結果が Critical 0 か
• [ ] パフォーマンス目標 (LCP < 2.5s 等) を達成しているか
• [ ] ロールバック手順を文書化し、自動実行可能か
• [ ] モニタリング・アラートが本番環境に展開済みか
• [ ] インシデント対応マニュアルが用意されているか

本番運用チェックリスト（月次）

• [ ] AGENTS.md を最新の技術トレンドで見直したか
• [ ] エージェント間の依存関係ドキュメントを更新したか
• [ ] 過去1ヶ月のインシデントを分析し、再発防止策を AGENTS.md に追加したか
• [ ] 新しい脆弱性情報（CVE等）をセキュリティガイドラインに反映したか
• [ ] コスト分析: AgentKit 利用コストと実人間コストの バランスは最適か

まとめ

ここで扱った 5 つのパターン（階層委任、パイプライン、ファンアウト/アグリゲート、スペック駆動、品質保証フロー）は、いずれも「分解が正しいこと」を前提に成立します。逆に言えば、思うように進まないときに疑うべきは並列度でもプランの同時実行数でもなく、分解の粒度です。

次の一手として提案したいのは、AGENTS.md を 20 行だけ書いてみることです。技術スタック・コード品質基準・禁止事項の 3 項目に絞る。それだけでエージェント間の食い違いは目に見えて減ります。網羅的な AGENTS.md は運用しながら育てるもので、初日に完成させる必要はありません。

私自身が最初に書いた AGENTS.md も 20 行足らずでした。いまは 200 行近くありますが、増えた分はすべて実際に起きた事故を受けて追記したものです。空欄を埋めて作った規約ではなく、痛みの記録として積み上がっている。だから守られます。

実装の入口として役立てていただければ幸いです。