サブエージェント

サブエージェントは、Qwen Code 内で特定の種類のタスクを処理するための専門化されたAIアシスタントです。タスク固有のプロンプト、ツール、動作を設定したAIエージェントに、集中した作業を委任できます。

サブエージェントとは

サブエージェントは独立したAIアシスタントであり、以下の特徴があります:

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

Claude Code と Codex サブエージェント

組み込みの claude-code および codex エージェントは、別途インストールされたネイティブツールに委任します。Claude Code は claude-agent-acp アダプターで、Codex は codex 実行ファイルでインストールおよび認証し、実行ファイルを PATH で利用可能にします。これらのエージェントはネイティブのモデルと認証設定を使用します。実行ファイルがない場合、Qwen Code は独自のモデルにフォールバックしません。

どちらのエージェントもデフォルトでフォアグラウンド実行です。バックグラウンドの完了通知を受け取るには、run_in_background: true を設定します。信頼されたワークスペースが必要で、セーフモードでは利用できません。どちらのエグゼキューターも macOS/Linux（WSL を含む）をサポートします。ネイティブ Windows の起動は、プラットフォームガイダンスを表示して起動前に拒否されます。

Claude Code は ACP エグゼキューターを使用し、セッションが保持されている間は継続的な入力を受け付けます。Codex は単一のタスクに一時限りのアプリサーバースレッドを使用し、最終的な回答を返します。Codex タスクはメッセージを受け取ったり再開したりできません。代わりに新しいタスクを開始してください。Codex では、ネイティブツールの進捗、トークン数、コストは報告されません。Qwen Code を再起動した後、ネイティブセッションを復元することはできません。

カスタム Codex エージェントには、既存の executor フロントマターを使用します:


---
name: codex-review
description: Review code with Codex
executor:
  kind: codex
  command: codex
background: false
---
 
Review the changes and report verified defects.

executor.args を省略すると codex app-server --stdio が起動します。指定された引数がそのデフォルトを置き換えます。カスタム Claude Code エージェントには kind: acp と command: claude-agent-acp を使用します。外部エグゼキューターでは、Qwen モデルのオーバーライド、ツールリスト、サブエージェントフック、maxTurns、フォーク履歴、チーム、およびワークフローはサポートされていません。ワークツリーの起動は既存のエージェント分離ライフサイクルを使用し、選択されたワークツリーでネイティブプロセスを実行します。

Codex は無人で実行されます。エージェントオーバーライドがない場合、デフォルト、プラン、および自動セッションは読み取り専用サンドボックスを使用します。Qwen の AUTO クラシファイアはネイティブコマンドを検査しません。中間の Qwen サブエージェントモードは、ネストされた委任中にネイティブアクセスを付与しません。ワークスペースへの書き込みと無人のワークスペースコマンドを許可するには、セッションまたは Codex エージェント定義で auto-edit を明示的に選択します。フルアクセスには yolo を選択します。すでに auto-edit または yolo になっているセッションは、より厳しいエージェント定義よりも優先されます。他の有効な承認モードは拒否されます。追加の権限またはユーザー入力のネイティブリクエストは拒否されます。設定された runConfig.max_time_minutes が実行時間を制限します。エグゼキューターはキャンセル時にプロセスのクリーンアップを待ちます。共有バックグラウンドキャンセル通知は、5秒のフォールバックでより早く到着する場合があります。

Fork サブエージェント

名前付きサブエージェントに加えて、Qwen Code は フォーク をサポートしています。これは subagent_type: "fork" で明示的に選択します。フォークは親の完全な会話コンテキストを継承し、通常はバックグラウンドでデタッチされて実行されます。フォークはインタラクティブセッションとヘッドレスセッションの両方で動作します。ヘッドレスフォークは常にバックグラウンドパスを使用します。subagent_type を省略した場合、フォークにはなりません。汎用サブエージェントが起動されます。トップレベルの名前付きサブエージェントはデフォルトでバックグラウンドで実行され、完了通知を通じて結果を配信します。現在のターンが通常のサブエージェントの結果をインラインで待つ必要がある場合は、run_in_background: false を設定します。

`fork_turns` によるフォークコンテキスト

fork_turns を受け付けるのは subagent_type: "fork" のみです。

省略または all を使用すると、親の会話全体を継承します。
"3" のような正の整数文字列を指定すると、直近のリアルユーザーターンを指定数だけ継承します。

ツールレスポンスと純粋なシステムリマインダーはユーザーターンとしてカウントされません。通常の名前付きサブエージェントやエージェントチームのチームメートは fork_turns を受け付けません。それらは個別の会話コンテキストを保持します。

`fork_tools` によるフォークツールの実行制限

