サブエージェント管理

サブエージェントは、独自のカスタムシステムプロンプト、独立したコンテキストウィンドウ、隔離された実行環境で動作する特化型 AI エージェントです。メインエージェントから委任された特定のタスクを処理し、メインの会話コンテキストを汚染しません。

主な特徴:

• 隔離されたコンテキストウィンドウ: 各サブエージェントは独自の独立したコンテキストウィンドウを保持します。サブエージェントが返す最終結果のみがメインエージェントのコンテキストを消費し、中間処理は消費しません。
• カスタムシステムプロンプト: すべてのサブエージェントは、その動作、性格、タスク解釈アプローチを定義する専用のシステムプロンプトを持ちます。
• 自動タスク委任: メインエージェントは、適切なタスクタイプを検出すると、自動ツール選択と同様に、サブエージェントを自動的に呼び出します。
• 手動呼び出し: @メンション（@Verifier、@Explorer、@Code-reviewer）を使ってサブエージェントを明示的に参照できます。

2 つのカテゴリ:

• デフォルトサブエージェント: 組み込み（Verifier、Explorer、Code-reviewer）— すぐに利用でき、事前設定済み
• カスタムサブエージェント: ユーザーが作成し、~/.verdent/subagents/ に保存される — プロジェクト固有のニーズに合わせて調整

デフォルトサブエージェントの理解

Verdent for VS Code には、事前設定済みですぐに利用でき、セットアップや設定が不要な 3 つの組み込みデフォルトサブエージェントが含まれています。

@Verifier check this authentication logic

@Explorer find all API endpoints

@Code-reviewer review this authentication flow

自動呼び出しと手動呼び出し

自動選択のトリガー:

メインエージェントは、タスクパターンの認識に基づいてサブエージェントを自動的に選択します:

Explorer サブエージェント:

• コードベース構造に関する質問（「アーキテクチャはどうなっていますか?」「X はどこに実装されていますか?」）
• ファイル検索のリクエスト（「〜するすべてのファイルを検索して」「〜に関連するコンポーネントを表示して」）
• コードナビゲーションのクエリ（「認証はどう動作しますか?」「この関数を呼び出しているのは何ですか?」）

Code-reviewer サブエージェント:

• セキュリティレビューのリクエスト（「セキュリティ脆弱性をレビューして」「SQL インジェクションのリスクをチェックして」）
• コード品質評価のプロンプト（「コード品質を分析して」「保守性の問題を特定して」）
• コミット前レビューのシナリオ（コード変更が提示されたときに暗黙的に）

Verifier サブエージェント:

• 検証のリクエスト（「このロジックを検証して」「この実装が正しいかチェックして」）
• 構文と正確性のチェック（「このコードは動きますか?」「認証フローを検証して」）

手動指定:

@メンションを使って自動ルーティングを上書きできます:

@Explorer find all authentication-related files
@Code-reviewer review the security of login flow
@Verifier check validation logic in middleware

Add Subagent ボタン: Input Box の Add Subagent ボタンを選択すると、次のことができます:

• 利用可能なサブエージェント（デフォルトとカスタム）から選択
• 選択したサブエージェントにタスクを明示的に委任
• 自動ルーティングの判断を上書き

手動指定のメリット:

• 正確性: 特定のサブエージェントが確実にタスクを処理
• 上書き: 複数が該当しうる場合に特定のサブエージェントを選択
• テスト: カスタムサブエージェントの動作を明示的に検証
• 一貫性: 同じサブエージェントでタスクを繰り返し、一貫した結果を取得

カスタムサブエージェントの作成

カスタムサブエージェントを使うと、プロジェクト固有のニーズ、ドメインの専門知識、チームのワークフローに合わせた特化型エージェントを作成できます。

作成方法

ファイル構造

カスタムサブエージェントファイルは、YAML フロントマター付きの Markdown 形式を使用します:

---
name: subagent-name
description: Brief description of specialization
---
# System Prompt

[Behavior definition, personality, interpretation style]

Invocation policy (strict): Only run if explicitly requested.

When to use:
- Specific scenario 1
- Specific scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2

YAML フロントマター（必須）:

• name: @メンションで使用するサブエージェントの識別子
• description: サブエージェントの目的を表す 1 行の説明

システムプロンプトセクション: サブエージェントの動作を定義する Markdown コンテンツ:

• 性格とトーン
• タスクの解釈アプローチ
• 出力形式の好み
• 意思決定の原則

呼び出しポリシー（必須）:

Invocation policy (strict|flexible): Policy description

• strict: ユーザーから明示的に要求された場合のみ呼び出し
• flexible: タスクパターンに基づく自動呼び出しを許可

使用ガイドライン:

When to use the [name] agent:
- Bullet list of scenarios for invocation

When NOT to use:
- Bullet list of scenarios to avoid

カスタムサブエージェントの例

---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt

You are an API documentation specialist.

Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides

When NOT to use:
- Inline code comments
- User-facing documentation

---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt

You are a database migration safety specialist.

Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables

Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures

When NOT to use:
- Schema design from scratch
- Query optimization

