メインコンテンツへスキップ
サブエージェント(Subagent)は、Qoder CLI で特定の種類の作業を担当する専用 Agent です。独自のシステムプロンプト、ツールセット、モデル設定、権限モード、実行制限、Hook を持てるため、コード探索、実装計画、API レビュー、テスト追加、移行調査などを集中して任せられます。

クイックスタート

  1. TUI で /agents を実行し、設定パネルを開きます。
  2. Tab を押して User または Project タブに切り替えます。
  3. Create new agent... を選択し、Subagent の説明を入力して確定します。
  4. 生成後、会話内で直接呼び出します。

Subagent とは

複数ファイルにまたがる調査、安定したドメイン固有の判断基準が必要な作業、または検索や分析の過程をメイン会話のコンテキストに混ぜたくない作業では、Subagent が有効です。メインセッションはユーザーの目的を理解して作業を編成し、Subagent は明確なサブタスクを実行して結果をメインセッションに返します。 主な価値: 主な特徴: 具体的なファイルやコマンドが分かっている場合は、直接そのツールを使う方が効率的です。Subagent は、判断と要約を含むオープンエンドな複数ステップの作業に向いています。

組み込み Subagent

Qoder CLI はいくつかの組み込み Subagent を登録します。/agentsBuiltIn タブに表示される正確な一覧は、バージョン、実行モード、有効な機能によって変わります。 よく使う組み込み Subagent: モードや機能フラグによっては、次の Subagent も表示されます。 組み込み Subagent は Qoder CLI が提供、保守します。ユーザーレベルやプロジェクトレベルの Subagent のように直接編集するものではありません。挙動を変えたい場合は、新しい名前または同じ名前でカスタム Subagent を作成し、ソース優先度を使って上書きします。

Subagent の表示と使用

利用可能な Subagent を表示する

TUI 方式

TUI で次を入力します。
/agents パネルは Subagent をソースごとに表示し、詳細確認、作成、有効化/無効化、カスタム項目の編集、再読み込みを行えます。.qoder/agents/ または ~/.qoder/agents/ を変更した後は、次を実行できます。

非対話方式

非対話環境では次を使います。
一覧には検出されたすべての Subagent が表示されます。同名の Subagent がより高い優先度のソースに上書きされている場合は、shadowed として表示されます。

ソースと優先度

Qoder CLI は複数のソースから Subagent を検出します。同名定義は優先度に従って上書きされます。優先度は低い順に次のとおりです。 実際に有効になるのは最も優先度の高い同名定義で、上書きされた定義は qodercli agents listshadowed と表示されます。

明示的に呼び出す

TUI モード

TUI 会話では、入力内で Subagent 名を直接指定するのが最も安定した呼び出し方法です。
TUI 入力では、読み込まれている Subagent を @ で指定することもできます。

Headless モード

Headless モードでは、同じ自然言語リクエストを qodercli -p で渡します。

暗黙的に呼び出す

TUI モード

TUI 会話では、タスクだけを説明し、Qoder CLI に各 Subagent の description をもとに判断させることもできます。

Headless モード

Headless モードでは、タスク説明だけを qodercli -p に渡すこともできます。
必ず特定の Subagent を使いたい場合は、名前を明示してください。TUI では @name も使えます。

現在の会話のメイン Agent として使う

--agent は、すでに読み込まれている Subagent を現在のセッションのメイン Agent として使います。この場合、その定義の initialPrompt がセッションの初期プロンプトとして使われます。

TUI モード

TUI を起動するときに --agent を指定します。
TUI 起動後、このセッションは api-reviewer をメイン Agent として使います。/agents パネルから Agent を実行しても、メインセッションの Agent は切り替わりません。@agent-name による 1 回の Subagent 呼び出しとして送信されます。

Headless モード

Headless モードでは -p と一緒に使います。

複数の Subagent を編成する

自然言語で Subagent の実行順序を説明すると、Qoder CLI はその順序に沿ってタスクを処理します。

TUI モード

TUI 会話では、編成リクエストをそのまま入力します。

Headless モード

Headless モードでは、同じ編成リクエストを qodercli -p で渡します。
独立したタスクであれば、並行実行を明示できます。依存関係がある作業では、上の例のように順序を説明してください。--max-turns は Headless クエリ全体の上限です。単一の Subagent 呼び出しを制限するには、その Subagent 設定で maxTurns を指定します。

Subagent をカスタマイズする

永続的なローカル Subagent 定義を作成する

方法 1:AI 支援生成(推奨)

Subagent を作成する最も簡単な方法です。自然言語で要件を説明するだけで、Qoder CLI が完全な設定ファイルを生成します。 手順:
  1. TUI で /agents を実行して設定パネルを開きます。
  2. TabUser または Project タブへ切り替えます。
  3. Create new agent... を選択して Enter を押します。
  4. Subagent の説明を入力し、Enter で確定します。