fork_tools を受け付けるのは subagent_type: "fork" のみです。配列には、read_file や grep_search などの正確な正規ツール名や、mcp__github などの MCP サーバーパターンを含めることができます。フォークは制限なしのフォークと同じモデルから見えるツール宣言を受け取ります（プロンプトキャッシュプレフィックスを保持するため）が、タスクプロンプトで制限が識別され、fork_tools でマッチしない呼び出しはスケジューリングまたは承認前に拒否されます。

フォークは ask_user_question を実行しません。ユーザー入力が必要な場合、親エージェントにブロッカーを報告します。
fork_tools を省略すると、他のすべての継承ツールが許可されます。
空の配列はすべてのツール呼び出しを拒否します。
* は受け付けられません。他のすべての実行可能な継承ツールを許可するには、fork_tools を省略してください。
ツール名に前後の空白を含めることはできません。ワイルドカードは mcp__* または mcp__github__read_* のような末尾の MCP ツールプレフィックスパターンとしてのみ受け付けられます。
mcp__* は、リストされていない組み込みツールを拒否しつつ、すべての MCP ツールを意図的に許可します。
シェルコマンド引数パターンはサポートされていません。run_shell_command をリストすると、そのツールが通常の権限チェックを進むことができますが、コマンドを事前承認することにはなりません。

これは、呼び出し元が提供する呼び出しごとの制限です。子フォークの機能を狭めますが、呼び出し元がリストを省略または拡張できるため、管理者が強制するセキュリティサンドボックスではありません。

`fork_profile` によるフォーク制限の再利用

プロジェクトは名前付きフォーク制限を .qwen/fork-profiles/<name>.md に保存し、fork_profile で選択できます。これは、複数の呼び出しで同じツール境界とタスクガイダンスが必要な場合に便利です。


---
name: ro-research
tools:
  - read_file
  - grep_search
  - glob
  - mcp__search__*
promptHint: |
  Work read-only. Prefer targeted searches and cite file evidence.
---

その後、フォークを次のように起動します。


agent(description="Research", prompt="Inspect the retry path", subagent_type="fork", fork_profile="ro-research")

fork_profile はフォークに対してのみ有効であり、fork_tools や名前付きチームメートと組み合わせることはできません。
プロファイルは現在プロジェクトのみです。リクエストされた名前、ファイル名、フロントマターの name は完全に一致する必要があります。プロファイルは .qwen/fork-profiles/ 内の通常のファイルに解決される必要があり、64 KiB を超えることはできません。
tools は必須であり、fork_tools のルール（空配列の拒否動作を含む）に従います。
promptHint はオプションで、200文字に制限されています。エスケープされ、フォークディレクティブの後、信頼できるツール制限の前に、プロジェクト提供のガイダンスとしてフレーミングされます。継承されたシステム指示やモデルから見えるツール宣言を変更することはありません。プロファイルファイルはフロントマターのみであるため、閉じ --- の後の非空白の Markdown は黙って無視される代わりに拒否されます。
プロファイルは起動時に1回だけ解決されます。保持されたフォークは、プロジェクトファイルが後で変更されても、解決されたツールのスナップショットで続行します。
プロジェクトフォークプロファイルは、ローカルカスタマイズを無効にするセーフモードとベアモードでは利用できません。

fork_tools と同様に、フォークプロファイルは管理者サンドボックスではなく、呼び出し元が選択する制限です。オプションのプロンプトガイダンスはプロジェクトが管理するコンテンツです。

フォークと名前付きサブエージェントの違い

	名前付きサブエージェント	Fork サブエージェント
コンテキスト	親の会話履歴なしで新規開始	デフォルトでは親の履歴をすべて継承。`fork_turns` で直近の範囲を選択可能
システムプロンプト	自身の設定済みプロンプトを使用	親の正確なシステムプロンプトを使用（キャッシュ共有のため）
ツール	インタラクティブな質問ツールなしの設定済み宣言セット	キャッシュのために親由来の宣言セットを保持。実行は常に `ask_user_question` を拒否し、`fork_tools` または `fork_profile` で宣言を変更せずに独立して narrow 可能
実行	デフォルトでバックグラウンド。明示的なフォアグラウンドのオプトアウトをサポート	常にデタッチ。親は即座に続行
ユースケース	専門タスク（テスト、ドキュメント）	現在のコンテキストが必要な並列タスク

フォークが使用される場面

AI は以下の必要がある場合に自動的にフォークを使用します:

複数の調査タスクを並列実行する場合（例：「モジュールA、B、Cを調査してください」）
メインの会話を続けながらバックグラウンド作業を実行する場合
現在の会話コンテキストの理解が必要なタスクを委任する場合

プロンプトキャッシュの共有

すべてのフォークは親のAPIリクエストプレフィックス（システムプロンプト、ツール、会話履歴）をそのまま共有するため、DashScope プロンプトキャッシュがヒットします。3つのフォークが並列実行されると、共有プレフィックスは一度キャッシュされて再利用され、独立したサブエージェントと比較してトークンコストを80%以上削減します。

再帰的委任の防止

