クイックスタート
- TUI で
/agentsを実行し、設定パネルを開きます。 Tabを押してUserまたはProjectタブに切り替えます。Create new agent...を選択し、Subagent の説明を入力して確定します。- 生成後、会話内で直接呼び出します。
Subagent とは
複数ファイルにまたがる調査、安定したドメイン固有の判断基準が必要な作業、または検索や分析の過程をメイン会話のコンテキストに混ぜたくない作業では、Subagent が有効です。メインセッションはユーザーの目的を理解して作業を編成し、Subagent は明確なサブタスクを実行して結果をメインセッションに返します。 主な価値:
主な特徴:
具体的なファイルやコマンドが分かっている場合は、直接そのツールを使う方が効率的です。Subagent は、判断と要約を含むオープンエンドな複数ステップの作業に向いています。
組み込み Subagent
Qoder CLI はいくつかの組み込み Subagent を登録します。/agents の BuiltIn タブに表示される正確な一覧は、バージョン、実行モード、有効な機能によって変わります。
よく使う組み込み Subagent:
モードや機能フラグによっては、次の Subagent も表示されます。
組み込み Subagent は Qoder CLI が提供、保守します。ユーザーレベルやプロジェクトレベルの Subagent のように直接編集するものではありません。挙動を変えたい場合は、新しい名前または同じ名前でカスタム Subagent を作成し、ソース優先度を使って上書きします。
Subagent の表示と使用
利用可能な Subagent を表示する
TUI 方式
TUI で次を入力します。/agents パネルは Subagent をソースごとに表示し、詳細確認、作成、有効化/無効化、カスタム項目の編集、再読み込みを行えます。.qoder/agents/ または ~/.qoder/agents/ を変更した後は、次を実行できます。
非対話方式
非対話環境では次を使います。ソースと優先度
Qoder CLI は複数のソースから Subagent を検出します。同名定義は優先度に従って上書きされます。優先度は低い順に次のとおりです。
実際に有効になるのは最も優先度の高い同名定義で、上書きされた定義は
qodercli agents list で shadowed と表示されます。
明示的に呼び出す
TUI モード
TUI 会話では、入力内で Subagent 名を直接指定するのが最も安定した呼び出し方法です。@ で指定することもできます。
Headless モード
Headless モードでは、同じ自然言語リクエストをqodercli -p で渡します。
暗黙的に呼び出す
TUI モード
TUI 会話では、タスクだけを説明し、Qoder CLI に各 Subagent のdescription をもとに判断させることもできます。
Headless モード
Headless モードでは、タスク説明だけをqodercli -p に渡すこともできます。
@name も使えます。
現在の会話のメイン Agent として使う
--agent は、すでに読み込まれている Subagent を現在のセッションのメイン Agent として使います。この場合、その定義の initialPrompt がセッションの初期プロンプトとして使われます。
TUI モード
TUI を起動するときに--agent を指定します。
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 が完全な設定ファイルを生成します。 手順:- TUI で
/agentsを実行して設定パネルを開きます。 TabでUserまたはProjectタブへ切り替えます。Create new agent...を選択してEnterを押します。- Subagent の説明を入力し、
Enterで確定します。
方法 2:設定を手動で書く(上級者向け)
Subagent 設定を完全に制御したい場合は、Markdown 設定ファイルを手動で作成できます。name フィールドで決まります。
--agents で一時的に注入する
--agents は Headless 実行、スクリプト、一回限りの自動化に便利です。Subagent 名をキー、定義を値とする JSON オブジェクトを受け取ります。--agents で注入した Subagent は現在のプロセスでのみ有効で、同名競合では最優先です。
--agents では prompt フィールドがシステムプロンプトになります。現在の JSON schema は description、prompt、tools、disallowedTools、mcpServers、model、effort、color、maxTurns、initialPrompt、skills、permissionMode をサポートします。timeoutMins、temperature、hooks、memory、background、isolation が必要な場合は Markdown 設定を使ってください。
Subagent を設定する
スコープを選択する
カスタム Subagent を作成または注入するときは、次のスコープから選択します。ツールを設定する
tools と disallowedTools は、カンマ区切り文字列または文字列配列で書けます。文字列配列は YAML のインライン配列でも、YAML のブロックリストでも指定できます。
Read、Grep、Glob、Bash、Write、Edit、WebFetch、WebSearch、Agent があります。
MCP ツールは完全修飾名を使います。
Agent(name) 式を使います。
Agent を無効にします。
tools から許可ツールを登録し、その後 disallowedTools にあるツールを削除します。MCP ツールは mcpServers またはグローバル MCP 設定で検出され、さらに tools で許可されて初めて Subagent から使えます。
MCP を設定する
すでに設定済みの MCP サーバーを参照できます。mcpServers は配列形式とオブジェクト形式の両方をサポートします。インラインサーバーフィールドは次のとおりです。
Hook を定義する
Subagent frontmatter のhooks は、その Subagent セッションにだけ作用します。対応イベントには PreToolUse、PostToolUse、PostToolUseFailure、Stop、SubagentStart、SubagentStop、Notification があります。
hooks は文字列の省略記法をサポートしません。各イベントの値は matcher 配列である必要があり、各 matcher の中で hooks 配列を使って 1 つ以上の Hook を宣言します。
Subagent 内では Stop は SubagentStop に変換されます。つまり、メインセッション終了時ではなく、その Subagent が完了したときに発火します。
hooks 配列では次の Hook タイプを使えます。
frontmatter schema は
once も受け付けますが、通常の Subagent frontmatter では一回限り Hook の意味は保持されません。一回限りの動作が必要な場合は、Hook コマンドまたは外部状態で制御してください。
権限モードを設定する
permissionMode は、Subagent のツール呼び出しに対する承認動作を制御します。
公開設定では上表の正規値を使うことを推奨します。実行時の解析は大文字小文字や区切り文字の違いを許容し、互換性のため
yolo は bypassPermissions として解析されますが、推奨表記は bypassPermissions です。
注意点:
permissionModeを省略すると、Subagent は親セッションの現在のモードを継承します。- 親セッションがすでに
acceptEdits、bypassPermissions、autoの場合、Subagent 自身の設定でそれより厳しくすることはできません。 planはメインセッションの計画状態に影響しません。Subagent の隔離コンテキスト内だけで有効です。
リモート Subagent を設定する
リモート Subagent は Agent Card から読み込まれます。Markdown 本文はシステムプロンプトとして使われず、動作はリモート Agent Card が公開する能力と説明に基づきます。agentCardJson で Agent Card JSON をインライン指定することもできます。リモート Subagent は auth フィールドをサポートし、よく使う認証タイプには apiKey、http、oauth があります。認証が必要な場合は、認証情報をプロジェクトリポジトリにコミットしないよう、ユーザーレベル設定を推奨します。
settings.json で既存 Subagent を上書きする
settings.json は新しい Subagent を作成できません。すでに検出された Subagent だけを上書きします。現在は、有効状態、モデル設定、実行制限、ツール許可リスト、追加 MCP サーバーを上書きできます。
"enabled": falseで Subagent を一時的に非表示にする。- 特定の Subagent だけモデルと温度を変える。
- 自動化のために最大ターン数や最大実行時間を制限する。
- 元の Markdown を編集せずにツールセットを絞る。
- 既存のローカル Subagent に MCP サーバーを追加する。
hooks、mcpServers、permissionMode は削除され、isolation は worktree の場合だけ保持されます。
ローカル Subagent の全フィールド
以下のフィールドは Markdown frontmatter で使えます。不明なフィールドは無視されます。効果をテストする
Subagent を作成または編集した後は、次の順序で確認してください。/agents reloadを実行するか、新しいセッションを開始します。/agentsまたはqodercli agents listで、期待したソースに表示されることを確認します。descriptionがいつ使うべきかを明確に説明しているか確認します。- 一度、名前を明示して呼び出します。
- 読み取り専用として設定している場合は、ファイルを変更しないよう依頼し、書き込み操作が出ないことを確認します。
disallowedToolsを設定している場合は、禁止された能力を依頼し、別手段を選ぶか制限を説明することを確認します。- MCP を使う場合は、対象 MCP ツールが検出され、
toolsによってブロックされていないことを確認します。 backgroundまたはバックグラウンド実行を使う場合は、メインセッションが完全な結果を待たず、完了通知が後続で届くことを確認します。
@name を使ってください。それでも使えない場合は /agents パネルの読み込みエラーを確認します。
ベストプラクティス
- 1 つの Subagent には 1 つの明確な責務を持たせ、レビュー、実装、テスト、リリースをまとめすぎない。
descriptionは選択用、本文プロンプトは Subagent 自身用に書きます。どちらも具体的にします。- まず読み取り専用ツールから始め、必要になったら
Edit、Write、Bashを追加します。 - リスクが高い Subagent には
maxTurns、timeoutMins、明示的なpermissionModeを設定します。 - 独立した作業コピーが必要な場合は
isolation: worktreeを使い、返された worktree パスと実際の diff を確認します。 - MCP ツールに依存する場合は、ツールが検出され、かつ許可されるように
mcpServersとtoolsの両方を設定します。 - プロジェクトレベルの Subagent はチーム共有標準に、ユーザーレベルの Subagent は個人の好みやプロジェクト横断ワークフローに向いています。
- 暗黙選択に任せる前に、まず明示的に呼び出してテストします。
- プラグイン配布の Subagent では、
hooks、mcpServers、permissionModeに依存しないでください。プラグイン安全ポリシーで削除されます。
よくある質問
Subagent とメインセッションの違いは?
Subagent は、独立したコンテキスト、自分のシステムプロンプト、ツールセット、実行制限、権限宣言で動作します。結果はメインセッションに返され、メインセッションが要約や続きの作業を行えます。プロジェクトレベルの Subagent が表示されないのはなぜですか?
ファイルが.qoder/agents/<name>.md にあり、frontmatter に少なくとも name と description があり、現在のプロジェクトが信頼済みであることを確認してください。その後 /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 の権限モードがより厳しくならないのはなぜですか?
親セッションがすでにacceptEdits、bypassPermissions、auto の場合、Subagent は permissionMode でそれより厳しくできません。permissionMode を省略した場合も、親セッションの現在のモードを継承します。