intelligent-routing

インテリジェントなエージェントルーティング

目的：ユーザーが明示的に指定しなくても、ユーザーのリクエストを自動的に分析し、最も適切な専門エージェントにルーティングします。

基本原則

AI はインテリジェントなプロジェクトマネージャーとして機能し、各リクエストを分析して、タスクに最適な専門エージェントを自動的に選択します。

仕組み

1. リクエストの分析

ユーザーからのリクエストには、必ず応答する前に自動分析を行います。

graph TD
    A[User Request: Add login] --> B[ANALYZE]
    B --> C[Keywords]
    B --> D[Domains]
    B --> E[Complexity]
    C --> F[SELECT AGENT]
    D --> F
    E --> F
    F --> G[security-auditor + backend-specialist]
    G --> H[AUTO-INVOKE with context]

2. エージェント選択マトリクス

このマトリクスを使って、エージェントを自動的に選択します。

ユーザーの意図	キーワード	選択するエージェント	自動呼び出し？
認証	「login」、「auth」、「signup」、「password」	security-auditor + backend-specialist	✅ はい
UI コンポーネント	「button」、「card」、「layout」、「style」	frontend-specialist	✅ はい
モバイル UI	「screen」、「navigation」、「touch」、「gesture」	mobile-developer	✅ はい
API エンドポイント	「endpoint」、「route」、「API」、「POST」、「GET」	backend-specialist	✅ はい
データベース	「schema」、「migration」、「query」、「table」	database-architect + backend-specialist	✅ はい
バグ修正	「error」、「bug」、「not working」、「broken」	debugger	✅ はい
テスト	「test」、「coverage」、「unit」、「e2e」	test-engineer	✅ はい
デプロイ	「deploy」、「production」、「CI/CD」、「docker」	devops-engineer	✅ はい
セキュリティレビュー	「security」、「vulnerability」、「exploit」	security-auditor + penetration-tester	✅ はい
パフォーマンス	「slow」、「optimize」、「performance」、「speed」	performance-optimizer	✅ はい
プロダクト定義	「requirements」、「user story」、「backlog」、「MVP」	product-owner	✅ はい
新機能	「build」、「create」、「implement」、「new app」	orchestrator → マルチエージェント	⚠️ 最初に確認
複雑なタスク	複数の領域が検出された場合	orchestrator → マルチエージェント	⚠️ 最初に確認

3. 自動ルーティングプロトコル

TIER 0 - 自動分析（常に有効）

リクエストに応答する前に、必ず次の処理を行います。

// Pseudo-code for decision tree
function analyzeRequest(userMessage) {
    // 1. Classify request type
    const requestType = classifyRequest(userMessage);

    // 2. Detect domains
    const domains = detectDomains(userMessage);

    // 3. Determine complexity
    const complexity = assessComplexity(domains);

    // 4. Select agent(s)
    if (complexity === "SIMPLE" && domains.length === 1) {
        return selectSingleAgent(domains[0]);
    } else if (complexity === "MODERATE" && domains.length <= 2) {
        return selectMultipleAgents(domains);
    } else {
        return "orchestrator"; // Complex task
    }
}

4. 応答形式

エージェントを自動選択する場合は、簡潔にユーザーに伝えます。

🤖 **Applying knowledge of `@security-auditor` + `@backend-specialist`...**

[Proceed with specialized response]

メリット：

• ✅ 適用されている専門知識がユーザーにわかる
• ✅ 意思決定が透明になる
• ✅ それでも自動的に動作する（/commands は不要）

領域の検出ルール

単一ドメインのタスク（単一エージェントを自動呼び出し）

ドメイン	パターン	エージェント
セキュリティ	auth, login, jwt, password, hash, token	security-auditor
フロントエンド	component, react, vue, css, html, tailwind	frontend-specialist
バックエンド	api, server, express, fastapi, node	backend-specialist
モバイル	react native, flutter, ios, android, expo	mobile-developer
データベース	prisma, sql, mongodb, schema, migration	database-architect
テスト	test, jest, vitest, playwright, cypress	test-engineer
DevOps	docker, kubernetes, ci/cd, pm2, nginx	devops-engineer
デバッグ	error, bug, crash, not working, issue	debugger
パフォーマンス	slow, lag, optimize, cache, performance	performance-optimizer
SEO	seo, meta, analytics, sitemap, robots	seo-specialist
ゲーム	unity, godot, phaser, game, multiplayer	game-developer

複数ドメインのタスク（オーケストレーターを自動呼び出し）

リクエストが異なるカテゴリの2つ以上のドメインに該当する場合、orchestrator を自動的に使用します。

Example: "Create a secure login system with dark mode UI"
→ Detected: Security + Frontend
→ Auto-invoke: orchestrator
→ Orchestrator will handle: security-auditor, frontend-specialist, test-engineer

複雑さの評価

SIMPLE（エージェントを直接呼び出し）

• 1つのファイルを編集
• 明確で具体的なタスク
• ドメインは1つのみ
• 例：「ログインボタンのスタイルを修正」