フォークの子は、それ以降のサブエージェントを生成できません。これは実行時に強制されます。フォークが Agent ツールを呼び出すと、タスクを直接実行するように指示するエラーを受け取ります。

現在の制限事項

ワークツリーの分離なし: フォークは親の作業ディレクトリを共有します。複数のフォークからの同時ファイル変更は競合する可能性があります。

主な利点

タスクの特化: 特定のワークフロー（テスト、ドキュメント、リファクタリングなど）に最適化されたエージェントを作成
コンテキストの分離: 専門的な作業をメインの会話から分離して保持
コンテキストの継承: フォークサブエージェントはデフォルトで完全な会話を継承し、直近の親ターン数を範囲指定して選択可能
プロンプトキャッシュの共有: フォークサブエージェントは親のキャッシュプレフィックスを共有し、トークンコストを削減
再利用性: エージェント設定をプロジェクトやセッション間で保存および再利用
アクセス制御: 各エージェントが使用できるツールをセキュリティと集中力のために制限
進捗の可視化: リアルタイムの進捗更新でエージェントの実行を監視

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

設定: サブエージェントの動作、ツール、システムプロンプトを定義する設定を作成します
委任: メインAIは自動的に適切なサブエージェントにタスクを委任できます。また、親の会話コンテキストが必要な場合は自身をフォーク（subagent_type: "fork"）できます
実行: サブエージェントは独立して動作し、設定されたツールを使用してタスクを完了します
結果: バックグラウンド実行は結果を含む完了通知をメインの会話に送信します。フォアグラウンドの通常サブエージェントは結果をインラインで返します
継続: メインAIは list_agents を使用してバックグラウンドエージェントを見つけ、send_message を使用して実行中、一時停止中、または完了したエージェントを継続できます

バックグラウンドエージェントの継続

トップレベルの通常サブエージェントはデフォルトでバックグラウンドで実行されます。バックグラウンドエージェントが完了した後、Qwen Code は重複エージェントを起動せずに関連作業を継続できる十分な状態を保持します。

list_agents は、現在のセッション内のアドレス指定可能なバックグラウンドエージェントを返します。これには、再開されたセッションで復元された互換性のあるエージェントも含まれます。各エントリには task_id、ステータス、およびメッセージを受け取れるかどうかが含まれます。
send_message に task_id を指定すると、実行中のエージェントにメッセージをキューイングし、一時停止中のエージェントを再開し、または完了したエージェントを継続します。完了したエージェントは、利用可能な場合は常駐ランタイムを再利用し、そうでない場合は保持されたトランスクリプトから復活します。
継続されたエージェントは、別の完了通知を通じて次の結果を報告します。

セッションが復元されると、互換性のあるバックグラウンドエージェントがセッションロスターに再追加されます。タスクは表示されても継続できない場合があります。保持された状態がないか、互換性がない場合です。list_agents はその場合に理由を報告します。

関連するフォローアップ作業には継続を使用してください。タスクが無関係であるか、前のエージェントを再開できない場合は、新しいエージェントを起動してください。

通知キュー

インタラクティブ TUI および ACP セッションでは、バックグラウンドエージェント、シェル、モニター、ワークフローからの完了通知がキューを共有し、セッションがアイドルになるとモデルターンにドレインされます。これらのキューは最大20個の通知を保持するため、ノイズの多いプロデューサーが無限のバックログを蓄積することはありません。ヘッドレス CLI のローカルキューはこのルールによって上限が設定されません。

21番目の通知が到着すると、Qwen Code はまず中間モニターのパルスを削除します（モニターの次のポーリングがそれを置き換えるため）。それ以外の場合、最も古いキューイングされた通知が削除されます。エージェントの結果、ワークフローの結果、およびスケジュールされたプロンプトは、インタラクティブ TUI では決して削除されません。代わりに、それを置き換える通知はドロップされます。同様に、ターミナル結果のみがキューイングされているときに到着するパルスもドロップされます。

破棄された通知は静かにドロップされるのではなく、報告されます。サマリーは、ライフトランスクリプトの次の通知の前に表示されます。ACP はそれをそのターンのモデル入力にもプレフィックスします。TUI はそれを次の通知バッチまで保持するため、cron プロンプトはスラッシュ、シェル、および @ の前処理をそのまま通過します。デーモン通知は確認前に記録されるため、リロード後、その永続レコードは後のオーバーフローサマリーより前に表示される場合があります。ACP は、セッションがクリアまたは切り替えられた場合、またはクライアントが通知ターンをキャンセルまたはプリエンプトした場合、保留中のサマリーを破棄できます。通知を破棄しても、そのタスクが停止または削除されることはなく、完了したタスクは結果を保持します。サマリーは、検査するタスクがある場合、/tasks とタスク出力ファイルを指します。破棄されたスケジュールされたプロンプトは配信されなかったものであり、再試行されません。記録されたがライブで配信できなかったデーモン通知は、セッションのトランスクリプトで引き続き利用可能であり、失われた通知とは別に報告されます。

