zenlm/zen-code-docs

Fork 0

mirror of https://github.com/zenlm/zen-code-docs.git synced 2026-10-30 14:58:40 +00:00

Files

T

pomelo-nwu ccdd00f0d9 feat: update docs

2025-09-12 17:56:29 +08:00

18 KiB

Raw Permalink Blame History

サブエージェント

サブエージェントは、Qwen Code 内で特定のタスクを処理するための専門的な AI アシスタントです。タスクに特化したプロンプト、ツール、および動作で構成された AI エージェントに、特定の作業を委任することができます。

サブエージェントとは？

サブエージェントとは、以下のような特徴を持つ独立した AI アシスタントです：

特定のタスクに特化 - 各サブエージェントは、特定の作業向けに特化したシステムプロンプトで構成されています
独立したコンテキストを持つ - メインチャットとは別に、独自の会話履歴を保持します
制御されたツールを使用 - 各サブエージェントが利用できるツールを個別に設定できます
自律的に動作 - タスクを割り当てられると、完了または失敗するまで独立して動作します
詳細なフィードバックを提供 - 進行状況、ツールの使用状況、実行統計をリアルタイムで確認できます

主要なメリット

タスクの専門化: 特定のワークフロー（テスト、ドキュメント作成、リファクタリングなど）に最適化されたエージェントを作成
コンテキストの分離: 専門的な作業をメインの会話から分離して管理
再利用性: エージェント設定をプロジェクトやセッション間で保存・再利用
アクセス制御: 各エージェントが使用できるツールを制限し、セキュリティと集中力を確保
進捗の可視化: リアルタイムの進捗更新でエージェントの実行状況を監視

サブエージェントの仕組み

設定: 振る舞い、ツール、システムプロンプトを定義したサブエージェント設定を作成
委譲: メインAIが適切なサブエージェントにタスクを自動的に委譲
実行: サブエージェントが独立して動作し、設定されたツールを使ってタスクを完了
結果: 結果と実行サマリーをメインの会話に戻す

はじめに

クイックスタート

最初のサブエージェントを作成する:
```
/agents create
```
ガイド付きウィザードに従って、専門的なエージェントを作成します。
既存のエージェントを管理する:
```
/agents manage
```
設定済みのサブエージェントを表示・管理できます。
サブエージェントを自動的に使用する: メインのAIに、サブエージェントの専門領域に合致するタスクを依頼するだけです。AIが自動的に適切な作業を委譲します。

使用例

User: "認証モジュールの包括的なテストを書いてください"

AI: これをテスト専門のサブエージェントに委譲します。
[Delegates to "testing-expert" subagent]
[テスト作成のリアルタイム進捗を表示]
[完了したテストファイルと実行サマリを返却]

管理

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}

新しいコントリビューターとエンドユーザーの両方がプロジェクトを理解できるような、
明確で包括的なドキュメントを作成することに重点を置いてください。

例

開発ワークフロー Agents

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: ベストプラクティス、セキュリティ問題、パフォーマンス、および保守性の観点からコードをレビューします
tools: read_file, read_many_files
---

あなたは品質、セキュリティ、保守性にフォーカスした経験豊富なコードレビュアーです。

レビュー基準:

- **コード構造**: オーガニゼーション、モジュール性、関心の分離
- **パフォーマンス**: アルゴリズムの効率性とリソース使用量
- **セキュリティ**: 脆弱性評価とセキュアコーディングプラクティス
- **ベストプラクティス**: 言語/フレームワーク固有の規約
- **エラーハンドリング**: 適切な例外処理とエッジケースのカバレッジ
- **可読性**: 明確な命名、コメント、コード構成
- **テスト**: テストカバレッジとテスト容易性の考慮事項

以下の形式で建設的なフィードバックを提供してください:

1. **重大な問題**: セキュリティ脆弱性、重大なバグ
2. **重要な改善点**: パフォーマンス問題、設計上の問題
3. **軽微な提案**: スタイル改善、リファクタリングの機会
4. **肯定的なフィードバック**: よく実装されたパターンと良いプラクティス

具体的な例と提案された解決策を含む、実行可能なフィードバックに焦点を当ててください。
影響度で問題の優先順位を付け、推奨事項の根拠を提供してください。

Use Cases:

"この認証実装のセキュリティ問題をレビューしてください"
"このデータベースクエリロジックのパフォーマンスへの影響をチェックしてください"
"コード構造を評価し、改善点を提案してください"

技術固有のエージェント

