TL;DR

Claude Codeの上に140体のAIエージェントを載せ、4つの取締役会・18の組織・憲法・安全停止権限を持つ自律型マルチエージェントシステムを構築した。367のテスト、135K行のPython、実際に動く。この記事では設計思想・技術的な選択・盛大な失敗を包み隠さず書く。

なぜ140体も必要なのか

ChatGPTやClaudeを1体で使っているうちに気づいた：AIは「何でもできる1人」より「専門家チーム」の方が圧倒的に品質が高い。

セキュリティレビュー、記事執筆、動画制作、コードレビュー、税務処理 — これを1つのプロンプトに押し込むと、全てが中途半端になる。人間の組織と同じで、専門分化 + ガバナンスが品質の鍵だ。

Operator (人間) — 最終決定権
    |
Secretary (/ask) — 意図解釈 → ルーティング
    |
4 Domain Boards — 各Chairman が戦略判断
    |
    ├── App Board ──→ Product(10), Design(6), Operations(6), Security(6), LLM(8)
    ├── Game Board → Game Design(4), Engineering(3), Creative(3)
    ├── Content Board → Content(6), Revenue(11), Marketing(6), Creative(13), Education(7)
    └── Shared Board → Backoffice(7), Research(7), Oracle(3), Autonomous(8), User Testing(21)

合計: 135 org agents + 5 Holdings = 140体

この構造は「かっこいいから」ではない。実際に専門エージェントが出す結果が、汎用エージェントより明確に上だったから到達した設計だ。

アーキテクチャ: Protocol-Driven Composition

AEGISのエンジン層(98K LOC)は、Protocol + Composition + DIパターンで設計されている。これは「継承地獄」を避けるための戦略的選択だ。

なぜProtocolなのか

# ❌ 継承ベース (やってはいけない)
class BaseAgent(ABC):
    @abstractmethod
    def execute(self): ...

class SecurityAgent(BaseAgent):  # 継承
    def execute(self): ...

class SecurityPentester(SecurityAgent):  # 多段継承 → 地獄
    def execute(self): ...

# ✅ AEGISの実際のパターン: Protocol + Composition
from typing import Protocol

class WorkflowEngineProtocol(Protocol):
    """インターフェース定義のみ — 実装は自由"""
    def execute_workflow(self, workflow_id: str, context: dict) -> dict: ...
    def get_status(self, execution_id: str) -> dict: ...

class LangGraphEngine:
    """Protocol準拠の実装A"""
    def execute_workflow(self, workflow_id, context):
        return self._langgraph_execute(workflow_id, context)

class NativeEngine:
    """Protocol準拠の実装B — LangGraph不要"""
    def execute_workflow(self, workflow_id, context):
        return self._native_execute(workflow_id, context)

# DIで注入 — 実行時に切り替え可能
container.register(WorkflowEngineProtocol, NativeEngine, Lifetime.SINGLETON)

この設計の利点: テスト時にモックが簡単。外部依存をProtocolで抽象化しているので、LLMなしでもパイプライン全体をテストできる。

3つのレイヤー

レイヤー	LOC	パターン	設計原則
Engine	98K	Protocol + Composition + DI	抽象化で拡張性を確保
API	20K	FastAPI pragmatic monolith	薄いRouter → Service → ORM
UI	12K	Vanilla ES6 functional modules	Named exports, module closures

各レイヤーに設計原則は1つだけ。これが重要。最初は「全レイヤーにDDD」を適用しようとして失敗した。実際にはAPIにDDDは過剰で、Pragmatic Layeredで十分だった。

Layer 1: ガバナンス (ルールで制御)

# 意思決定の4レベル
OPERATIONAL: エージェントが自動判断 (ステータス確認等)
TACTICAL:    Org CEOが判断 (機能実装、記事公開等)
STRATEGIC:   Chairman + 人間のCONFIRM (アーキテクチャ変更等)
CRITICAL:    人間のHALT (セキュリティ侵害、データ損失等)