エージェントの作業ディレクトリ

名前付きの通常サブエージェントの場合、working_dir はエージェントを現在のリポジトリ内の既存の git ワークツリーに固定します。相対パスはカレントディレクトリから解決され、ワークツリーはすでに git に登録されており、リポジトリ内に存在している必要があります。

working_dir は subagent_type: "fork" と組み合わせることはできません。呼び出し元所有の working_dir の起動はフォアグラウンドで実行されます。Qwen Code がそのワークツリーのライフサイクルを所有していないためです。明示的な run_in_background: true リクエストは拒否され、設定されたバックグラウンドのデフォルト（サブエージェント定義の background: true）はトップレベルで拒否され、ネストされている場合はフォアグラウンドにダウングレードされます。working_dir と isolation: "worktree" の両方が指定された場合、Qwen Code は別のワークツリーを作成する代わりに、呼び出し元が所有するワークツリーを再利用します。ワークフローンスクリプトは意図的に厳格になっています。workingDir と isolation の両方を受け取ったワークフローの agent() 呼び出しは、isolation を無視して実行する代わりに拒否されます。

はじめに

クイックスタート

最初のサブエージェントを作成:

/agents create

ガイド付きウィザードに従って、専門エージェントを作成します。
既存のエージェントを管理:

/agents manage

設定済みのサブエージェントを表示および管理します。
サブエージェントを自動的に使用: サブエージェントの専門分野に一致するタスクをメインAIに依頼するだけで、AIが自動的に適切な作業を委任します。

使用例


ユーザー: "認証モジュールの包括的なテストを書いてください"
AI: このタスクはテスト専門のサブエージェントに委任します。
[サブエージェント "testing-expert" に委任]
[テスト作成のリアルタイム進捗を表示]
[完了したテストファイルと実行サマリーを返す]

管理

CLI コマンド

サブエージェントは /agents スラッシュコマンドとそのサブコマンドで管理します:

使用方法: /agents create。ガイド付きステップウィザードを通じて新しいサブエージェントを作成します。

使用方法: /agents manage。インタラクティブな管理ダイアログを開き、既存のサブエージェントを表示および管理します。

保存場所

サブエージェントは複数の場所にMarkdownファイルとして保存されます:

プロジェクトレベル: .qwen/agents/（最優先）
ユーザーレベル: ~/.qwen/agents/（フォールバック）
拡張機能レベル: インストールされた拡張機能によって提供

これにより、プロジェクト固有のエージェント、すべてのプロジェクトで機能する個人用エージェント、および特殊な機能を追加する拡張機能提供のエージェントを持つことができます。

拡張機能サブエージェント

拡張機能は、有効にすると利用可能になるカスタムサブエージェントを提供できます。これらのエージェントは拡張機能の agents/ ディレクトリに保存され、個人用およびプロジェクト用エージェントと同じ形式に従います。

拡張機能サブエージェント:

拡張機能が有効になると自動的に検出されます
/agents manage ダイアログの「拡張機能エージェント」セクションに表示されます
直接編集することはできません（代わりに拡張機能のソースを編集してください）
ユーザー定義エージェントと同じ設定形式に従います

サブエージェントを提供する拡張機能を確認するには、拡張機能の qwen-extension.json ファイルの agents フィールドを確認してください。

ファイル形式

サブエージェントはYAMLフロントマター付きのMarkdownファイルを使用して設定します。この形式は人間が読みやすく、任意のテキストエディタで簡単に編集できます。

基本構造


---
name: agent-name
description: このエージェントをいつ、どのように使用するかの簡単な説明
model: inherit # オプション: inherit, fast, modelId, または authType:modelId
approvalMode: auto-edit # オプション: default, plan, auto-edit, yolo, bubble
tools:         # オプション: 許可リストのツール
  - tool1
  - tool2
disallowedTools: # オプション: ブロックリストのツール
  - tool3
---

システムプロンプトの内容をここに記述します。
複数の段落がサポートされています。

モデル選択

オプションの model フロントマターフィールドを使用して、サブエージェントが使用するモデルを制御します:

inherit: メインの会話と同じモデルを使用します。
フィールドを省略: inherit と同じ。
fast: 設定された fastModel を使用します。有効なfastモデルが設定されていない場合、サブエージェントは inherit にフォールバックします。
glm-5: そのモデルIDを使用します。Qwen Codeは最初にメインの会話の認証タイプを確認します。そのモデルが利用できない場合、別の設定済みプロバイダーからモデルを解決できます。
openai:gpt-4o: 明示的なプロバイダーとモデルIDを使用します。これは、サブエージェントをメインの会話とは異なる認証タイプで登録されたモデルで実行する必要がある場合に便利です。

例:


---
name: fast-reviewer
description: 設定された高速モデルで小さな差分をレビューします
model: fast
tools:
  - read_file
  - grep_search
---


---
name: openai-researcher
description: 調査タスクにOpenAI互換プロバイダーを使用します
model: openai:gpt-4o
tools:
  - read_file
  - grep_search
  - glob
---

fast セレクターは、settings.json または /model --fast で設定された同じ fastModel 設定を使用します。その設定自体が、openai:deepseek-v4-flash のように別の設定済み認証タイプのモデルを参照する場合があります。セレクターが別の認証タイプに解決されると、Qwen Codeはそのサブエージェントリクエスト用に専用のランタイムプロバイダーを作成し、プロバイダーにはベアのモデルIDのみを送信します。

組み込みの Explore エージェントは、デフォルトでメインセッションのモデルを継承します。その組み込みエージェントのみ異なるモデルを選択するには、settings.json で agents.builtin.exploreModel を設定し、Qwen Code を再起動します。

以前のバージョンでは、デフォルトで Explore に fastModel を使用していました。その動作を維持するには、agents.builtin.exploreModel を fast に設定します。


{
  "agents": {
    "builtin": {
      "exploreModel": "fast"
    }
  }
}

この設定は、上記と同じセレクターを受け付けます。これは Qwen Code が組み込みの Explore 定義を解決するときにのみ適用されます。Explore という名前のセッション、プロジェクト、ユーザー、または拡張エージェントは、独自の model 設定を保持します。

モデルに具体的なモデルIDを公開せずにユーザー定義のグレードから選択させるには、agents.modelGrades を設定し、オプションで agents.allowedGrades で制限します。


{
  "agents": {
    "modelGrades": {
      "small": "fast",
      "high": "qwen-max"
    },
    "allowedGrades": ["small", "high"]
  }
}

Agent ツールは、通常のサブエージェントに対して model: "small" または model: "high" を受け付けます。不明、許可されていない、フォーク、および名前付きチームメートのグレード選択は拒否されます。カスタムエージェントの明示的なモデルは、引き続きグレードよりも優先されます。

許可モード

オプションの approvalMode フロントマターフィールドを使用して、サブエージェントのツール呼び出しがどのように承認されるかを制御します。有効な値:

default: ツールはインタラクティブな承認が必要（メインセッションのデフォルトと同じ）
plan: 分析のみモード — エージェントは計画を立てますが、変更は実行しません
auto-edit: ツールはプロンプトなしで自動承認（ほとんどのエージェントに推奨）
yolo: すべてのツールが自動承認（破壊的な可能性があるものを含む）
bubble: バックグラウンドエージェントのツール承認が親セッションに表示されます

このフィールドを省略した場合、サブエージェントの許可モードは自動的に決定されます:

親セッションが yolo または auto-edit モードの場合、サブエージェントはそのモードを継承します。許可的な親は許可的なままです。
親セッションが plan モードの場合、サブエージェントはplanモードのままです。分析のみのセッションは、委任されたエージェントを通じてファイルを変更できません。
親セッションが default モード（信頼されたフォルダ内）の場合、サブエージェントは auto-edit を取得し、自律的に動作できます。

approvalMode を設定した場合でも、親の許可モードが優先されます。たとえば、親がyoloモードの場合、approvalMode: plan のサブエージェントでもyoloモードで実行されます。


---
name: cautious-reviewer
description: 変更を行わずにコードをレビューします
approvalMode: plan
tools:
  - read_file
  - grep_search
  - glob
---

あなたはコードレビュアーです。コードを分析し、結果を報告してください。
ファイルは変更しないでください。

ツール設定

tools および disallowedTools を使用して、サブエージェントがアクセスできるツールを制御します。

tools (許可リスト): 指定すると、サブエージェントはリストされたツールのみを使用できます。省略すると、サブエージェントは親セッションから利用可能なすべてのツールを継承します。


---
name: reader
description: コード探索のための読み取り専用エージェント
tools:
  - read_file
  - grep_search
  - glob
  - web_fetch
---

disallowedTools (ブロックリスト): 指定すると、リストされたツールがサブエージェントのツールプールから削除されます。これは、すべての許可ツールをリストせずに「X以外のすべて」を許可したい場合に便利です。


---
name: safe-worker
description: ファイルを変更できないエージェント
disallowedTools:
  - write_file
  - edit
  - run_shell_command
---

tools と disallowedTools の両方が設定されている場合、許可リストが最初に適用され、次にブロックリストがそのセットから削除されます。

MCP ツール も同じルールに従います。サブエージェントに tools リストがない場合、親セッションからすべてのMCPツールを継承します。サブエージェントに明示的な tools リストがある場合、そのリストに明示的に名前が含まれているMCPツールのみを取得します。

disallowedTools フィールドは、MCPサーバーレベルのパターンをサポートします:

mcp__server__tool_name — 特定のMCPツールをブロック
mcp__server — そのMCPサーバーのすべてのツールをブロック


---
name: no-slack
description: Slackアクセスがないエージェント
disallowedTools:
  - mcp__slack
---

Claude Code 互換性フィールド

Qwen Code は、以下の Claude Code 2.1.168 フロントマターフィールドを受け入れます。これにより、CCのエージェントファイルを .qwen/agents/ にドロップすると、サポートされているフィールドが同一に解析されます。無効な値を持つオプションフィールドは、拒否されるのではなく解析時に静かにドロップされます。これはCCが使用するのと同じ寛容な姿勢です。

フィールド	型	備考
`permissionMode`	enum string	`acceptEdits`, `auto`, `bypassPermissions`, `default`, `dontAsk`, `plan`。解析時に `approvalMode` にマッピングされます。両方が設定されている場合、明示的な `approvalMode` が優先されます。
`maxTurns`	正の整数	エージェントのターン予算を制限します。実行時に `runConfig.max_turns` に配線されます。両方が設定されている場合、トップレベルのフィールドが優先されます。保存時に、レガシーのネストされた値はファイルから削除され、2つの真実のソースを防ぎます。
`color`	enum string	表示色。許可リスト: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` (CCの `_Y` をミラー)。レガシーのqwenセンチネル `auto` は後方互換性のために保持されます。その他の値は解析時に静かにドロップされます。
`mcpServers`	レコード of specs	エージェントごとのMCPサーバーオーバーライド。エージェントが起動するときにセッションレベルのMCPサーバーセットとマージされます。キーが衝突した場合、エージェントの仕様が優先されます（CCの `scope: 'agent'` セマンティクスに一致）。不正なエントリは、エージェント全体を失敗させるのではなく、キーごとに警告付きでドロップされます。
`hooks`	レコード of 配列	エージェントごとのフック。キーはCCフックイベント名（`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, …）。値は、`settings.json` の `hooks` フィールドと同じ形状の `{ matcher?, hooks: [...] }` 定義の配列です。エージェントの実行中に登録され、停止時に削除されます。

上記すべてを使用した例:


---
name: rigorous-reviewer
description: ターン制限付きの詳細なコードレビュー
permissionMode: plan
maxTurns: 50
color: cyan
tools:
  - read_file
  - grep_search
  - glob
mcpServers:
  filesystem:
    type: stdio
    command: node
    args: [/usr/local/lib/mcp-fs/server.js]
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: echo "review-agent about to run a shell command"
---

あなたはコードレビュアーです。コードを徹底的に分析し、重大度順に結果を報告してください。

残りのCCフロントマターフィールド（effort, skills, initialPrompt, memory, isolation）は、宣言的エージェント設計ドキュメントに文書化されており、前提となるインフラストラクチャが存在するようになったら、後続のPRで実装されます（effort はモデルレイヤーのパラメーターが必要、memory はスコープ付きメモリサブシステムが必要、--agent CLIフラグは initialPrompt を有効にする、など）。

hooks v1 の制限事項。 hooks を宣言するサブエージェントが実行されている間、そのフックエントリは、そのサブエージェント自身のツール呼び出しだけでなく、セッション内のすべての一致するイベントに対して発火します。異なるエージェントごとのフックセットを持つ2つのサブエージェントが同時に実行される場合、両方のセットが両方のエージェントに対して発火します。エージェントごとのスコープフィルタリングは後続の対応に委ねられます。v1では、エージェントの実行期間中グローバルに発火しても安全なエージェントごとのフック（例: ログ記録）を、動作を変更するフックよりも優先してください。

使用例


---
name: project-documenter
description: プロジェクトのドキュメントとREADMEファイルを作成します
---

あなたはドキュメンテーションスペシャリストです。

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

サブエージェントを効果的に使用する

自動委任

Qwen Code は以下に基づいて積極的にタスクを委任します:

リクエスト内のタスク説明
サブエージェント設定の description フィールド
現在のコンテキストと利用可能なツール

より積極的なサブエージェントの使用を促進するには、description フィールドに「use PROACTIVELY」や「MUST BE USED」などのフレーズを含めてください。

明示的な呼び出し

コマンドで特定のサブエージェントを言及して呼び出します:


testing-expert サブエージェントに決済モジュールの単体テストを作成させてください
documentation-writer サブエージェントにAPIリファレンスを更新させてください
react-specialist サブエージェントにこのコンポーネントのパフォーマンスを最適化させてください

例

開発ワークフローエージェント

テストスペシャリスト

包括的なテスト作成とテスト駆動開発に最適です。


---
name: testing-expert
description: 包括的な単体テスト、統合テストを作成し、ベストプラクティスでテスト自動化を処理します
tools:
  - read_file
  - write_file
  - read_many_files
  - run_shell_command
---

あなたはテストスペシャリストです。高品質で保守可能なテストの作成に焦点を当てています。

