# 拡張性とカスタマイズ (/ja/docs/verdent-for-vscode/advanced-features/extensibility) > カスタムサブエージェント、ルール、MCP 連携を通じて Verdent の機能を拡張する ### 学習内容 [#学習内容] 3 つの強力な拡張方法を使って Verdent for VS Code をカスタマイズし、拡張する方法を学びます。すなわち、カスタムサブエージェント、ルールシステム、そして MCP 連携です。 *** ## 拡張性の概要 [#拡張性の概要] Verdent for VS Code には、機能を拡張し動作をカスタマイズするための主要な方法が 3 つあります。 1. **カスタムサブエージェント** - ドメイン固有のタスク向けに特化した AI エージェントを作成する 2. **ルールシステム** - VERDENT.md、AGENTS.md、plan\_rules.md を通じて動作を制御する 3. **MCP 連携** - Model Context Protocol を介して外部のツールやサービスを接続する 各方法は異なるカスタマイズニーズに対応しており、ワークフロー全体を最適化するために組み合わせて使用できます。 *** ## 方法 1: カスタムサブエージェント [#方法-1-カスタムサブエージェント] ### 概要 [#概要] カスタムサブエージェントは、専用のシステムプロンプト、呼び出しポリシー、タスク固有の専門知識を備えた特化型 AI エージェントです。Verdent の組み込みサブエージェント（`@Verifier`、`@Explorer`、`@Code-reviewer`）を、プロジェクト固有の機能で拡張します。 **保存場所:** `~/.verdent/subagents/` ### カスタムサブエージェントの作成 [#カスタムサブエージェントの作成] **ファイル構造:** ```markdown --- name: subagent-name description: One-line purpose description --- # System Prompt [Behavior definition, personality, task interpretation approach] Invocation policy (strict|flexible): Policy description When to use: - Scenario 1 - Scenario 2 When NOT to use: - Avoid scenario 1 - Avoid scenario 2 ``` **作成方法:** **方法 1: 設定メニュー** 1. Settings → Subagents 2. 「Create new subagent」 3. 名前、説明、システムプロンプトを定義する 4. 呼び出しポリシーを設定する 5. `~/.verdent/subagents/` に保存する **方法 2: ファイルを直接作成** 1. `~/.verdent/subagents/` に移動する 2. Markdown ファイルを作成する（例: `security-reviewer.md`） 3. YAML フロントマターを追加する 4. システムプロンプトと使用ガイドラインを記述する ### カスタムサブエージェントのユースケース [#カスタムサブエージェントのユースケース] **ドメイン固有の専門知識:** * **金融計算:** 税務コンプライアンス、金融規制 * **ヘルスケアの HIPAA コンプライアンス:** 患者データ取り扱い基準 * **暗号:** セキュリティ実装のベストプラクティス **チーム固有のワークフロー:** * **コードスタイルの徹底:** linter ルールを超えるチームのコーディング標準 * **ドキュメントの一貫性:** ドキュメントがチームのテンプレートに従うよう保証する * **依存関係の監査:** サードパーティパッケージを承認済みリストと照合して監視する **技術スタックのスペシャリスト:** * **React パフォーマンス最適化:** 不要な再レンダリングを特定する * **SQL クエリ最適化:** データベースのパフォーマンスを分析・改善する * **Docker 設定レビュー:** コンテナ化の実装を検証する **品質保証:** * **テストカバレッジ分析:** テストされていないコードパスを特定する * **エラーハンドリングレビュー:** 包括的な例外処理を保証する * **ロギング標準の徹底:** ロギングの実装を検証する ### 例: API ドキュメントジェネレーター [#例-api-ドキュメントジェネレーター] ```markdown --- 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 ``` **使用方法:** ``` @api-documenter document the /api/users endpoints ``` ### 例: データベースマイグレーションレビュアー [#例-データベースマイグレーションレビュアー] ```markdown --- 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 ``` ### 呼び出しポリシー [#呼び出しポリシー] **Strict ポリシー:** * サブエージェントは @-メンションで明示的にリクエストされた場合のみ実行される * 呼び出しはユーザーが完全に制御する * 特化型でたまにしか使わないサブエージェントに最適 **Flexible ポリシー:** * タスクパターンの検出に基づいて自動的に呼び出される * メインエージェントが一致するタスクを自動的にルーティングする * 頻繁に使用される、明確に定義されたサブエージェントに最適 *** ## 方法 2: ルールシステム [#方法-2-ルールシステム] ### 概要 [#概要-1] ルールファイルは、コードを変更せずに Verdent の動作、出力フォーマット、意思決定を制御する Markdown ドキュメントです。3 種類のルールが包括的なカスタマイズを提供します。 | ルールの種類 | 適用範囲 | 優先度 | 保存場所 | | ------------------ | ----------------- | --- | -------------------------- | | **VERDENT.md** | すべてのプロジェクトでグローバル | 中 | `~/.verdent/VERDENT.md` | | **AGENTS.md** | プロジェクト固有（チーム） | 最高 | プロジェクトのルートディレクトリ | | **plan\_rules.md** | Plan Mode のフォーマット | 独立 | `~/.verdent/plan_rules.md` | ### ルールの優先順位 [#ルールの優先順位] 競合が発生した場合: 1. **AGENTS.md**（最高）- プロジェクトルールがユーザー設定を上書きする 2. **VERDENT.md**（中）- プロジェクトとの競合がない場合に適用される 3. **デフォルトの動作**（最低）- Verdent の組み込みデフォルト **競合の例:** ``` VERDENT.md: "Use 2-space indentation" AGENTS.md: "Use 4-space indentation for this project" → Result: 4-space indentation (project rules win) ``` ### VERDENT.md（グローバル設定） [#verdentmdグローバル設定] **目的:** すべてのプロジェクトにわたる個人的なコーディングスタイルと設定 **例:** ```markdown # User Rules ## TypeScript Preferences - Use strict mode in tsconfig.json - Prefer interfaces over type aliases - Include return types on all functions ## Code Organization - One component per file - Named exports instead of default exports - Organize imports: external, internal, types ## Documentation - TSDoc comments for public APIs - Include @param and @returns tags ## Communication - Provide explanations before showing code - Highlight breaking changes explicitly ``` **アクセス:** Settings → Rules → User Rules ### AGENTS.md（プロジェクトルール） [#agentsmdプロジェクトルール] **目的:** チーム全体のコーディング標準とプロジェクト固有の規約 **例:** ```markdown # AGENTS.md ## Dev environment tips - Use `pnpm dlx turbo run where ` to navigate - Run `pnpm install --filter ` for dependencies - Check package.json name field for correct package name ## Testing instructions - Run `pnpm turbo run test --filter ` - From package root: `pnpm test` - Focus on one test: `pnpm vitest run -t ""` - Fix all errors before merge ## PR instructions - Title format: [] - Always run `pnpm lint` and `pnpm test` before committing ``` **アクセス:** プロジェクトのルートディレクトリ（バージョン管理対象） ### plan\_rules.md（プランのカスタマイズ） [#plan_rulesmdプランのカスタマイズ] **目的:** Plan Mode の出力フォーマットと詳細レベルを制御する **例:** ```markdown # Plan Rules ## Plan Structure - Start with brief summary (2-3 sentences) - Include estimated time for each major step - List prerequisites before implementation steps - Identify potential risks ## Level of Detail - Break tasks into subtasks of 15-30 minutes - Include specific file paths for modifications - List functions/components to create/modify ## Format - Use numbered lists for sequential steps - Use bullet points for options - Include code snippets for complex changes ``` **アクセス:** Settings → Rules → Plan Rules ### ルール記述のベストプラクティス [#ルール記述のベストプラクティス] **具体的かつ指示的に:** ``` ✓ Good: "Always use async/await for asynchronous operations" ✗ Vague: "Try to use modern JavaScript" ``` **論理的に整理する:** * 関連するルールはセクション見出しの下にまとめる * 関心事を分離する（スタイル、テスト、ドキュメント、セキュリティ） * ファイル間で一貫した構造を使用する **重要なルールを優先する:** * 重要なルールは各セクションの最初に配置する * 譲れない基準には強調を使う: `**NEVER** commit credentials` * バグ防止とセキュリティに重点を置く **効果をテストする:** * 新しい会話を開始してルールの適用を検証する * 実際のエージェントの動作に基づいてルールを調整する * プロジェクトの進化に合わせて更新する *** ## 方法 3: MCP 連携 [#方法-3-mcp-連携] ### 概要 [#概要-2] Model Context Protocol（MCP）は、外部のツール、データソース、サービスを接続することで Verdent を拡張します。MCP サーバーは、Verdent と外部システムをつなぐ橋渡し役として機能します。 **設定:** Settings → MCP Servers から `~/.verdent/mcp.json` ### MCP の機能 [#mcp-の機能] **外部システムへのアクセス:** * データベースクエリツール（PostgreSQL、MySQL、MongoDB） * クラウドサービスの API（AWS、Azure、GCP） * プロジェクト管理（Jira、Linear、Asana） * CI/CD パイプライン（Jenkins、GitHub Actions） * 監視サービス（Datadog、New Relic） **カスタムツールの開発:** 独自システム向けに MCP サーバーを作成します。 * 社内 API 連携 * レガシーシステムの橋渡し * 特殊なデータソース * ワークフロー自動化ツール ### MCP とカスタムサブエージェント、ルールの使い分け [#mcp-とカスタムサブエージェントルールの使い分け] | 必要なこと | 最適な方法 | 理由 | | ------------------- | ------------------- | ------------------------- | | 特化型の AI 分析 | カスタムサブエージェント | カスタムコンテキストを伴う AI による推論が必要 | | コーディング標準の徹底 | ルール（AGENTS.md） | シンプルな動作の制御 | | 外部データベースへのアクセス | MCP 連携 | 外部システムへの接続が必要 | | 個人的なコーディング設定 | ルール（VERDENT.md） | グローバルな動作のカスタマイズ | | チームの規約 | ルール（AGENTS.md） | 共有プロジェクト標準 | | API 連携 | MCP 連携 | 外部サービスとのやり取り | | プランフォーマットのカスタマイズ | ルール（plan\_rules.md） | Plan Mode の出力制御 | | ドメインの専門知識（金融、ヘルスケア） | カスタムサブエージェント | 専門知識の応用 | ### 例: 3 つの方法すべてを組み合わせる [#例-3-つの方法すべてを組み合わせる] **シナリオ:** 厳格なコンプライアンス要件を持つフルスタック開発チーム **カスタムサブエージェント:** ```markdown --- name: compliance-auditor description: Audits code for regulatory compliance (SOC2, HIPAA) --- [System prompt for compliance checking] ``` **AGENTS.md（プロジェクトルール）:** ```markdown ## Security Standards - All API endpoints must validate inputs - Never log PII or credentials - Encrypt sensitive data at rest and in transit ## Compliance - Run @compliance-auditor before all PRs - Document data retention policies in code comments - Include audit trails for data access ``` **MCP 連携:** * **コンプライアンスデータベースの MCP サーバー:** 操作をコンプライアンスルールと照合する * **監査ログの MCP サーバー:** すべての機密データアクセスを記録する **ワークフロー:** ``` User: "Create endpoint for user profile updates" Verdent: [Applies AGENTS.md rules] [Generates secure endpoint with validation] [Automatically invokes @compliance-auditor] [Uses MCP to log operation in audit system] Result: Compliant, secure, audited endpoint ``` *** ## 拡張性のベストプラクティス [#拡張性のベストプラクティス] ### シンプルに始めて、段階的に拡張する [#シンプルに始めて段階的に拡張する] **段階的な導入:** 1. **フェーズ 1:** 基本的なルール（VERDENT.md または AGENTS.md）から始める 2. **フェーズ 2:** 繰り返し発生する特化型タスク向けにカスタムサブエージェントを追加する 3. **フェーズ 3:** 外部システム接続のために MCP を連携する ### 戦略的に方法を組み合わせる [#戦略的に方法を組み合わせる] **相乗効果の例:** **ルール + サブエージェント:** * AGENTS.md でカスタムサブエージェントをいつ呼び出すかを指定する * ルールでサブエージェントの推奨事項に従うことを徹底する **ルール + MCP:** * AGENTS.md でどの MCP サーバーが使用承認されているかを定義する * ルールでいつ外部データアクセスが必要かを指定する **サブエージェント + MCP:** * カスタムサブエージェントが MCP ツールを使って外部システムにアクセスする * サブエージェントが専門知識をもって MCP の結果を解釈する ### カスタマイズを文書化する [#カスタマイズを文書化する] **チームのドキュメント:** カスタムサブエージェントとプロジェクトルール（AGENTS.md）について: * 自明でないルールやサブエージェントの根拠を文書化する * 正しい使い方の例を示す * トラブルシューティングガイドを含める * コードと一緒にバージョン管理する **個人のドキュメント:** VERDENT.md と個人用サブエージェントについて: * 複雑なルールには理由をコメントで添える * ルールを整理し、最新に保つ * 不要になったルールは速やかに削除する ### 十分にテストする [#十分にテストする] **検証プロセス:** 1. カスタマイズを作成する（サブエージェント / ルール / MCP 設定） 2. 新しい会話を開始してテストする 3. 動作が期待通りであることを検証する 4. 結果に基づいて調整する 5. 成功したパターンを文書化する **よくあるテストシナリオ:** * サブエージェントは期待どおりに自動的に呼び出されるか？ * プロジェクトルールはユーザールールを正しく上書きするか？ * MCP サーバーは接続し、操作を実行できるか？ * 組み合わせた方法は競合せずに連携するか？ *** ## 拡張性のトラブルシューティング [#拡張性のトラブルシューティング] ### カスタムサブエージェントの問題 [#カスタムサブエージェントの問題] **サブエージェントが呼び出されない:** * 呼び出しポリシーを確認する（strict は明示的な @-メンションが必要） * 「When to use」のガイドラインがリクエストと一致しているか確認する * ファイルが `~/.verdent/subagents/` ディレクトリにあることを確認する * YAML フロントマターの構文を確認する **予期しないサブエージェントの動作:** * システムプロンプトが明確かどうか見直す * 「When to use」と「When NOT to use」のガイドラインを調整する * 明示的な @-メンションでテストし、動作を切り分ける * 結果に基づいてシステムプロンプトを反復改善する ### ルールの競合 [#ルールの競合] **ルールが適用されない:** * ルールの優先順位を確認する（AGENTS.md > VERDENT.md） * ファイルが正しい場所にあることを確認する * 新しい会話を開始して、まっさらな状態で適用をテストする * ルールをより具体的かつ指示的にする **予期しない動作:** * 同じファイル内に矛盾するルールがないか探す * ルールが曖昧すぎないか確認する * 編集しているルールファイルが正しいか確認する * 明確な表現を使う（「Always」「Never」「Prefer」） ### MCP 連携の問題 [#mcp-連携の問題] **接続の失敗:** * `mcp.json` の構文を確認する * 認証情報を確認する * MCP サーバーが稼働中でアクセス可能であることを確認する * ネットワーク接続を検証する **ツール呼び出しの問題:** * MCP サーバーが期待されるツールを公開していることを確認する * ツールのパラメータ形式を確認する * MCP サーバーのログでエラーを確認する * MCP サーバーを単独でテストする *** ## 関連項目 [#関連項目] <CardGroup cols="2"> <Card title="サブエージェントの管理" icon="users" href="/docs/verdent-for-vscode/agents-rules/subagent-management"> 詳細なサブエージェント作成ガイド </Card> <Card title="ルールシステム" icon="book" href="/docs/verdent-for-vscode/agents-rules/rule-systems"> ルールの完全なドキュメント </Card> <Card title="MCP 連携" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp"> MCP のセットアップと設定 </Card> <Card title="ツールリファレンス" icon="wrench" href="/docs/verdent-for-vscode/advanced-features/tool-reference"> 組み込みツールの機能 </Card> </CardGroup>