最重要ルール: Security HALT — セキュリティorgは全orgを即座に停止できる。これは他のどのルールよりも優先される。14-Day Revenue Ruleよりも上。

Layer 2: AEGIS OS パイプライン (LLMで推論)

6つのorgがリレー形式でクエリを処理する:

[Market Intelligence] → [Strategy (Go/No-Go)] → [Product] → [Technology] → [Execution] → [Validation]

各ステージは独立したcircuit breakerで保護されている。1つが壊れても他は動く。

# 実際のコード (pipeline_resilience.py)
class StageCircuitBreaker:
    """ステージごとの独立したサーキットブレーカー"""
    def __init__(self, failure_threshold=3, cooldown=60):
        self.state = "closed"  # closed → open → half_open
        self.failure_count = 0

    def call(self, func, *args):
        if self.state == "open":
            if time.time() - self.last_failure > self.cooldown:
                self.state = "half_open"  # 再試行
            else:
                raise CircuitOpenError(f"Circuit open for {self.stage}")
        try:
            result = func(*args)
            self._on_success()
            return result
        except Exception as e:
            self._on_failure()
            raise

パイプラインが途中で失敗しても、完了済みステージからresume可能:

# 最初の実行 (Stage 3で失敗)
make org-pipeline QUERY="AI marketplace"
# → Stage 1 ✅, Stage 2 ✅, Stage 3 ❌

# 中断復帰
python3 orchestrator.py --resume run_20260327_143022
# → Stage 1 (スキップ), Stage 2 (スキップ), Stage 3 → 6 (再実行)

Layer 3: Claude Code Integration (実行)

Claude CodeのAgentツールで並列エージェントを起動する。これがAEGISの「実際の手足」だ。

# 実際の使用例: 5つの並列エージェントでテスト作成
Agent("schemas テスト作成", run_in_background=True)
Agent("resilience統合テスト", run_in_background=True)
Agent("ステージ3-6テスト", run_in_background=True)
Agent("MCPツールテスト", run_in_background=True)
Agent("E2E統合テスト", run_in_background=True)
# → 全て並列実行 → 結果を統合 → 367テスト作成

実際のセッション — 1日で367テストを書いた話

「テストを書け」と言われて嬉しい開発者はいない。しかし140体のエージェントを持つシステムで「テストなし」は自殺行為だ。

問題

初期段階ではテストが24個しかなかった。pipeline_resilience.pyにバグを入れると、気づくのは本番で壊れた時。

解決: 並列エージェントでテストを量産

Claude CodeにはAgentツールがある。これを使って5つの並列エージェントに同時にテストを書かせた:

Agent 1: schema validation テスト → 82テスト (JSONパース、全スキーマ検証)
Agent 2: pipeline_resilience テスト → 22テスト (circuit breaker, retry, health check)
Agent 3: stage 3-6 ユニットテスト → 45テスト (各ステージの入出力検証)
Agent 4: MCPツールテスト → 34テスト (8つのMCPツール全カバー)
Agent 5: E2Eテスト → 41テスト (フルパイプライン結合テスト)

結果、1日で338テストが生まれた。その後の機能追加で367テストに到達。

なぜ並列が効くのか

テストファイルは依存関係が少ない。Agent 1がschemaテストを書いている間、Agent 4がMCPテストを書いても衝突しない。これが「記事を5人で書け」だと衝突する（同じファイルを触る）。タスクの性質を見極めて並列化するのがコツ。

テスト実行結果:
test_schemas.py          — 82テスト
test_pipeline_resilience — 22テスト
test_stages.py           — 45テスト
test_mcp_tools.py        — 34テスト
test_parallel_pipeline   — 14テスト
test_e2e_pipeline.py     — 41テスト
test_browser_agent       — 68テスト (SSRF防御、URL検証)
+ 追加テスト              — 61テスト
─────────────────────────
合計                      367テストメソッド
全テスト実行時間: 約9秒

収益専門家エージェントの追加

136体で始めたAEGISだが、収益がゼロだった。技術的に美しいシステムを作っても、稼げなければ持続できない。