専門知識には以下が含まれます:

- 適切なモックと分離を備えた単体テスト
- コンポーネント間の相互作用のための統合テスト
- テスト駆動開発のプラクティス
- エッジケースの特定と包括的なカバレッジ
- パフォーマンステストとロードテスト（適切な場合）

各テストタスクについて:

1. コード構造と依存関係を分析する
2. 主要機能、エッジケース、エラー条件を特定する
3. 説明的な名前を持つ包括的なテストスイートを作成する
4. 適切なセットアップ/ティアダウンと意味のあるアサーションを含める
5. 複雑なテストシナリオを説明するコメントを追加する
6. テストが保守可能でDRY原則に従っていることを確認する

検出された言語とフレームワークのテストベストプラクティスに常に従ってください。
ポジティブテストケースとネガティブテストケースの両方に焦点を当ててください。

使用例:

「認証サービスの単体テストを書いてください」
「支払い処理ワークフローの統合テストを作成してください」
「データ検証モジュールのエッジケースのテストカバレッジを追加してください」

ドキュメントライター

明確で包括的なドキュメントの作成に特化しています。


---
name: documentation-writer
description: 包括的なドキュメント、READMEファイル、APIドキュメント、ユーザーガイドを作成します
tools:
  - read_file
  - write_file
  - read_many_files
---

あなたはテクニカルドキュメンテーションスペシャリストです。

あなたの役割は、開発者とエンドユーザーの両方に役立つ、
明確で包括的なドキュメントを作成することです。以下に焦点を当ててください:

**APIドキュメントの場合:**

- 例を用いた明確なエンドポイントの説明
- 型と制約を含むパラメーターの詳細
- レスポンス形式のドキュメント
- エラーコードの説明
- 認証要件

**ユーザードキュメントの場合:**

- 役立つ場合はスクリーンショット付きのステップバイステップの手順
- インストールとセットアップガイド
- 設定オプションと例
- 一般的な問題のトラブルシューティングセクション
- よくあるユーザー質問に基づくFAQセクション

**開発者ドキュメントの場合:**

- アーキテクチャの概要と設計上の決定
- 実際に動作するコード例
- コントリビューションガイドライン
- 開発環境のセットアップ

コード例を常に検証し、ドキュメントが実際の実装と最新の状態を保つようにしてください。明確な見出し、箇条書き、例を使用してください。

使用例:

「ユーザー管理エンドポイントのAPIドキュメントを作成してください」
「このプロジェクトの包括的なREADMEを書いてください」
「トラブルシューティング手順を含むデプロイメントプロセスを文書化してください」

コードレビュアー

コード品質、セキュリティ、ベストプラクティスに焦点を当てています。


---
name: code-reviewer
description: コードをベストプラクティス、セキュリティ問題、パフォーマンス、保守性についてレビューします
tools:
  - read_file
  - read_many_files
---

あなたは経験豊富なコードレビュアーであり、品質、セキュリティ、保守性に焦点を当てています。

レビュー基準:

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

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

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

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

使用例:

「この認証実装をセキュリティ上の問題についてレビューする」
「このデータベースクエリロジックのパフォーマンスへの影響を確認する」
「コード構造を評価し、改善点を提案する」

テクノロジー特化型エージェント

Reactスペシャリスト

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


---
name: react-specialist
description: React開発、フック、コンポーネントパターン、モダン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、フック、コンポーネントの適切な型付け
- **モダンパターン**: Suspense、Error Boundaries、Concurrent Features

Reactタスクの場合:

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

常にReactのベストプラクティスに追従し、非推奨のパターンを避けてください。
アクセシビリティとユーザーエクスペリエンスの考慮に焦点を当ててください。

使用例:

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

Pythonエキスパート

Python開発、フレームワーク、ベストプラクティスに特化しています。


---
name: python-expert
description: Python開発、フレームワーク、テスト、Python固有のベストプラクティスの専門家
tools:
  - read_file
  - write_file
  - read_many_files
  - run_shell_command
---

あなたはPythonエコシステムに深い知識を持つPythonエキスパートです。

専門知識には以下が含まれます:

- **Pythonコア**: Pythonらしいパターン、データ構造、アルゴリズム
- **フレームワーク**: Django、Flask、FastAPI、SQLAlchemy
- **テスト**: pytest、unittest、モック、テスト駆動開発
- **データサイエンス**: pandas、numpy、matplotlib、jupyter notebooks
- **非同期プログラミング**: asyncio、async/awaitパターン
- **パッケージ管理**: pip、poetry、仮想環境
- **コード品質**: PEP 8、型ヒント、pylint/flake8によるリンティング

Pythonタスクの場合:

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

コミュニティ標準に従った、クリーンで保守可能なPythonコードの記述に焦点を当ててください。

使用例:

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

ベストプラクティス

設計原則

単一責任の原則

各Subagentは明確で焦点を絞った目的を持つべきです。