---
name: a11y-auditor
description: Audits frontend code for accessibility compliance
---
# System Prompt

You are an accessibility compliance specialist (WCAG 2.1 Level AA).

Audit criteria:
- Semantic HTML structure
- ARIA labels and roles
- Keyboard navigation support
- Color contrast ratios
- Screen reader compatibility
- Focus management

Report format:
- Issues categorized by severity (critical/major/minor)
- WCAG guideline references
- Code examples showing fixes
- Testing recommendations

Invocation policy (flexible): May auto-invoke for UI component reviews.

When to use:
- User creates/modifies UI components
- Pre-deployment accessibility checks
- Compliance audits

When NOT to use:
- Backend API code
- Build configuration files

カスタムサブエージェントの一般的なユースケース

サブエージェントの動作設定（AGENTS.md パターン）

AGENTS.md は主にプロジェクトルールファイルとして機能しますが（ルールシステムを参照）、プロジェクト固有のサブエージェントの動作を定義することもできます。

システムプロンプト設計の原則

具体的かつ指示的に: 一般的なガイダンスではなく、正確な動作の期待値を定義します。

良い例:

Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks

避けるべき例:

Try to optimize code when possible

性格とトーンを確立する: 特定の目的に最適化された明確な「ペルソナ」を作成します:

You are a performance optimization specialist.

意思決定の原則を定義する: サブエージェントがトレードオフにどう対処すべきかを導きます:

When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement

出力形式を指定する: 結果の提示方法を制御します:

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

呼び出しポリシーの設定

Strict ポリシー:

Invocation policy (strict): Only run when explicitly requested.

次の場合に使用します:

• サブエージェントが機密性の高い操作（セキュリティレビュー、データベースマイグレーション）を扱う
• ユーザーが呼び出すタイミングを意識的に決定すべき
• 自動呼び出しが妨げになりうる

Flexible ポリシー:

Invocation policy (flexible): May auto-invoke based on task patterns.

次の場合に使用します:

• サブエージェントが妨げにならず有用なコンテキストを提供する
• 自動呼び出しがワークフローの効率を高める
• タスクパターンが明確に識別できる

使用ガイドラインのベストプラクティス:

「いつ使うか」セクション:

• トリガーとなるシナリオを具体的に記述
• サブエージェントを呼び出すべきプロンプトの例を含める
• サブエージェントの専門領域に合致するタスクの特徴を記述

「いつ使わないか」セクション:

• 不適切な呼び出しを防ぐために除外条件を明示的にリスト化
• 関連するサブエージェントとの境界を明確化
• スコープの肥大化を防止

タスクルーティングとディスパッチ

Verdent のマルチサブエージェントシステムにより、自動ルーティングと特化型エージェント間の連携を通じて、タスクの並列実行が可能になります。

アーキテクチャの構成要素

メインエージェント（オーケストレーター）: プライマリエージェントがユーザーのリクエストを分析し、複雑なタスクを分解し、特化した作業を適切なサブエージェントに委任します。会話コンテキストを維持し、サブエージェントの結果を調整します。

サブエージェントプール: 自動または手動で呼び出せる、利用可能なサブエージェント（デフォルトとカスタムの両方）の集合です。それぞれが独立したコンテキストで個別に動作します。

自動タスクルーティング: メインエージェントがサブエージェントの専門領域に合致するタスクパターンを検出すると、作業を自動的にディスパッチします:

• コードベース探索の質問 → Explorer サブエージェント
• セキュリティレビューのリクエスト → Code-reviewer サブエージェント
• 検証チェック → Verifier サブエージェント

並列実行: 複雑な操作では、複数のサブエージェントを同時に実行できます。例: Explorer サブエージェントがコードベースを検索する一方で、Code-reviewer が同時にセキュリティを分析し、より高速に結果を提供します。

結果の統合: サブエージェントの出力はメインエージェントに返され、メインエージェントが結果を統合し、統一されたレスポンスをユーザーに提示します。

サブエージェントの監視

Verdent がサブエージェントの操作と結果を表示する Chat View を通じて、サブエージェントの使用状況とパフォーマンスを追跡できます。

監視方法

Chat View のインジケーター:

• サブエージェントの呼び出しが会話履歴に表示される
• サブエージェントの実行中は進捗インジケーターが表示される
• どのサブエージェントが出力を提供したかが結果に明示される

サブエージェント出力セクション: 専用の表示領域:

• サブエージェントのタスク実行結果
• 並列タスクの進捗インジケーター
• タスク完了時の統合サマリー

レスポンスの帰属: Verdent はレスポンス内で発見事項を特定のサブエージェントに帰属させ、どのエージェントがどの分析や検索を実行したかを明確にします。

可視性と透明性

操作の透明性: Verdent は次を表示します:

• どのサブエージェントが呼び出されたか
• 呼び出しが自動か手動か
• タスク委任の理由
• サブエージェントの実行ステータス

手動指定の確認: @メンションを使用すると、Verdent は指定したサブエージェントがタスクを処理していることを確認し、ルーティングの設定が尊重されることを保証します。

関連項目