説明を入力すると、Qoder CLI が設定を自動生成します。
生成後、選択したディレクトリで設定ファイルを見つけて調整できます。
ヒント:まず AI 支援生成で初期 Subagent を作り、その後で特定のニーズに合わせて反復的に調整することをおすすめします。カスタマイズ可能な良い土台を素早く得られます。

方法 2:設定を手動で書く(上級者向け)

Subagent 設定を完全に制御したい場合は、Markdown 設定ファイルを手動で作成できます。
Markdown ファイルは YAML frontmatter で始まる必要があります。frontmatter は設定を宣言し、Markdown 本文はローカル Subagent のシステムプロンプトになります。
Subagent を別の worktree で実行するには、frontmatter に追加します:
ファイル名は Subagent 名ではありません。実際の名前は frontmatter の name フィールドで決まります。

--agents で一時的に注入する

--agents は Headless 実行、スクリプト、一回限りの自動化に便利です。Subagent 名をキー、定義を値とする JSON オブジェクトを受け取ります。--agents で注入した Subagent は現在のプロセスでのみ有効で、同名競合では最優先です。
--agents では prompt フィールドがシステムプロンプトになります。現在の JSON schema は descriptionprompttoolsdisallowedToolsmcpServersmodeleffortcolormaxTurnsinitialPromptskillspermissionMode をサポートします。timeoutMinstemperaturehooksmemorybackgroundisolation が必要な場合は Markdown 設定を使ってください。

Subagent を設定する

スコープを選択する

カスタム Subagent を作成または注入するときは、次のスコープから選択します。

ツールを設定する

toolsdisallowedTools は、カンマ区切り文字列または文字列配列で書けます。文字列配列は YAML のインライン配列でも、YAML のブロックリストでも指定できます。
よく使うツール名には ReadGrepGlobBashWriteEditWebFetchWebSearchAgent があります。 MCP ツールは完全修飾名を使います。
Subagent が呼び出せる他の Subagent を限定するには、Agent(name) 式を使います。
Subagent からの再ディスパッチを完全に禁止するには、Agent を無効にします。
ツール処理の順序は、まず tools から許可ツールを登録し、その後 disallowedTools にあるツールを削除します。MCP ツールは mcpServers またはグローバル MCP 設定で検出され、さらに tools で許可されて初めて Subagent から使えます。

MCP を設定する

すでに設定済みの MCP サーバーを参照できます。
この Subagent 専用の MCP サーバーをインライン定義することもできます。
mcpServers は配列形式とオブジェクト形式の両方をサポートします。インラインサーバーフィールドは次のとおりです。

Hook を定義する

Subagent frontmatter の hooks は、その Subagent セッションにだけ作用します。対応イベントには PreToolUsePostToolUsePostToolUseFailureStopSubagentStartSubagentStopNotification があります。 hooks は文字列の省略記法をサポートしません。各イベントの値は matcher 配列である必要があり、各 matcher の中で hooks 配列を使って 1 つ以上の Hook を宣言します。 Subagent 内では StopSubagentStop に変換されます。つまり、メインセッション終了時ではなく、その Subagent が完了したときに発火します。
各イベントには matcher を並べます。各 matcher の hooks 配列では次の Hook タイプを使えます。 frontmatter schema は once も受け付けますが、通常の Subagent frontmatter では一回限り Hook の意味は保持されません。一回限りの動作が必要な場合は、Hook コマンドまたは外部状態で制御してください。

権限モードを設定する

permissionMode は、Subagent のツール呼び出しに対する承認動作を制御します。 公開設定では上表の正規値を使うことを推奨します。実行時の解析は大文字小文字や区切り文字の違いを許容し、互換性のため yolobypassPermissions として解析されますが、推奨表記は bypassPermissions です。 注意点:
  • permissionMode を省略すると、Subagent は親セッションの現在のモードを継承します。
  • 親セッションがすでに acceptEditsbypassPermissionsauto の場合、Subagent 自身の設定でそれより厳しくすることはできません。
  • plan はメインセッションの計画状態に影響しません。Subagent の隔離コンテキスト内だけで有効です。

リモート Subagent を設定する

リモート Subagent は Agent Card から読み込まれます。Markdown 本文はシステムプロンプトとして使われず、動作はリモート Agent Card が公開する能力と説明に基づきます。
agentCardJson で Agent Card JSON をインライン指定することもできます。リモート Subagent は auth フィールドをサポートし、よく使う認証タイプには apiKeyhttpoauth があります。認証が必要な場合は、認証情報をプロジェクトリポジトリにコミットしないよう、ユーザーレベル設定を推奨します。

settings.json で既存 Subagent を上書きする

settings.json は新しい Subagent を作成できません。すでに検出された Subagent だけを上書きします。現在は、有効状態、モデル設定、実行制限、ツール許可リスト、追加 MCP サーバーを上書きできます。
よくある用途:
  • "enabled": false で Subagent を一時的に非表示にする。
  • 特定の Subagent だけモデルと温度を変える。
  • 自動化のために最大ターン数や最大実行時間を制限する。
  • 元の Markdown を編集せずにツールセットを絞る。
  • 既存のローカル Subagent に MCP サーバーを追加する。
