> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # サブエージェント サブエージェント（Subagent）は、Qoder CLI で特定の種類の作業を担当する専用 Agent です。独自のシステムプロンプト、ツールセット、モデル設定、権限モード、実行制限、Hook を持てるため、コード探索、実装計画、API レビュー、テスト追加、移行調査などを集中して任せられます。 ## クイックスタート 1. TUI で `/agents` を実行し、設定パネルを開きます。 2. `Tab` を押して `User` または `Project` タブに切り替えます。 3. `Create new agent...` を選択し、Subagent の説明を入力して確定します。 4. 生成後、会話内で直接呼び出します。 ```text theme={null} Use the api-reviewer subagent to review this API design ``` ## Subagent とは 複数ファイルにまたがる調査、安定したドメイン固有の判断基準が必要な作業、または検索や分析の過程をメイン会話のコンテキストに混ぜたくない作業では、Subagent が有効です。メインセッションはユーザーの目的を理解して作業を編成し、Subagent は明確なサブタスクを実行して結果をメインセッションに返します。 主な価値： | 価値 | 説明 | | --------------- | ----------------------------------------------------------------------------------------------------------- | | メインセッションを集中させる | 各 Subagent は独立した会話コンテキスト、システムプロンプト、ツールレジストリ、実行記録、圧縮フローを持ちます。検索や思考の中間過程はメイン会話に直接混ざりません。 | | 専門タスクの品質を高める | タスクごとに専用プロンプト、ツール許可リスト、ツール拒否リスト、MCP サーバー、モデル、権限、実行上限を設定でき、レビュー、探索、計画などに安定した基準を持たせられます。 | | チームの作業フローを再利用する | ユーザーレベルとプロジェクトレベルの Subagent は繰り返し使え、プロジェクトと共有できるため、チームで一貫した作業フローを使えます。 | | ツールと権限の境界を制御する | Subagent ごとにツールセットと権限モードを設定でき、高リスクな作業で不適切な能力を使う可能性を下げられます。 | | 複雑な作業を編成する | 互いに独立したタスクでは複数の Subagent を並行して実行できます。バックグラウンド Subagent セッションが有効な場合は、独立した作業をバックグラウンドに回して完了後にメインセッションへ通知できます。 | 主な特徴： | 特徴 | 説明 | | ---------- | -------------------------------------------------------------------------------------- | | コンテキスト分離 | 各 Subagent は独立した会話コンテキスト、システムプロンプト、ツールレジストリ、実行記録、圧縮フローを持ちます。検索や思考の中間過程はメイン会話に直接混ざりません。 | | 能力のカスタマイズ | タスクごとにプロンプト、ツール許可リスト、ツール拒否リスト、MCP サーバー、モデル、権限、実行上限を設定できます。 | | 並行実行 | 互いに独立したタスクでは、Qoder CLI が複数の Subagent を並行して実行できます。 | | バックグラウンド実行 | バックグラウンド Subagent セッションが有効な場合、独立した作業をバックグラウンドに回し、完了後にメインセッションへ通知できます。 | | ワークスペース分離 | 独立した変更が必要な場合は `worktree` 分離を使い、Subagent を別の git worktree で実行できます。 | 具体的なファイルやコマンドが分かっている場合は、直接そのツールを使う方が効率的です。Subagent は、判断と要約を含むオープンエンドな複数ステップの作業に向いています。 ## 組み込み Subagent Qoder CLI はいくつかの組み込み Subagent を登録します。`/agents` の `BuiltIn` タブに表示される正確な一覧は、バージョン、実行モード、有効な機能によって変わります。 よく使う組み込み Subagent： | 名前 | 能力 | | ----------------- | ------------------------------------------------------------------------------------------------------ | | `general-purpose` | 複雑な検索、複数ファイル分析、呼び出し経路の追跡、複数ステップ作業向けの汎用調査 Subagent。Subagent タイプを明示しない場合、Agent ツールはこの Subagent を既定で使います。 | | `Explore` | ファイル検索、シンボル検索、既存実装の理解に使う高速な読み取り専用コード探索。利用可能なツールを継承したうえで、書き込み系と制御系のツールを取り除き、探索向けのモデル設定を使います。 | | `Plan` | 編集前に実装方針、重要ファイル、順序、アーキテクチャ上のトレードオフを整理する読み取り専用の計画作成。 | モードや機能フラグによっては、次の Subagent も表示されます。 | 名前 | 表示される場面 | 能力 | | ------------------ | --------- | ------------------------------------------------------------- | | `qoder-guide` | 非 SDK モード | Qoder CLI の使い方、設定、Skills、Agents、MCP、Hooks に関する質問に答えます。 | | `statusline-setup` | TUI モード | カスタム status line を設定します。shell 設定の読み取り、スクリプト作成、設定更新を行うことがあります。 | 組み込み Subagent は Qoder CLI が提供、保守します。ユーザーレベルやプロジェクトレベルの Subagent のように直接編集するものではありません。挙動を変えたい場合は、新しい名前または同じ名前でカスタム Subagent を作成し、ソース優先度を使って上書きします。 ## Subagent の表示と使用 ### 利用可能な Subagent を表示する #### TUI 方式 TUI で次を入力します。 ```text theme={null} /agents ``` `/agents` パネルは Subagent をソースごとに表示し、詳細確認、作成、有効化/無効化、カスタム項目の編集、再読み込みを行えます。`.qoder/agents/` または `~/.qoder/agents/` を変更した後は、次を実行できます。 ```text theme={null} /agents reload ``` #### 非対話方式 非対話環境では次を使います。 ```bash theme={null} qodercli agents list ``` 一覧には検出されたすべての Subagent が表示されます。同名の Subagent がより高い優先度のソースに上書きされている場合は、shadowed として表示されます。 ### ソースと優先度 Qoder CLI は複数のソースから Subagent を検出します。同名定義は優先度に従って上書きされます。優先度は低い順に次のとおりです。 | 優先度 | ソース | 入口 | 説明 | | --- | -------- | ------------------------ | -------------------------------------------------------------------------------- | | 1 | Built-in | `/agents` の `BuiltIn` タブ | Qoder CLI に同梱される機能です。Qoder CLI が提供、管理し、通常は直接編集しません。 | | 2 | User | `~/.qoder/agents/*.md` | ユーザーレベルの Subagent です。このユーザーの複数プロジェクトで有効です。 | | 3 | Project | `.qoder/agents/*.md` | プロジェクトレベルの Subagent です。現在のプロジェクトで有効で、プロジェクト共有に適しており、フォルダ信頼状態の影響を受けます。 | | 4 | Plugin | インストール済みプラグイン | プラグインが提供する Subagent です。プラグイン Subagent がある場合だけ `Plugin` タブが表示され、通常はプラグイン側で管理されます。 | | 5 | Flag | `--agents` JSON | 現在のプロセスに一時注入される Subagent です。最優先で、このコマンドまたはセッションだけに適用されます。 | 実際に有効になるのは最も優先度の高い同名定義で、上書きされた定義は `qodercli agents list` で `shadowed` と表示されます。 ### 明示的に呼び出す #### TUI モード TUI 会話では、入力内で Subagent 名を直接指定するのが最も安定した呼び出し方法です。 ```text theme={null} Use the api-reviewer subagent to review this API design ``` TUI 入力では、読み込まれている Subagent を `@` で指定することもできます。 ```text theme={null} @api-reviewer review this API design and return only required changes ``` #### Headless モード Headless モードでは、同じ自然言語リクエストを `qodercli -p` で渡します。 ```bash theme={null} qodercli -p "Use the api-reviewer subagent to review this API design" ``` ### 暗黙的に呼び出す #### TUI モード TUI 会話では、タスクだけを説明し、Qoder CLI に各 Subagent の `description` をもとに判断させることもできます。 ```text theme={null} Review this API design ``` #### Headless モード Headless モードでは、タスク説明だけを `qodercli -p` に渡すこともできます。 ```bash theme={null} qodercli -p "Review this API design" ``` 必ず特定の Subagent を使いたい場合は、名前を明示してください。TUI では `@name` も使えます。 ### 現在の会話のメイン Agent として使う `--agent` は、すでに読み込まれている Subagent を現在のセッションのメイン Agent として使います。この場合、その定義の `initialPrompt` がセッションの初期プロンプトとして使われます。 #### TUI モード TUI を起動するときに `--agent` を指定します。 ```bash theme={null} qodercli --agent api-reviewer ``` TUI 起動後、このセッションは `api-reviewer` をメイン Agent として使います。`/agents` パネルから Agent を実行しても、メインセッションの Agent は切り替わりません。`@agent-name` による 1 回の Subagent 呼び出しとして送信されます。 #### Headless モード Headless モードでは `-p` と一緒に使います。 ```bash theme={null} qodercli --agent api-reviewer -p "Review this API design" ``` ### 複数の Subagent を編成する 自然言語で Subagent の実行順序を説明すると、Qoder CLI はその順序に沿ってタスクを処理します。 #### TUI モード TUI 会話では、編成リクエストをそのまま入力します。 ```text theme={null} First use the general-purpose subagent to check the implementation approach, then use the api-reviewer subagent to review the API design ``` #### Headless モード Headless モードでは、同じ編成リクエストを `qodercli -p` で渡します。 ```bash theme={null} qodercli -p "First use the general-purpose subagent to check the implementation approach, then use the api-reviewer subagent to review the API design" --max-turns 10 ``` 独立したタスクであれば、並行実行を明示できます。依存関係がある作業では、上の例のように順序を説明してください。`--max-turns` は Headless クエリ全体の上限です。単一の Subagent 呼び出しを制限するには、その Subagent 設定で `maxTurns` を指定します。 ## Subagent をカスタマイズする ### 永続的なローカル Subagent 定義を作成する #### 方法 1：AI 支援生成（推奨） Subagent を作成する最も簡単な方法です。自然言語で要件を説明するだけで、Qoder CLI が完全な設定ファイルを生成します。 手順： 1. TUI で `/agents` を実行して設定パネルを開きます。 2. `Tab` で `User` または `Project` タブへ切り替えます。 3. `Create new agent...` を選択して `Enter` を押します。 4. Subagent の説明を入力し、`Enter` で確定します。 ```text theme={null} > /agents ------------------------------------------------------------------------------------------ Agents: User [Project] BuiltIn -> Create new agent... Agent list: No project agents found. Press Enter to select - Esc to exit - Tab to cycle tabs - Up/Down to navigate ``` 説明を入力すると、Qoder CLI が設定を自動生成します。 ```text theme={null} > /agents ------------------------------------------------------------------------------------------ Agents: User [Project] BuiltIn Describe the agent: > Help me review RESTful api design Press Enter to select - Esc to exit - Tab to cycle tabs - Up/Down to navigate ``` 生成後、選択したディレクトリで設定ファイルを見つけて調整できます。 ```bash theme={null} # プロジェクトレベル（Project タブ） .qoder/agents/ # ユーザーレベル（User タブ） ~/.qoder/agents/ ``` ヒント：まず AI 支援生成で初期 Subagent を作り、その後で特定のニーズに合わせて反復的に調整することをおすすめします。カスタマイズ可能な良い土台を素早く得られます。 #### 方法 2：設定を手動で書く（上級者向け） Subagent 設定を完全に制御したい場合は、Markdown 設定ファイルを手動で作成できます。 ```bash theme={null} # プロジェクトレベル。現在のプロジェクトだけで有効。バージョン管理に適しています .qoder/agents/api-reviewer.md # ユーザーレベル。このユーザーの各プロジェクトで有効 ~/.qoder/agents/api-reviewer.md ``` Markdown ファイルは YAML frontmatter で始まる必要があります。frontmatter は設定を宣言し、Markdown 本文はローカル Subagent のシステムプロンプトになります。 ```markdown theme={null} --- name: api-reviewer description: Review API designs, endpoint naming, request methods, status codes, error responses, and versioning. tools: [Read, Grep, Glob] disallowedTools: [Write, Edit] permissionMode: default model: inherit maxTurns: 8 timeoutMins: 10 color: cyan --- You are an API design reviewer. Focus on: - Resource naming and URL structure - Request method semantics - Status code and error response consistency - Pagination, filtering, and versioning Return concise findings grouped by severity. Include concrete examples when possible. ``` Subagent を別の worktree で実行するには、frontmatter に追加します： ```yaml theme={null} isolation: worktree ``` ファイル名は Subagent 名ではありません。実際の名前は frontmatter の `name` フィールドで決まります。 ### `--agents` で一時的に注入する `--agents` は Headless 実行、スクリプト、一回限りの自動化に便利です。Subagent 名をキー、定義を値とする JSON オブジェクトを受け取ります。`--agents` で注入した Subagent は現在のプロセスでのみ有効で、同名競合では最優先です。 ```bash theme={null} qodercli \ --agents '{"api-reviewer":{"description":"Review API designs","prompt":"You are an API reviewer.","tools":["Read","Grep","Glob"],"maxTurns":6}}' \ -p "Use the api-reviewer subagent to review docs/api.yaml" ``` `--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 を作成または注入するときは、次のスコープから選択します。 | スコープ | 設定入口 | | ------- | ---------------------- | | Project | `.qoder/agents/*.md` | | User | `~/.qoder/agents/*.md` | | Flag | `--agents` | ### ツールを設定する `tools` と `disallowedTools` は、カンマ区切り文字列または文字列配列で書けます。文字列配列は YAML のインライン配列でも、YAML のブロックリストでも指定できます。 ```yaml theme={null} tools: Read,Grep,Glob ``` ```yaml theme={null} tools: [Read, Grep, Glob] ``` ```yaml theme={null} tools: - Read - Grep - Glob ``` よく使うツール名には `Read`、`Grep`、`Glob`、`Bash`、`Write`、`Edit`、`WebFetch`、`WebSearch`、`Agent` があります。 MCP ツールは完全修飾名を使います。 ```yaml theme={null} tools: - mcp__docs__search - mcp__docs__* - mcp__* ``` Subagent が呼び出せる他の Subagent を限定するには、`Agent(name)` 式を使います。 ```yaml theme={null} tools: - Read - Grep - Agent(Explore, Plan) ``` Subagent からの再ディスパッチを完全に禁止するには、`Agent` を無効にします。 ```yaml theme={null} disallowedTools: [Agent] ``` ツール処理の順序は、まず `tools` から許可ツールを登録し、その後 `disallowedTools` にあるツールを削除します。MCP ツールは `mcpServers` またはグローバル MCP 設定で検出され、さらに `tools` で許可されて初めて Subagent から使えます。 ### MCP を設定する すでに設定済みの MCP サーバーを参照できます。 ```yaml theme={null} mcpServers: - docs ``` この Subagent 専用の MCP サーバーをインライン定義することもできます。 ```yaml theme={null} mcpServers: docs: command: ./scripts/docs-mcp args: ["--stdio"] include_tools: ["search", "read"] ``` `mcpServers` は配列形式とオブジェクト形式の両方をサポートします。インラインサーバーフィールドは次のとおりです。 | フィールド | 意味 | | ------------------ | ------------------------ | | `command` | stdio MCP サーバーを起動するコマンド。 | | `args` | コマンド引数配列。 | | `env` | MCP サーバーに渡す環境変数。 | | `cwd` | MCP サーバーの作業ディレクトリ。 | | `url` / `http_url` | リモート MCP サーバーの URL。 | | `headers` | リモートリクエストヘッダー。 | | `tcp` | TCP 接続先。 | | `type` | 転送タイプ。`sse` または `http`。 | | `timeout` | 接続または呼び出しタイムアウト。 | | `trust` | この MCP サーバーを信頼するかどうか。 | | `description` | サーバー説明。 | | `include_tools` | 指定した MCP ツールだけを含めます。 | | `exclude_tools` | 指定した MCP ツールを除外します。 | ### Hook を定義する Subagent frontmatter の `hooks` は、その Subagent セッションにだけ作用します。対応イベントには `PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`Stop`、`SubagentStart`、`SubagentStop`、`Notification` があります。 `hooks` は文字列の省略記法をサポートしません。各イベントの値は matcher 配列である必要があり、各 matcher の中で `hooks` 配列を使って 1 つ以上の Hook を宣言します。 Subagent 内では `Stop` は `SubagentStop` に変換されます。つまり、メインセッション終了時ではなく、その Subagent が完了したときに発火します。 ```yaml theme={null} hooks: PreToolUse: - matcher: Bash hooks: - type: command command: ./scripts/check-subagent-command.sh timeout: 30 statusMessage: Checking command Stop: - hooks: - type: command command: ./scripts/subagent-finished.sh ``` 各イベントには matcher を並べます。各 matcher の `hooks` 配列では次の Hook タイプを使えます。 | `type` | 必須フィールド | 説明 | | --------- | --------- | -------------------------------------------------------------------------------------------- | | `command` | `command` | ローカルコマンドを実行します。任意で `shell`、`timeout`、`if`、`statusMessage` を指定できます。 | | `http` | `url` | HTTP endpoint を呼び出します。任意で `headers`、`allowedEnvVars`、`timeout`、`if`、`statusMessage` を指定できます。 | | `prompt` | `prompt` | プロンプトからモデル判定を実行します。任意で `model`、`timeout`、`if`、`statusMessage` を指定できます。 | | `agent` | `prompt` | 独立した Hook Agent を実行します。任意で `model`、`timeout`、`if`、`statusMessage` を指定できます。 | frontmatter schema は `once` も受け付けますが、通常の Subagent frontmatter では一回限り Hook の意味は保持されません。一回限りの動作が必要な場合は、Hook コマンドまたは外部状態で制御してください。 ### 権限モードを設定する `permissionMode` は、Subagent のツール呼び出しに対する承認動作を制御します。 | 値 | 意味 | | ------------------- | --------------------------------------------------- | | `default` | デフォルト権限ポリシーを使い、必要に応じて確認します。 | | `acceptEdits` | 編集操作を自動承認します。 | | `bypassPermissions` | 権限確認を省略します。セキュリティポリシーで無効な場合は `acceptEdits` に下げられます。 | | `dontAsk` | 自発的に確認しません。確認が必要な操作は拒否されます。 | | `auto` | 自動ポリシー判定を使います。 | | `plan` | この Subagent 自身の計画状態に入ります。読み取り専用の計画作業に適しています。 | 公開設定では上表の正規値を使うことを推奨します。実行時の解析は大文字小文字や区切り文字の違いを許容し、互換性のため `yolo` は `bypassPermissions` として解析されますが、推奨表記は `bypassPermissions` です。 注意点： * `permissionMode` を省略すると、Subagent は親セッションの現在のモードを継承します。 * 親セッションがすでに `acceptEdits`、`bypassPermissions`、`auto` の場合、Subagent 自身の設定でそれより厳しくすることはできません。 * `plan` はメインセッションの計画状態に影響しません。Subagent の隔離コンテキスト内だけで有効です。 ### リモート Subagent を設定する リモート Subagent は Agent Card から読み込まれます。Markdown 本文はシステムプロンプトとして使われず、動作はリモート Agent Card が公開する能力と説明に基づきます。 ```markdown theme={null} --- kind: remote name: docs-helper description: Answer questions using the remote documentation agent. agentCardUrl: https://agent.example/.well-known/agent-card.json --- ``` `agentCardJson` で Agent Card JSON をインライン指定することもできます。リモート Subagent は `auth` フィールドをサポートし、よく使う認証タイプには `apiKey`、`http`、`oauth` があります。認証が必要な場合は、認証情報をプロジェクトリポジトリにコミットしないよう、ユーザーレベル設定を推奨します。 ### `settings.json` で既存 Subagent を上書きする `settings.json` は新しい Subagent を作成できません。すでに検出された Subagent だけを上書きします。現在は、有効状態、モデル設定、実行制限、ツール許可リスト、追加 MCP サーバーを上書きできます。 ```json theme={null} { "agents": { "overrides": { "api-reviewer": { "enabled": true, "tools": ["Read", "Grep", "Glob"], "runConfig": { "maxTurns": 6, "maxTimeMinutes": 10 }, "modelConfig": { "model": "auto", "generateContentConfig": { "temperature": 0.2 } }, "mcpServers": { "docs": { "command": "./scripts/docs-mcp", "args": ["--stdio"] } } } } } } ``` よくある用途： * `"enabled": false` で Subagent を一時的に非表示にする。 * 特定の Subagent だけモデルと温度を変える。 * 自動化のために最大ターン数や最大実行時間を制限する。 * 元の Markdown を編集せずにツールセットを絞る。 * 既存のローカル Subagent に MCP サーバーを追加する。 プラグイン提供の Subagent には追加の安全ポリシーが適用されます。`hooks`、`mcpServers`、`permissionMode` は削除され、`isolation` は `worktree` の場合だけ保持されます。 ### ローカル Subagent の全フィールド 以下のフィールドは Markdown frontmatter で使えます。不明なフィールドは無視されます。 | フィールド | 必須 | 値 | 意味 | | ----------------- | :-: | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | `name` | はい | 空でない文字列 | Subagent 名。自然言語で指定しやすい、明確で安定した名前を推奨します。 | | `description` | はい | 空でない文字列 | この Subagent をいつ使うかの説明。Qoder CLI は選択時にこれを使います。 | | `background` | いいえ | ブール値 | デフォルトでバックグラウンド起動するかどうか。バックグラウンド Subagent セッションが有効である必要があります。 | | `color` | いいえ | `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan` | TUI で Subagent を実行しているときに表示される色。 | | `disallowedTools` | いいえ | 文字列または文字列配列 | ツール拒否リスト。ツール登録後に指定ツールを取り除きます。 | | `effort` | いいえ | `low`、`medium`、`high`、`xhigh`、`max`、または正の整数 | 推論強度または予算。 | | `hooks` | いいえ | Hook 設定オブジェクト | この Subagent セッションにだけ作用する frontmatter hooks。 | | `initialPrompt` | いいえ | 文字列 | この定義を `--agent` でセッションのメイン Agent として使う場合の初期プロンプト。通常の Subagent 呼び出しではタスクプロンプトとして注入されません。 | | `isolation` | いいえ | `worktree` を推奨 | 分離方式。`worktree` は別の git worktree で Subagent を実行します。未設定時は既定のワークスペースを使います。 | | `kind` | いいえ | `local` | 種類。省略するとローカル Subagent として扱われます。リモート Subagent は `remote` を使います。 | | `maxTurns` | いいえ | 正の整数 | 1 回の Subagent 呼び出しの最大会話ターン数。 | | `mcpServers` | いいえ | サーバー名配列、インラインサーバーオブジェクト、またはその組み合わせ | この Subagent 用の追加 MCP 検出。実際に使えるかどうかは引き続き `tools` と `disallowedTools` によって制御されます。 | | `memory` | いいえ | `user`、`project`、`local` | この Subagent の永続メモリスコープ。グローバル自動メモリが有効な場合だけ動作します。 | | `model` | いいえ | 任意のモデル名またはモデル別名。よく使う値は `inherit`、`auto`、`lite`、`efficient`、`performance` | この Subagent が使うモデル。省略時は `inherit` で、現在の会話モデルを継承します。 | | `permissionMode` | いいえ | `default`、`acceptEdits`、`bypassPermissions`、`dontAsk`、`auto`、`plan` | この Subagent の権限モード。未指定時は親セッションの現在のモードを継承します。 | | `skills` | いいえ | 文字列または文字列配列 | この Subagent が使える Skills を制限します。 | | `temperature` | いいえ | 数値 | モデル温度。省略時は loader が既定の温度設定を書き込みます。 | | `timeoutMins` | いいえ | 正の整数 | 1 回の Subagent 呼び出しの最大実行時間（分）。 | | `tools` | いいえ | 文字列または文字列配列。`*` を使用可能 | ツール許可リスト。省略時は現在利用可能なツールセットを使い、`*` は全ツールを意味します。 | ## 効果をテストする Subagent を作成または編集した後は、次の順序で確認してください。 1. `/agents reload` を実行するか、新しいセッションを開始します。 2. `/agents` または `qodercli agents list` で、期待したソースに表示されることを確認します。 3. `description` がいつ使うべきかを明確に説明しているか確認します。 4. 一度、名前を明示して呼び出します。 ```text theme={null} Use the api-reviewer subagent to review this API: POST /login GET /logout ``` 5. 読み取り専用として設定している場合は、ファイルを変更しないよう依頼し、書き込み操作が出ないことを確認します。 6. `disallowedTools` を設定している場合は、禁止された能力を依頼し、別手段を選ぶか制限を説明することを確認します。 7. MCP を使う場合は、対象 MCP ツールが検出され、`tools` によってブロックされていないことを確認します。 8. `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/.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` を省略した場合も、親セッションの現在のモードを継承します。 ### バックグラウンド Subagent の結果はどこで確認できますか？ バックグラウンド実行では、メインセッションはまず起動結果を受け取ります。タスク結果は後から完了通知として届きます。通知が届く前に期待結果を要約しないでください。 ### 組み込みまたはプラグイン Subagent を編集できますか？ 組み込みとプラグイン Subagent は直接編集するものではありません。代わりにユーザーレベルまたはプロジェクトレベルの Subagent を作成してください。同名で上書きする場合は、ソース優先度とプラグイン安全ポリシーに注意してください。