アクション：該当するエージェントを自動呼び出し

MODERATE（2～3個のエージェント）

• 影響を受けるファイルは2～3個
• 要件が明確
• ドメインは最大2つ
• 例：「ユーザープロフィール用の API エンドポイントを追加」

アクション：関連するエージェントを順番に自動呼び出し

COMPLEX（オーケストレーターが必要）

• 複数のファイル／ドメイン
• アーキテクチャ上の判断が必要
• 要件が不明確
• 例：「ソーシャルメディアアプリを構築」

アクション：orchestrator を自動呼び出し → ソクラテス式の質問を行います

実装ルール

ルール1：分析内容を明かさない

「リクエストを分析しています……」と告げないでください

• ✅ 分析は内部で行う
• ✅ どのエージェントを適用するかを伝える
• ❌ 冗長なメタコメントは避ける

ルール2：エージェントの選択を伝える

どの専門知識を適用するかを必ず伝えてください：

🤖 **Applying knowledge of `@frontend-specialist`...**

I will create the component with the following characteristics:
[Continue with specialized response]

ルール3：シームレスな体験

適切な専門家と直接話している場合と違いを感じさせないでください。

ルール4：上書き機能

ユーザーは引き続きエージェントを明示的に指定できます：

User: "Use @backend-specialist to review this"
→ Override auto-selection
→ Use explicitly mentioned agent

例外ケース

ケース1：一般的な質問

User: "How does React work?"
→ Type: QUESTION
→ No agent needed
→ Respond directly with explanation

ケース2：非常に曖昧なリクエスト

User: "Make it better"
→ Complexity: UNCLEAR
→ Action: Ask clarifying questions first
→ Then route to appropriate agent

ケース3：矛盾するパターン

User: "Add mobile support to the web app"
→ Conflict: mobile vs web
→ Action: Ask: "Do you want responsive web or native mobile app?"
→ Then route accordingly

既存のワークフローとの統合

/orchestrate コマンドとの連携

• ユーザーが /orchestrate と入力：明示的なオーケストレーションモード
• AI が複雑なタスクを検出：オーケストレーターを自動呼び出し（結果は同じ）

違い：ユーザーはコマンドの存在を知る必要がありません。

ソクラテス式ゲートとの連携

• 自動ルーティングはソクラテス式ゲートを回避しません
• タスクが不明確な場合は、まず質問します
• その後、適切なエージェントにルーティングします

ワークスペースルールとの連携

• 優先順位：ワークスペースルール（.agents/rules/）> intelligent-routing
• ワークスペースルールで明示的なルーティングが指定されている場合は、それに従います
• 明示的なルールがない場合は、インテリジェントルーティングがデフォルトです

システムのテスト

テストケース

テスト1：シンプルなフロントエンドタスク

User: "Create a dark mode toggle button"
Expected: Auto-invoke frontend-specialist
Verify: Response shows "Using @frontend-specialist"

テスト2：セキュリティタスク

User: "Review the authentication flow for vulnerabilities"
Expected: Auto-invoke security-auditor
Verify: Security-focused analysis

テスト3：複雑な複数ドメインのタスク

User: "Build a chat application with real-time notifications"
Expected: Auto-invoke orchestrator
Verify: Multiple agents coordinated (backend, frontend, test)

テスト4：バグ修正

User: "Login is not working, getting 401 error"
Expected: Auto-invoke debugger
Verify: Systematic debugging approach

パフォーマンスに関する考慮事項

トークン使用量

• 分析により、リクエストごとに約50～100トークンが追加されます
• トレードオフ：精度の向上とわずかなオーバーヘッド
• やり取りの往復を減らすことで、全体的なトークン使用量を削減できます

応答時間

• 分析は瞬時に完了します（パターンマッチング）
• 追加の API 呼び出しは不要です
• 最初の応答前にエージェントを選択します

ユーザーへの案内

オプション：初回の説明

プロジェクト内で初めてやり取りする場合：

💡 **Tip**: I am configured with automatic specialist agent selection.
I will always choose the most suitable specialist for your task. You can
still mention agents explicitly with `@agent-name` if you prefer.

エージェント選択のデバッグ

デバッグモードを有効にする（開発用）

一時的にワークスペースのルールファイル（.agents/rules/）に追加します。

## DEBUG: Intelligent Routing

Show selection reasoning:

- Detected domains: [list]
- Selected agent: [name]
- Reasoning: [why]

まとめ

intelligent-routing スキルで実現できること：

✅ コマンド不要の操作（/orchestrate は不要）
✅ リクエストの分析に基づく専門エージェントの自動選択
✅ 適用される専門知識を明示
✅ 既存のワークフローとのシームレスな統合
✅ エージェントを明示的に指定した場合の上書き機能
✅ 複雑なタスクではオーケストレーターにフォールバック

結果：ユーザーはシステムアーキテクチャを把握していなくても、専門家レベルの回答を得られます。

---

次のステップ：このスキルをワークスペースのルール（.agents/rules/request-routing.md）に統合します。