問題の本質

汎用のrevenue_ceoは「戦略」は語れるが、各プラットフォームの具体的な攻略法を知らない。「ココナラで売れ」と言っても、検索アルゴリズムの仕組みも価格設定の相場も知らない。

4体の収益専門家エージェントを追加

# Revenue org (9 → 11体)
coconala_specialist:
  focus: "ココナラ出品最適化、価格戦略、検索アルゴリズム攻略、レビュー獲得"
  # ココナラの検索は「お気に入り数 × 販売件数 × レビュー」で決まる
  # 初期はダンピング価格で実績を積む戦略

gumroad_specialist:
  focus: "Gumroad商品設計、3段階価格戦略、外部集客導線、メール配信最適化"
  # Gumroad Discoverに載れば自然流入が発生する
  # 3段階 ($9.99 / $24.99 / $49.99) の価格戦略

# Education org (5 → 7体)
menta_specialist:
  focus: "MENTAプラン設計、ニッチ×得意掛け合わせ、リテンション最適化"
  # 「Claude Code × ソロプレナー」という超ニッチでポジショニング
  # 無料相談 → 月額¥5,000のコンバージョン導線

udemy_specialist:
  focus: "Udemyコース設計、ベストセラー獲得戦略、自分集客97%最大化"
  # 自分の集客リンク経由なら売上の97%が手元に残る
  # ニッチキーワードで検索上位を狙う

ポイント: 汎用エージェントに知識を足すのではなく、専門エージェントを分離した。これにより、ココナラの価格戦略とGumroadの価格戦略が衝突しない。各プラットフォームには独自のルールがある。

エージェントプロンプト設計の深い話

140体のプロンプトに共通プロトコルを注入する:

# _shared_protocols.md (全エージェント共通)
- 憲法遵守: manifesto違反 = HALT
- 信頼度表明: 0.9+ → proceed, 0.7-0.89 → note, <0.5 → don't present as fact
- 反ハルシネーション: ファイル参照前に存在確認、メトリクス引用時にソース明記
- セキュリティ: ハードコードした秘密 = HALT

各エージェントはこの共通基盤の上に、専門知識と禁止事項を持つ:

# pentester.prompt (例)
## ETHICAL GUARDRAILS (絶対)
- 許可されたシステムのみテスト
- 破壊的行為禁止 — 脆弱性確認で停止
- DoS禁止、データ持ち出し禁止
- 全ての発見に修正案を含める

プロンプトの3層構造

Layer 1: _shared_protocols.md (全エージェント共通 — 憲法)
Layer 2: org_agents.yaml (組織レベル — 権限・制約・KPI)
Layer 3: <agent_name>.prompt (個別 — 専門知識・禁止事項)

なぜ3層なのか？最初は6層だった。結果、LLMはルールの30%を無視した。層が深いほど弱いルールが無視される。3層が最適解だった。

💡 ここまでの設計パターンをもっと詳しく知りたい方へ

この記事では概要を書いていますが、全プロンプトテンプレート（コピペ可）、ガバナンスルール全文、コスト最適化の具体設定、再利用可能なスターターキットを含む完全版を公開しています。

📖 完全版: Claude Codeで140体のAIエージェント組織を構築した全設計図（¥500）

56個のエージェントプロンプト集（英語版）は Gumroad でも入手可能です。

CrewAI / LangGraph / AutoGen との違い

「マルチエージェントなら CrewAI や AutoGen を使えばいいのでは?」と思うだろう。実際に全部試した上で、AEGISは独自設計を選んだ。

比較表

観点	CrewAI	LangGraph	AutoGen	AEGIS
エージェント定義	Python class	Graph node	ConversableAgent	Markdownプロンプト
ガバナンス	なし	なし	なし	4レベル意思決定 + 憲法
安全停止	なし	なし	なし	Security HALT (即時)
スケール上限	~10体	~20 node	~10体	140体 (オンデマンド)
LLMコスト	全てクラウド	全てクラウド	全てクラウド	90%ローカル (¥0)
テスト容易性	低い	中程度	低い	高い (Protocol抽象化)
学習コスト	低い	高い	中程度	高い

