【Claude Codeサブエージェント入門 第4回】toolsと返す形 ― toolsで担当の道具を絞る、返す形と「遭遇した障害」の欄、反映のタイミングと読み込まれない定義

Claude Codeサブエージェント入門 第4回 toolsと返す形 生成AI

「調査だけを任せたいのに、担当がファイルを書き換えたり、勝手にコマンドを実行したりしないか心配です」
「担当の定義ファイルを置いたのに、担当の一覧に出てきません。エラーも出ないので、どこが悪いのか分かりません」

第3回(担当を定義する)では、担当(サブエージェント)の定義のファイルの形、フィールドの一覧、description の書き方を見ました。定義が書けても、何ができる担当にするかと、何をどんな形で返させるかを決めなければ、安全にも使いやすくもなりません。さらに、書いたはずの定義が、黙って読み込まれないことがあります。

第4回では、tools で担当のできることを絞る方法、返す形と「遭遇した障害」の欄、定義の反映のタイミングと読み込まれないときの原因を扱います。冒頭の1つ目の相談は「tools で『できること』を絞る」の節、2つ目の相談は「反映のタイミングと、読み込まれないとき」の節が答えです。数値・仕様は2026年10月時点です。


tools で「できること」を絞る

担当に使わせる道具は、定義の tools に書いて許可リストとして絞ります。役割ごとに、必要な道具だけを渡します。

役割toolsできること
調査(infra-researcher)Read, Grep, Glob読むだけ。変更できない
レビュー(playbook-reviewer)Read, Grep, Glob, Bash+git diff などの実行。Edit・Write なし
作成(playbook-writer)Read, Grep, Glob, Edit, Write, Bash+ファイルの編集・作成
省略書かない本体の道具を全部引き継ぐ。広すぎる
Bash の一部だけ止める権限ルール permissions.deny に Bash(git push *)担当にも本体にも効く(公式の sub-agents。ルールの書き方は連載「Claude Code実践入門」第6回)

表の3つの担当(infra-researcher・playbook-writer・playbook-reviewer)は、この連載で使う筆者の例です(役割とモデルの対応は第6回の「役割とモデルの対応(筆者の例)」、3つのひな形は第9回の「3役のひな形(筆者の例)」で扱います)。

tools で担当の「できること」を絞る様子を、4行で示した図。各行に Read・Grep・Glob・Bash・Edit・Write の6つの道具の札があり、使えるものは色付き、使えないものは破線の薄い札になっている。調査(infra-researcher)は Read・Grep・Glob だけで、読むだけ。変更できない。レビュー(playbook-reviewer)は Read・Grep・Glob・Bash で、+git diff などの実行。Edit・Write なし。作成(playbook-writer)は6つ全部で、+ファイルの編集・作成。tools を省略(書かない)は赤い札で6つ全部になり、本体の道具を全部引き継ぐ。広すぎる。最下行に、Bash の一部だけ止めるときは権限ルール permissions.deny に Bash(git push *) と書く(担当にも本体にも効く)とある。図の見出しは「tools で「できること」を絞る」。

補足:disallowedTools は外す一覧で、Bash(git push *) と書いても Bash 全体が外れます。tools に許可リストを書いた担当は、Agent を入れなければほかの担当を呼びません。tools を省いた担当は、既定では本体の下に3層まで担当を呼べます。出典:https://code.claude.com/docs/ja/sub-agents 、https://code.claude.com/docs/ja/tools-reference (tools は許可リスト)(deny のルールは本体にも担当にも効く、は sub-agents のページの記述)

表の読み方を、公式の記述に沿って補います。

  • 省略すると引き継ぐ:担当は、本体で使える組み込みの道具と MCP の道具を引き継ぎ、tools(許可リスト)と disallowedTools(外す一覧)の2つの絞り込みで狭められる。tools を書かない担当は、道具を全部引き継ぐ
  • 両方書いたときの順番:disallowedTools を先に適用し、残った道具に対して tools を解く。両方に書いた道具は外れる
  • Bash の一部だけ止める:disallowedTools に Bash(git push *) のような指定を書くと、一致するコマンドだけでなく Bash の道具ごと外れる。Bash を残して特定のコマンドだけ止めたいときは、settings の permissions.deny に Bash(git push *) を書く。この deny ルールは本体にも担当にも効く。ルールの書き方と限界は、連載「Claude Code実践入門」第6回の「allow・ask・denyルールの書き方」「前方一致の落とし穴と、denyの限界」で扱っています
  • 担当がほかの担当を呼べるか:既定では、担当が自分でさらに担当を呼べる(本体の下に3層まで)。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で段数を変えられ、1にすると入れ子を使えない(v2.1.217 以降)。入れ子が使える設定で、レビュー担当のように読むだけにしたい担当に呼ばせたくないときは、公式は tools の一覧に Agent を入れない(または disallowedTools に入れる)と書いています

筆者が非対話の claude -p(Claude Code 2.1.302)で試したところ、tools: Read, Grep, Glob, Bash のレビュー担当は、Edit を使わずに git diff・ansible-lint・構文チェックを実行して、結果を返してきました(演習は第13回の手順5)。