✅ 良い例:


---
name: testing-expert
description: 包括的な単体テストと統合テストを記述します
---

❌ 避けるべき例:


---
name: general-helper
description: テスト、ドキュメント、コードレビュー、デプロイメントの支援
---

理由: 焦点を絞ったエージェントの方が、より良い結果を生み出し、保守も容易です。

明確な特化

広範な機能ではなく、特定の専門領域を定義します。

✅ 良い例:


---
name: react-performance-optimizer
description: プロファイリングとベストプラクティスを使用して、パフォーマンスのためにReactアプリケーションを最適化します
---

❌ 避けるべき例:


---
name: frontend-developer
description: フロントエンド開発タスクの作業
---

理由: 特定の専門知識により、より的を絞った効果的な支援が可能になります。

実用的な説明

エージェントをいつ使用すべきかが明確にわかる説明を書きましょう。

✅ 良い例:


description: セキュリティの脆弱性、パフォーマンスの問題、保守性の懸念についてコードをレビューします

❌ 避けるべき例:


description: 便利なコードレビュアー

理由: 明確な説明は、メインのAIが各タスクに適したエージェントを選択するのに役立ちます。

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

システムプロンプトのガイドライン

専門性を明確に:


あなたは以下の専門知識を持つPythonテストスペシャリストです:

- pytestフレームワークとフィクスチャ
- モックオブジェクトと依存性注入
- テスト駆動開発のプラクティス
- pytest-benchmarkを使用したパフォーマンステスト

段階的なアプローチを含める:


各テストタスクについて:

1. コード構造と依存関係を分析する
2. 主要機能とエッジケースを特定する
3. 明確な命名を持つ包括的なテストスイートを作成する
4. セットアップ/ティアダウンと適切なアサーションを含める
5. 複雑なテストシナリオを説明するコメントを追加する

出力基準を指定する:


常に以下の標準に従ってください:

- シナリオを説明する説明的なテスト名を使用する
- ポジティブテストケースとネガティブテストケースの両方を含める
- 複雑なテスト関数にdocstringを追加する
- テストが独立しており、任意の順序で実行できるようにする

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

ツール制限: toolsを使用してサブエージェントがアクセスできるツールを制限するか、disallowedToolsを使用して特定のツールをブロックしながら他のツールは継承することができます
権限モード: サブエージェントはデフォルトで親エージェントの権限モードを継承します。プランモードのセッションは、委任されたエージェントを通じてauto-editにエスカレーションすることはできません。特権モード（auto-edit、yolo）は信頼できないフォルダではブロックされます。
プロバイダー選択: model: authType:modelId または model: fast（fastModelが別の認証タイプに解決される場合）を使用するサブエージェントは、そのサブエージェントのモデルリクエストを選択されたプロバイダーに送信します。そのプロバイダーがサブエージェントのタスクとデータに適切であることを確認してください。
サンドボックス化: すべてのツール実行は、直接ツールを使用する場合と同じセキュリティモデルに従います
監査証跡: すべてのSubagentのアクションはログに記録され、リアルタイムで表示可能です
アクセス制御: プロジェクトレベルおよびユーザーレベルの分離により、適切な境界が提供されます
機密情報: エージェント設定にシークレットや認証情報を含めないでください
本番環境: 開発環境と本番環境には、それぞれ別のエージェントを用意することを検討してください

制限事項

Subagent設定には以下のソフト警告が適用されます（ハード制限はありません）:

説明フィールド: 説明が1,000文字を超えると警告が表示されます
システムプロンプト: システムプロンプトが10,000文字を超えると警告が表示されます

サブエージェント

サブエージェントとは

Claude Code と Codex サブエージェント

Fork サブエージェント

fork_turns によるフォークコンテキスト

fork_tools によるフォークツールの実行制限

fork_profile によるフォーク制限の再利用

フォークと名前付きサブエージェントの違い

フォークが使用される場面

プロンプトキャッシュの共有

再帰的委任の防止

現在の制限事項

主な利点

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

バックグラウンドエージェントの継続

通知キュー

エージェントの作業ディレクトリ

はじめに

クイックスタート

使用例

管理

CLI コマンド

保存場所

拡張機能サブエージェント

ファイル形式

基本構造

モデル選択

許可モード

ツール設定

Claude Code 互換性フィールド

使用例

サブエージェントを効果的に使用する

自動委任

明示的な呼び出し

例

開発ワークフローエージェント

テストスペシャリスト

ドキュメントライター

コードレビュアー

テクノロジー特化型エージェント

Reactスペシャリスト

Pythonエキスパート

ベストプラクティス

設計原則

単一責任の原則

明確な特化

実用的な説明

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

システムプロンプトのガイドライン

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

制限事項

`fork_turns` によるフォークコンテキスト

`fork_tools` によるフォークツールの実行制限

`fork_profile` によるフォーク制限の再利用