具体的な違い

1. ガバナンスがない問題

CrewAIで10体のエージェントを動かすと、全員が平等に発言する。セキュリティリスクのある提案を止める仕組みがない。AEGISではsecurity_ceoが全orgを即座に停止できる。

# CrewAIの場合
crew = Crew(agents=[dev, reviewer, deployer])
crew.kickoff()  # → 誰が最終判断する? セキュリティは?

# AEGISの場合
# security_ceo が HALT → 全org停止 → 人間にエスカレート
# 14-Day Revenue Rule < Security HALT (優先順位が明示的)

2. プロンプトがコードに埋まる問題

CrewAIやAutoGenでは、エージェントのプロンプトがPythonコードの中に書かれる。140体のプロンプトをPythonファイルの中で管理するのは地獄。

AEGISでは全プロンプトが独立した.promptファイル。エンジニアでなくてもプロンプトを編集できる。

3. ¥0運用ができない問題

他のフレームワークはOpenAI/Anthropic APIを前提としている。AEGISはOllama (ローカルLLM) をデフォルトで使い、日常業務の90%を¥0で処理する。

# LLMルーティング
OPERATIONAL: qwen2.5:14b (Ollama, ローカル, ¥0)
TACTICAL:    Claude Sonnet 4.6 (クラウド)
STRATEGIC:   Claude Opus 4.6 (クラウド)

正直な結論

5体以下のエージェントなら CrewAI で十分。学習コストが低く、すぐ動く。

10体以上、かつガバナンスが必要なら — 既存フレームワークでは足りない。AEGISのようなカスタム設計が必要になる。これは「AEGISが優れている」ではなく、「問題の規模が違う」という話。

コスト最適化: ¥0で動かす

# Adapter Patternで段階的移行
LLM:     Ollama(¥0) → Claude API(有料) — env varで切替
DB:      SQLite(¥0) → PostgreSQL(有料) — Adapter差替
Storage: ファイルシステム(¥0) → S3/R2(有料) — Adapter差替
Cache:   In-memory(¥0) → Redis(有料) — Adapter差替
TTS:     Edge TTS(¥0) → ElevenLabs(有料) — Adapter差替

日常業務の90%はローカルLLMで処理。M1 Max 64GBで快適に動作。クラウドは重要な判断時のみ。

# 最小構成で起動 (Docker不要)
make dev-minimal
# → Ollamaだけで AEGIS OS パイプラインが動く

失敗から学んだこと

失敗1: 「ルールを書けば従う」は幻想

最初は200ページのルールブックを書いた。結果: LLMはルールの30%を無視した。

解決策: ルールを6層から3層に削減。最重要ルールだけを強調。「やるべきこと」より「やってはいけないこと」の方がLLMは従う。

失敗2: エージェント数を増やしすぎた

最初は「エージェントが多い = 品質が高い」と思った。実際は:

通信オーバーヘッドが爆増
コンテキストウィンドウを設定読み込みだけで消費
使われないエージェントが全体の40%

解決策: 使われていないエージェントを削除する代わりに、オンデマンドロードに変更。必要な時だけ起動する。常時稼働は20-30体。残りは寝ている。

失敗3: ¥0の売上

30本以上の記事を書いた。Gumroad商品も作った。売上ゼロ。

原因は単純: トラフィックがゼロ。良い記事を書いても、誰も見なければ売れない。

学び: コンテンツ生成AIは「書く」作業を自動化するが、「読んでもらう」作業は自動化できない。配信とマーケティングが本当のボトルネック。

失敗4: トークン浪費

毎会話で~6,000トークンをルール読み込みだけで消費していた。実作業に使えるコンテキストが激減。

解決策: 全設定ファイルを69%圧縮 (1,609行 → 494行)。プロンプトも29%圧縮 (22,262行 → 15,814行)。情報ゼロロスで達成。