返す形と、障害の報告

担当は、作業の経緯を本体に見せず、最後に返す1通の報告だけを本体に渡します。その報告の形を、定義の本文に書いておきます。

  • 返す形を本文に書く:セクションを埋め終えたら止まる、という自然な止まりどころができる。書かないと、必要以上に長く走り続けやすい(Academy レッスン3)
  • 「遭遇した障害」の欄:回避策、特別なフラグが要ったコマンド、環境の癖を書かせる。本体が同じ回り道を繰り返さずに済む
  • 筆者の例:Ansible のコマンドは 2>&1 | cat を付けないと止まる。成否は PLAY RECAP で見る、と報告させる
  • 足さない一文:「あなたは○○の専門家です」(第2回の「使う・使わないの判断ルール」)

「筆者の例」の 2>&1 | cat は、Claude Code から Ansible を実行すると「Ansible requires blocking IO」で止まることがある、という筆者の環境の癖です(連載「Claude Code実践入門」第4回の「チームで共有するCLAUDE.mdのひな形(筆者の例)」の「環境の癖」で説明しています)。終了コードは cat の0になるので、成否は出力の PLAY RECAP で判断させます。

返す形は、定義の本文に次のように書きます(レビュー担当の例です)。

次の形で返してください。
## 概要
## 重大(直ちに直す)
## 主要
## 軽微
## 推奨
## 判定(そのまま進めてよいか)
## 遭遇した障害(回避策・特別なフラグのいるコマンド・環境の癖)
担当の本文に書く返す形(レビュー担当の例)を示した図。灰色の枠に、「次の形で返してください。」と、見出し「## 概要」「## 重大(直ちに直す)」「## 主要」「## 軽微」「## 推奨」「## 判定(そのまま進めてよいか)」「## 遭遇した障害(回避策・特別なフラグのいるコマンド・環境の癖)」が縦に並び、最後の「遭遇した障害」の行がオレンジの枠で囲まれている。右に2つの説明がある。緑「セクションを埋め終えたら止まる」は、自然な止まりどころができる、書かないと必要以上に長く走り続けやすい。オレンジ「「遭遇した障害」の欄」は、回避策、特別なフラグが要ったコマンド、環境の癖を書かせる、本体が同じ回り道を繰り返さずに済む。オレンジの矢印が説明から最後の行を指している。最下行に「足さない一文:「あなたは○○の専門家です」」とある。

補足:レビュー担当の返す形の例です。出典は Academy のレッスン3 https://academy.claude.com/ja/courses/introduction-to-subagents/designing-effective-subagents と、公式の Code reviewer の例です。

公式の Code reviewer の例は、読むだけのレビュー担当(Edit・Write を持たない)の本文で、「Critical issues (must fix)」「Warnings (should fix)」「Suggestions (consider improving)」の優先度順に返させています。「遭遇した障害」の欄は、Academy のレッスン3が勧めるものです(筆者が確認した範囲では、公式の例の担当に障害を報告させる節は見つかりませんでした)。

もう1つの止めどころとして、定義の maxTurns があります。担当が上限の回数に達すると、Claude Code は出力を「部分的な結果」と印を付けて返し、Claude は続きを再開できます(この印は v2.1.246 以降)。

筆者が試したとき、レビュー担当は「担当が確認したこと(lint 0・構文成功)」と「まだ確認していないこと(stg への --check --diff、冪等性)」を分けて返してきました。返す形に「判定」と「障害」の欄を持たせると、確かめていないことが報告に残ります。


反映のタイミングと、読み込まれないとき

定義のファイルを置いたら、すぐ使えるのか、それとも再起動が要るのか。そして、定義がなぜか読み込まれないとき、どこを見るのか。

  • 反映:.claude/agents/ への追加・編集(Claude に書かせた場合も)は数秒で反映され、再起動は要らない(公式)
  • 再起動が要る場合:セッション開始時に無かった agents フォルダーの最初のファイル、--add-dir で足したフォルダー、--disable-slash-commands のセッション。Code タブでの動きは筆者は確かめていない
  • 黙って読み飛ばされる:name が無い、先頭行が --- でない、name だけで description が無い、YAML の誤り
  • 筆者の CLI(2.1.289)で確かめた:description の無い定義は担当の一覧に出ず、エラーの表示も無かった。Code タブの表示は筆者は確かめていない
  • 点検:claude plugin validate .claude/agents(v2.1.233 以降)。Code タブで Claude に実行させられるかは、筆者は確かめていない
  • 使わせない担当:permissions.deny に Agent(名前)(組み込みにも効く)

補足:読み飛ばしの理由は claude --debug のログにだけ出ます。出典は https://code.claude.com/docs/ja/sub-agents です。

