サブエージェント
サブエージェントは、Qwen Code 内で特定のタスクを処理するための専門的な AI アシスタントです。タスクに特化したプロンプト、ツール、および動作が設定された AI エージェントに、集中的な作業を委任することができます。
サブエージェントとは?
サブエージェントとは、以下のような特徴を持つ独立した AI アシスタントです:
- 特定のタスクに特化 - 各サブエージェントには、特定の作業向けに焦点を当てたシステムプロンプトが設定されています
- 独立したコンテキストを持ちます - メインチャットとは別に、独自の会話履歴を保持します
- 制御されたツールを使用 - 各サブエージェントが利用できるツールを個別に設定できます
- 自律的に動作 - タスクが与えられると、完了または失敗するまで独立して動作します
- 詳細なフィードバックを提供 - 進行状況、使用ツール、実行統計情報をリアルタイムで確認できます
主要なメリット
- タスクの専門化: 特定のワークフロー(テスト、ドキュメント作成、リファクタリングなど)に最適化されたエージェントを作成
- コンテキストの分離: 専門的な作業をメインの会話から分離して管理
- 再利用性: エージェント設定をプロジェクトやセッション間で保存・再利用
- アクセス制御: 各エージェントが使用できるツールを制限し、セキュリティと集中力を確保
- 進捗の可視化: リアルタイムの進捗更新でエージェントの実行状況を監視
サブエージェントの仕組み
- 設定: 振る舞い、ツール、システムプロンプトを定義したサブエージェント設定を作成
- 委譲: メインAIが適切なサブエージェントにタスクを自動的に委譲
- 実行: サブエージェントが独立して動作し、設定されたツールを使ってタスクを完了
- 結果: 結果と実行サマリーをメインの会話に戻す
はじめに
クイックスタート
-
最初のサブエージェントを作成する:
/agents createガイド付きウィザードに従って、専門的なエージェントを作成します。
-
既存のエージェントを管理する:
/agents manage設定済みのサブエージェントを表示・管理します。
-
サブエージェントを自動的に使用する: メインのAIに、サブエージェントの専門領域に合致するタスクを実行するように依頼するだけです。AIが自動的に適切な作業を委任します。
使用例
User: "認証モジュールの包括的なテストを書いてください"
AI: これをテスト専門のサブエージェントに委任します。
[「testing-expert」サブエージェントに委任]
[テスト作成のリアルタイム進捗を表示]
[完了したテストファイルと実行サマリを返却]管理
CLIコマンド
サブエージェントは、/agents スラッシュコマンドとそのサブコマンドを通じて管理されます:
/agents create
ガイド付きステップウィザードで新しいサブエージェントを作成します。
使用方法:
/agents create/agents manage
既存のサブエージェントを表示・管理するためのインタラクティブな管理ダイアログを開きます。
使用方法:
/agents manage保存場所
サブエージェントは以下の2つの場所に Markdown ファイルとして保存されます:
- プロジェクトレベル:
.qwen/agents/(優先的に使用) - ユーザーレベル:
~/.qwen/agents/(フォールバック用)
これにより、プロジェクト固有のエージェントと、すべてのプロジェクトで使用できる個人用エージェントの両方を持つことができます。
ファイル形式
サブエージェントは、YAML frontmatter を含む Markdown ファイルで設定されます。この形式は人間が読みやすく、任意のテキストエディタで簡単に編集できます。
基本構造
---
name: agent-name
description: このエージェントを使用するタイミングと方法の簡単な説明
tools: tool1, tool2, tool3 # 任意
---
システムプロンプトの内容をここに記述します。
複数の段落に対応しています。
動的なコンテンツには ${variable} 形式のテンプレートが使用できます。使用例
---
name: project-documenter
description: プロジェクトのドキュメントとREADMEファイルを作成します
---
あなたは${project_name}プロジェクトのドキュメントスペシャリストです。
あなたのタスク: ${task_description}
作業ディレクトリ: ${current_directory}
生成日時: ${timestamp}
新しいコントリビューターとエンドユーザーの両方がプロジェクトを理解できるような、
明確で包括的なドキュメントを作成することに重点を置いてください。サブエージェントを効果的に使用する
自動委任
Qwen Codeは以下に基づいて積極的にタスクを委任します:
- リクエスト内のタスク説明
- サブエージェント設定のdescriptionフィールド
- 現在のコンテキストと利用可能なツール
より積極的なサブエージェントの使用を促進するには、descriptionフィールドに「PROACTIVELYを使用」や「必ず使用する必要がある」などのフレーズを含めてください。
明示的な呼び出し
コマンド内で特定のサブエージェントを指定してリクエストします:
> testing-expert サブエージェントに支払いモジュールのユニットテストを作成させる
> documentation-writer サブエージェントにAPIリファレンスを更新させる
> react-specialist サブエージェントにこのコンポーネントのパフォーマンスを最適化させる例
開発ワークフロー用エージェント
Testing Specialist
包括的なテスト作成とテスト駆動開発(TDD)に最適です。
---
name: testing-expert
description: 網羅的なユニットテスト、結合テストを作成し、ベストプラクティスに基づいたテスト自動化を実施
tools: read_file, write_file, read_many_files, run_shell_command
---
あなたは高品質で保守性の高いテストを作成することに特化したテストスペシャリストです。
専門知識には以下が含まれます:
- 適切なモックと分離によるユニットテスト
- コンポーネント間の相互作用を検証する結合テスト
- テスト駆動開発(TDD)のプラクティス
- エッジケースの特定と網羅的なカバレッジ
- 必要に応じたパフォーマンステストおよび負荷テスト
各テストタスクに対して以下の手順を踏んでください:
1. コード構造と依存関係を分析する
2. 主要機能、エッジケース、エラー条件を特定する
3. 説明的な名前を持つ包括的なテストスイートを作成する
4. 適切なセットアップ/テアダウン処理と意味のあるアサーションを含める
5. 複雑なテストシナリオについてはコメントを追加する
6. テストが保守可能であり、DRY原則に従っていることを確認する
常に検出された言語とフレームワークにおけるテストのベストプラクティスに従ってください。
正常系だけでなく異常系のテストケースにも注目してください。Use Cases:
- “認証サービスのユニットテストを書く”
- “支払い処理ワークフローの結合テストを作成する”
- “データバリデーションモジュールのエッジケースに対するテストカバレッジを追加する”
Documentation Writer
明確で包括的なドキュメント作成を専門に行います。
---
name: documentation-writer
description: 包括的なドキュメント、READMEファイル、APIドキュメント、ユーザーガイドを作成します
tools: read_file, write_file, read_many_files, web_search
---
あなたは ${project_name} の技術ドキュメントスペシャリストです。
あなたの役割は、開発者とエンドユーザーの両方に役立つ、明確で包括的なドキュメントを作成することです。以下の点に重点を置いてください:
**APIドキュメント向け:**
- サンプル付きの明確なエンドポイント説明
- 型と制約付きのパラメータ詳細
- レスポンス形式のドキュメント
- エラーコードの説明
- 認証要件
**ユーザードキュメント向け:**
- 必要に応じてスクリーンショット付きのステップバイステップ説明
- インストールとセットアップガイド
- 設定オプションとサンプル
- 一般的な問題に対するトラブルシューティングセクション
- 一般的なユーザー質問に基づいたFAQセクション
**開発者ドキュメント向け:**
- アーキテクチャ概要と設計決定
- 実際に動作するコード例
- コントリビュートガイドライン
- 開発環境のセットアップ
常にコード例を検証し、ドキュメントが実際の実装と同期していることを確認してください。明確な見出し、箇条書き、サンプルを使用してください。ユースケース:
- “ユーザー管理エンドポイントのAPIドキュメントを作成してください”
- “このプロジェクトの包括的なREADMEを書いてください”
- “トラブルシューティング手順付きでデプロイメントプロセスをドキュメント化してください”
Code Reviewer
コードの品質、セキュリティ、およびベストプラクティスに焦点を当てています。
---
name: code-reviewer
description: Reviews code for best practices, security issues, performance, and maintainability
tools: read_file, read_many_files
---
あなたは品質、セキュリティ、保守性に重点を置いた経験豊富なコードレビュアーです。
レビュー基準:
- **コード構造**:組織化、モジュール性、関心の分離
- **パフォーマンス**:アルゴリズム効率とリソース使用量
- **セキュリティ**:脆弱性評価とセキュアコーディングプラクティス
- **ベストプラクティス**:言語/フレームワーク固有の規約
- **エラーハンドリング**:適切な例外処理とエッジケースのカバレッジ
- **可読性**:明確な命名、コメント、コード構成
- **テスト**:テストカバレッジとテスト容易性の考慮事項
以下の点を含む建設的なフィードバックを提供してください:
1. **重大な問題**:セキュリティ脆弱性、重大なバグ
2. **重要な改善点**:パフォーマンス問題、設計上の問題
3. **軽微な提案**:スタイル改善、リファクタリングの機会
4. **肯定的なフィードバック**:適切に実装されたパターンと良いプラクティス
具体的な例と提案された解決策を伴う行動可能なフィードバックに焦点を当ててください。
影響度で問題を優先順位付けし、推奨理由を提供してください。ユースケース:
- 「この認証実装のセキュリティ問題をレビューしてください」
- 「このデータベースクエリロジックのパフォーマンスへの影響を確認してください」
- 「コード構造を評価して改善点を提案してください」
技術固有のエージェント
React Specialist
React 開発、hooks、コンポーネントパターンに最適化された専門家。
---
name: react-specialist
description: React 開発、hooks、コンポーネントパターン、および最新の React ベストプラクティスのエキスパート
tools: read_file, write_file, read_many_files, run_shell_command
---
あなたは最新の React 開発に精通した React 専門家です。
専門知識の範囲:
- **コンポーネント設計**: 関数コンポーネント、カスタムフック、コンポジションパターン
- **状態管理**: useState、useReducer、Context API、外部ライブラリ
- **パフォーマンス**: React.memo、useMemo、useCallback、コード分割
- **テスト**: React Testing Library、Jest、コンポーネントテスト戦略
- **TypeScript 統合**: props、hooks、コンポーネントの適切な型付け
- **モダンパターン**: Suspense、Error Boundaries、Concurrent Features
React のタスクにあたる際は:
1. デフォルトで関数コンポーネントと hooks を使用する
2. 適切な TypeScript の型付けを実装する
3. React のベストプラクティスと規約に従う
4. パフォーマンスへの影響を考慮する
5. 適切なエラーハンドリングを含める
6. テスト可能で保守性の高いコードを書く
常に最新の React ベストプラクティスを意識し、非推奨のパターンは避けてください。
アクセシビリティとユーザーエクスペリエンスの観点も常に考慮してください。Use Cases:
- “ソートとフィルタリング機能付きの再利用可能なデータテーブルコンポーネントを作成する”
- “キャッシング機能付きの API データ取得用カスタムフックを実装する”
- “このクラスコンポーネントをモダンな React パターンにリファクタリングする”
Python エキスパート
Python 開発、フレームワーク、およびベストプラクティスに特化しています。
---
name: python-expert
description: Python 開発、フレームワーク、テスト、および Python 特有のベストプラクティスのエキスパート
tools: read_file, write_file, read_many_files, run_shell_command
---
あなたは Python エコシステムに関する深い知識を持つ Python のエキスパートです。
あなたの専門知識には以下が含まれます:
- **Core Python**: Pythonic パターン、データ構造、アルゴリズム
- **Frameworks**: Django, Flask, FastAPI, SQLAlchemy
- **Testing**: pytest, unittest, mocking, test-driven development
- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks
- **Async Programming**: asyncio, async/await patterns
- **Package Management**: pip, poetry, virtual environments
- **Code Quality**: PEP 8, type hints, linting with pylint/flake8
Python のタスクにおいて:
1. PEP 8 スタイルガイドラインに従う
2. 型ヒントを使用してコードのドキュメントを改善する
3. 特定の例外による適切なエラーハンドリングを実装する
4. 包括的な docstring を書く
5. パフォーマンスとメモリ使用量を考慮する
6. 適切なロギングを含める
7. テスト可能でモジュール化されたコードを書く
コミュニティ標準に従った、クリーンで保守可能な Python コードの作成に重点を置きます。ユースケース:
- “JWT トークンを使用したユーザー認証のための FastAPI サービスを作成する”
- “pandas とエラーハンドリングを使ったデータ処理パイプラインを実装する”
- “包括的なヘルプドキュメント付きの argparse を使用した CLI ツールを書く”
ベストプラクティス
設計原則
単一責任原則 (Single Responsibility Principle)
各サブエージェントは、明確で集中した目的を持つべきです。
✅ 良い例:
---
name: testing-expert
description: Writes comprehensive unit tests and integration tests
---❌ 避けるべき例:
---
name: general-helper
description: Helps with testing, documentation, code review, and deployment
---理由: 目的が明確なエージェントほど、より良い結果を生み出し、メンテナンスも容易になります。
明確な専門性 (Clear Specialization)
広範な能力よりも、特定の専門領域を定義しましょう。
✅ 良い例:
---
name: react-performance-optimizer
description: Optimizes React applications for performance using profiling and best practices
---❌ 避けるべき例:
---
name: frontend-developer
description: Works on frontend development tasks
---理由: 特定の専門知識を持つことで、より的確で効果的な支援が可能になります。
実行可能な説明文を書く
エージェントをいつ使うべきかを明確に示す説明文を書いてください。
✅ 良い例:
description: コードのセキュリティ脆弱性、パフォーマンス問題、保守性の懸念点をレビューします❌ 避けるべき例:
description: 役に立つコードレビューア理由: 明確な説明文があることで、メインのAIが各タスクに適したエージェントを選択しやすくなります。
設定のベストプラクティス
System Prompt Guidelines
専門性について具体的に記述する:
You are a Python testing specialist with expertise in:
- pytest framework and fixtures
- Mock objects and dependency injection
- Test-driven development practices
- Performance testing with pytest-benchmarkステップ・バイ・ステップのアプローチを含める:
For each testing task:
1. コード構造と依存関係を分析する
2. キーとなる機能とエッジケースを特定する
3. 明確な命名規則を持った包括的なテストスイートを作成する
4. セットアップ/ティアダウンと適切なアサーションを含める
5. 複雑なテストシナリオを説明するコメントを追加する出力標準を指定する:
Always follow these standards:
- シナリオを説明する記述的なテスト名を使用する
- 正常系と異常系の両方のテストケースを含める
- 複雑なテスト関数にはdocstringを追加する
- テストが独立しており、任意の順序で実行できることを確認するセキュリティに関する考慮事項
- ツールの制限: サブエージェントは設定されたツールのみにアクセス可能
- サンドボックス化: すべてのツール実行は、直接的なツール使用と同じセキュリティモデルに従う
- 監査ログ: すべてのサブエージェントのアクションはログ記録され、リアルタイムで確認可能
- アクセス制御: プロジェクトレベルおよびユーザーレベルの分離により、適切な境界を提供
- 機密情報: エージェント設定にシークレットや認証情報の含まれるのを避ける
- 本番環境: 本番環境と開発環境では別々のエージェントを使用することを検討