プラグイン提供の Subagent には追加の安全ポリシーが適用されます。hooksmcpServerspermissionMode は削除され、isolationworktree の場合だけ保持されます。

ローカル Subagent の全フィールド

以下のフィールドは Markdown frontmatter で使えます。不明なフィールドは無視されます。

効果をテストする

Subagent を作成または編集した後は、次の順序で確認してください。
  1. /agents reload を実行するか、新しいセッションを開始します。
  2. /agents または qodercli agents list で、期待したソースに表示されることを確認します。
  3. description がいつ使うべきかを明確に説明しているか確認します。
  4. 一度、名前を明示して呼び出します。
  1. 読み取り専用として設定している場合は、ファイルを変更しないよう依頼し、書き込み操作が出ないことを確認します。
  2. disallowedTools を設定している場合は、禁止された能力を依頼し、別手段を選ぶか制限を説明することを確認します。
  3. MCP を使う場合は、対象 MCP ツールが検出され、tools によってブロックされていないことを確認します。
  4. background またはバックグラウンド実行を使う場合は、メインセッションが完全な結果を待たず、完了通知が後続で届くことを確認します。
呼び出されない場合は、まず明示的な名前または @name を使ってください。それでも使えない場合は /agents パネルの読み込みエラーを確認します。

ベストプラクティス

  • 1 つの Subagent には 1 つの明確な責務を持たせ、レビュー、実装、テスト、リリースをまとめすぎない。
  • description は選択用、本文プロンプトは Subagent 自身用に書きます。どちらも具体的にします。
  • まず読み取り専用ツールから始め、必要になったら EditWriteBash を追加します。
  • リスクが高い Subagent には maxTurnstimeoutMins、明示的な permissionMode を設定します。
  • 独立した作業コピーが必要な場合は isolation: worktree を使い、返された worktree パスと実際の diff を確認します。
  • MCP ツールに依存する場合は、ツールが検出され、かつ許可されるように mcpServerstools の両方を設定します。
  • プロジェクトレベルの Subagent はチーム共有標準に、ユーザーレベルの Subagent は個人の好みやプロジェクト横断ワークフローに向いています。
  • 暗黙選択に任せる前に、まず明示的に呼び出してテストします。
  • プラグイン配布の Subagent では、hooksmcpServerspermissionMode に依存しないでください。プラグイン安全ポリシーで削除されます。

よくある質問

Subagent とメインセッションの違いは?

Subagent は、独立したコンテキスト、自分のシステムプロンプト、ツールセット、実行制限、権限宣言で動作します。結果はメインセッションに返され、メインセッションが要約や続きの作業を行えます。

プロジェクトレベルの Subagent が表示されないのはなぜですか?

ファイルが .qoder/agents/<name>.md にあり、frontmatter に少なくとも namedescription があり、現在のプロジェクトが信頼済みであることを確認してください。その後 /agents reload を実行し、/agents パネルの読み込みエラーを確認します。

同名 Subagent が期待通りに有効にならないのはなぜですか?

高優先度のソースが低優先度のソースを上書きします。順序は Built-in < User < Project < Plugin < Flag です。qodercli agents list で shadowed 項目を確認できます。

description と本文プロンプトの違いは?

description はいつ Subagent を呼び出すかを説明し、選択に影響します。本文プロンプトは呼び出された後に Subagent が見るシステムプロンプトで、タスクの進め方に影響します。

複数の Subagent を同時に実行できますか?

はい。独立したタスクであれば、Qoder CLI は複数の Subagent を並行して実行できます。依存関係がある作業では、プロンプト内で順序を説明してください。

Subagent から別の Subagent を呼び出せますか?

はい。Agent ツールが利用可能であれば呼び出せます。特定の Subagent だけを許可するには Agent(name) または Agent(name1, name2) を使います。再ディスパッチを禁止するには disallowedTools: [Agent] を使います。

設定した MCP ツールを Subagent が使えないのはなぜですか?

まず MCP サーバーが mcpServers またはグローバル MCP 設定で検出されていることを確認してください。次に、tools が完全修飾 MCP ツール名を許可していることを確認します。mcpServers はツールを検出するだけで、すべての MCP ツールを自動許可するわけではありません。

Subagent の権限モードがより厳しくならないのはなぜですか?

親セッションがすでに acceptEditsbypassPermissionsauto の場合、Subagent は permissionMode でそれより厳しくできません。permissionMode を省略した場合も、親セッションの現在のモードを継承します。

バックグラウンド Subagent の結果はどこで確認できますか?

バックグラウンド実行では、メインセッションはまず起動結果を受け取ります。タスク結果は後から完了通知として届きます。通知が届く前に期待結果を要約しないでください。

組み込みまたはプラグイン Subagent を編集できますか?

組み込みとプラグイン Subagent は直接編集するものではありません。代わりにユーザーレベルまたはプロジェクトレベルの Subagent を作成してください。同名で上書きする場合は、ソース優先度とプラグイン安全ポリシーに注意してください。