担当の定義の反映のタイミングと、読み込まれないときを示した図。上の緑の枠「反映のタイミング」に2つの箱がある。「すぐ反映される」は、.claude/agents/ への追加・編集(Claude に書かせた場合も)は数秒で反映され、再起動は要らない。「再起動が要る場合」は、セッション開始時に無かった agents フォルダーの最初のファイル、--add-dir で足したフォルダー、--disable-slash-commands のセッション。下の赤い枠「黙って読み飛ばされる4つの理由(エラーは出ない)」には、name が無い、先頭行が --- でない、name だけで description が無い、YAML の誤り、の4つの箱があり、矢印で「担当の一覧に出ない(エラーの表示も無い)」につながる。その下に、筆者の CLI(2.1.289)で確かめた結果として、description の無い定義は一覧に出ず、エラーの表示も無かったこと、理由は claude --debug のログにだけ出ること、点検は claude plugin validate .claude/agents であることが添えられている。

読み飛ばしと再起動について、公式の記述を補います。

  • 再起動が要る理由:Claude Code が監視するのは、セッションの開始時に存在した ~/.claude/agents/ と .claude/agents/ などのフォルダーだけ。新しく作ったフォルダーの最初のファイルは、再起動して読み込ませる
  • name が無い定義:読み飛ばされるというより、担当ではなく「担当のそばに置いた文書」として扱われる
  • name だけで description が無い定義:読み飛ばされ、理由はデバッグのログに書かれる。筆者の記録(2.1.289)の「一覧に出ず、エラーも出ない」と合う
  • フォルダーの中の定義を点検する:claude plugin validate に .claude/agents や ~/.claude/agents のフォルダーを渡すと、frontmatter が読めないファイルを見つけられる
  • デバッグのログ:Claude Code を --debug 付きで起動すると見られる

定義を Claude に書かせたとき、.claude/ の下への書き込みは保護されたパスなので確認の画面が出ます。筆者が claude -p(2.1.302)で準備を試したときも、3つの定義の書き込みは承認待ちになりました。確認の内容を見て許可すれば、数秒で担当として使えるようになります。


考えてみよう

  1. 調査だけを任せたい担当の tools は、どう書きますか。tools を書かなかったら、何が起きますか
  2. 担当を git push だけ止めたいとき、disallowedTools に Bash(git push *) と書くのと、permissions.deny に書くのとでは、何が違いますか
  3. 置いたはずの定義が担当の一覧に出ないとき、確かめるものを3つ挙げてください

ヒント:1は「tools で『できること』を絞る」の表、2は同じ節の補足、3は「反映のタイミングと、読み込まれないとき」の節を見直してください。


まとめ

  • tools は許可リスト。調査は Read, Grep, Glob(読むだけ)、レビューは+Bash、作成は+Edit, Write。書かないと本体の道具を全部引き継ぐ
  • Bash の一部だけ止めるには、disallowedTools ではなく permissions.deny の Bash(git push *)。disallowedTools に書くと Bash 全体が外れる。deny は担当にも本体にも効く
  • tools に許可リストを書き、Agent を入れなければ、担当はほかの担当を呼ばない。tools を省くと、既定で本体の下に3層まで呼べる
  • 返す形を本文に書くと、止まりどころができる。「遭遇した障害」の欄で、回避策・特別なフラグ・環境の癖を本体に返させる
  • .claude/agents/ の追加・編集は数秒で反映される。再起動が要るのは、新しい agents フォルダーの最初のファイル、--add-dir、--disable-slash-commands
  • name が無い、先頭行が --- でない、description が無い、YAML の誤りは黙って読み飛ばされる。理由は claude --debug に出る。claude plugin validate .claude/agents(v2.1.233 以降)で点検する

次回は、担当のモデルの決まり方(model に書ける値、決まる順番、別名で書く理由、組織の許可リスト)を扱います。


連載「Claude Codeサブエージェント入門」全13回

全回の目次と、読む順番・目的別の読み方は、Claude Codeサブエージェント入門の入口のページにまとめています。

  1. サブエージェントとは
  2. 組み込みの担当と使い分け
  3. 担当を定義する
  4. toolsと返す形(この記事)
  5. 担当のモデルの決まり方
  6. 役割とモデル・effort
  7. スキルから担当を呼ぶ
  8. 順に使う・前と裏
  9. ログの要約とレビューの担当
  10. 費用を測って小さく使う
  11. 演習(前編):準備
  12. 演習(中編):読み込む・呼ぶ・モデルを見る
  13. 演習(後編):レビュー・スキル・費用
seichan

プロフィール詳細は「プロフィール」をご覧ください。
AWS Certified Solutions Architect – Professional (https://www.credly.com/badges/fd8feb88-6f1f-42ff-a94b-445bb6661cb8/public_url)
Nutanix Certified Professional - Multicloud Infrastructure 6 (https://www.credly.com/badges/5c081bef-a425-42e4-809c-85138e676630/public_url)
Palo Alto Networks System Engineer (PSE) - Hardware Firewall Professional (https://www.credly.com/badges/69dc3880-4a51-47eb-8843-47ba6ea7d013/public_url)

seichanをフォローする
生成AI
シェアする
seichanをフォローする

コメント

タイトルとURLをコピーしました