失敗5: ドキュメントと実態の乖離

ドキュメントに「146エージェント」と書いてあるのに実際は136体だった。User Testing orgが24→21に変更されたが更新漏れ。

解決策: agents.yamlから正確なカウントを自動取得するスクリプトを作成。ドキュメントと実装の不一致は自動検知する。手動管理は必ず壊れる。

数字で見る

指標	値
エージェント総数	140体 (135 org + 5 holdings)
組織数	18 orgs × 4 boards
Python LOC	135,000+
テスト	367メソッド
テスト実行時間	~9秒
プロンプトファイル	139+ ファイル
コンテキスト消費	~2,000トークン/会話 (圧縮後)
LLMコスト (ローカル)	¥0/月
収益専門家エージェント	4体 (coconala, gumroad, menta, udemy)

技術スタック

エンジン設計:     Protocol + Composition + DI (Python)
エージェント定義:  Markdownプロンプト (.prompt) × 140体
パイプライン:     Python (asyncio + ThreadPoolExecutor)
LLM:             Ollama (qwen2.5:14b) + Claude API (フォールバック)
設定:            YAML (ai_config.yaml, agents.yaml)
テスト:          pytest (367テスト, ~9秒)
検索:            SearXNG (セルフホスト)
MCP:             FastMCP (8ツール)
API:             FastAPI (20K LOC, 12 routers)
UI:              Vanilla ES6 modules (12K LOC)
CI:              GitHub Actions + detect-secrets + pip audit

再現手順

# 1. リポジトリ構造 (概要)
aegis/
├── engine/                      # エンジン (98K LOC)
│   ├── organizations/           # AEGIS OSパイプライン (10K LOC)
│   ├── common/                  # DI, circuit breaker, protocols
│   └── external/                # 外部連携 (publishers, validators)
├── orgs/                        # 18組織 × エージェントプロンプト
│   ├── revenue/                 # Revenue org (11 agents)
│   ├── education/               # Education org (7 agents)
│   ├── security/                # Security org (6 agents)
│   └── ...                      # 他15組織
├── holdings/                    # ガバナンス (Secretary, 4 Chairmen)
├── prompts/                     # 共有プロトコル
├── config/organizations/        # LLM設定
├── services/api/                # FastAPI (20K LOC)
└── ui/public/                   # Vanilla ES6 UI (12K LOC)

# 2. 最小起動
make dev-minimal  # Ollamaのみ、Docker不要

# 3. パイプライン実行
make org-pipeline QUERY="AI agent marketplace"

# 4. テスト
python3 -m pytest engine/organizations/tests/ -v
# → 367 passed in ~9s

まとめ

140体のAIエージェント組織は、過剰に見えるかもしれない。実際に過剰だった部分もある。

しかし学んだことは:

専門分化はLLMでも有効 — 1体の万能AIより、専門家チームの方が品質が高い
ガバナンスは必須 — 野放しのAIは暴走する。Security HALTは命綱
テストが全て — 367テストなしでは怖くて触れない
コストはゼロにできる — ローカルLLMで日常業務の90%を処理
フレームワーク選定より設計原則 — CrewAI/AutoGenで足りないなら作る。でも5体以下ならCrewAIで十分
作るだけじゃダメ — 最大の失敗は「良いものを作れば売れる」という幻想
プラットフォーム専門家は汎用AIより強い — ココナラの攻略法とUdemyの攻略法は全く違う

次はこの経験を活かして、AIエージェント設計のメンタリングと有料チュートリアルを始める。道具は十分。あとは人に届けるだけだ。

関連リンク

📖 完全版: 全設計図 + プロンプトテンプレート + スターターキット (¥500)
🛒 56個のAIエージェントプロンプト集 — Gumroad
📝 Zennプロフィール — 他の技術記事はこちら
💬 質問やフィードバックはコメント欄へ。全て読んでいます。

この記事はClaude Codeの/askコマンドでAEGIS Secretaryにルーティングされ、Content Boardが執筆を担当しました。記事自体がAEGISの出力です。