React Specialist

React 開発、hooks、コンポーネントパターンに最適化されています。

---
name: react-specialist
description: React 開発、hooks、コンポーネントパターン、および最新の React ベストプラクティスのエキスパート
tools: read_file, write_file, read_many_files, run_shell_command
---

あなたは最新の React 開発に精通した React スペシャリストです。

専門知識の範囲：

- **Component Design**: 関数コンポーネント、カスタムフック、コンポジションパターン
- **State Management**: useState、useReducer、Context API、外部ライブラリ
- **Performance**: React.memo、useMemo、useCallback、コード分割
- **Testing**: React Testing Library、Jest、コンポーネントテスト戦略
- **TypeScript Integration**: props、hooks、コンポーネントの適切な型付け
- **Modern Patterns**: Suspense、Error Boundaries、Concurrent Features

React のタスクでは：

1. デフォルトで関数コンポーネントと hooks を使用
2. 適切な TypeScript の型付けを実装
3. React のベストプラクティスと規約に従う
4. パフォーマンスへの影響を考慮
5. 適切なエラーハンドリングを含める
6. テスト可能で保守性の高いコードを書く

常に最新の React ベストプラクティスを維持し、非推奨のパターンは避けてください。
アクセシビリティとユーザーエクスペリエンスの考慮に重点を置いてください。

Use Cases:

"ソートとフィルタリング機能付きの再利用可能なデータテーブルコンポーネントを作成"
"キャッシング機能付きの API データ取得用カスタムフックを実装"
"このクラスコンポーネントを最新の React パターンにリファクタリング"

Python Expert

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, モッキング、テスト駆動開発
- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks
- **Async Programming**: asyncio, async/await パターン
- **Package Management**: pip, poetry, 仮想環境
- **Code Quality**: PEP 8, 型ヒント、pylint/flake8 による linting

Python のタスクにおいて：

1. PEP 8 スタイルガイドラインに従う
2. コードのドキュメント化のために型ヒントを使用する
3. 特定の例外による適切なエラーハンドリングを実装する
4. 包括的な docstring を書く
5. パフォーマンスとメモリ使用量を考慮する
6. 適切なロギングを含める
7. テスト可能でモジュール化されたコードを書く

コミュニティ標準に従った、クリーンで保守可能な Python コードの作成に焦点を当てます。

Use Cases:

"JWT トークンを使用したユーザー認証のための FastAPI サービスを作成する"
"pandas とエラーハンドリングによるデータ処理パイプラインを実装する"
"包括的なヘルプドキュメント付きの argparse を使用して CLI ツールを書く"

ベストプラクティス

設計原則

単一責任原則

各サブエージェントは、明確で集中した目的を持つべきです。

✅ 良い例:

---
name: testing-expert
description: Writes comprehensive unit tests and integration tests
---

❌ 避けるべき例:

---
name: general-helper
description: Helps with testing, documentation, code review, and deployment
---

理由: 目的に集中したエージェントの方が、より良い結果を生み出し、メンテナンスも容易になります。

明確な専門性

広範な能力よりも、特定の専門領域を定義しましょう。

✅ 良い例:

---
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を追加する
- テストが独立しており、任意の順序で実行できることを確認する

セキュリティに関する考慮事項

ツールの制限: サブエージェントは設定されたツールのみにアクセス可能
サンドボックス化: すべてのツール実行は、直接ツールを使用する場合と同じセキュリティモデルに従う
監査ログ: すべてのサブエージェントのアクションはログに記録され、リアルタイムで確認可能
アクセス制御: プロジェクトレベルおよびユーザーレベルの分離により、適切な境界を提供
機密情報: エージェント設定にシークレットや認証情報の含まれるのを避ける
本番環境: 本番環境と開発環境では別々のエージェントを検討すること

18 KiB Raw Permalink Blame History

サブエージェント

サブエージェントとは？

主要なメリット

サブエージェントの仕組み

はじめに

クイックスタート

使用例

管理

CLI コマンド

/agents create

/agents manage

保存場所

ファイル形式

基本構造

使用例

例

開発ワークフロー Agents

Testing Specialist

Documentation Writer

Code Reviewer

技術固有のエージェント

React Specialist

Python Expert

ベストプラクティス

設計原則

単一責任原則

明確な専門性

実行可能な説明文を書く

設定のベストプラクティス

System Prompt Guidelines

セキュリティに関する考慮事項

18 KiB

Raw Permalink Blame History

`/agents create`

`/agents manage`