この記事でやること
Claude Code のサブエージェント（Agent tool / .claude/agents/）に作業を委譲すると、検証もせずに「完了しました」と帰ってくることがあります。実際に運用していて頻発したこの問題を、委譲プロンプトの書き方で潰します。
- サブエージェントが早期終了する4つの原因
- 委譲プロンプトに必ず含める5項目のテンプレート（コピペ可）
- エージェント定義ファイル側に入れる「自己点検チェックリスト」の実例
- そもそも委譲すべきかの判断軸
前提
- Claude Code がインストール済みで、サブエージェント（Agent tool）を使ったことがある
- カスタムエージェントは
~/.claude/agents/または.claude/agents/に Markdown で定義できる
なお、サブエージェントのモデルを切り替えてコストを下げる話は別記事に書いています → Claude CodeのAgent toolでサブエージェントのモデルを切り替えてトークンコストを下げる
症状：サブエージェントは「だいたい完成」で帰ってくる
数ヶ月サブエージェントを運用して、繰り返し起きた失敗パターンは次の3つでした。
- 「だいたい完成」で終了する — 指示の8割だけやって完了報告してくる
- 検証せずに完了報告する — build も test も走らせず「実装しました」
- エラーを独断で握りつぶす — 途中でエラーに遭遇すると、報告せずスコープを勝手に縮めて完了扱いにする
サブエージェントはメインセッションとコンテキストを共有しません。こちらが暗黙に期待している「当然テストは通してから戻ってくるよね」は、プロンプトに書かない限り存在しないのがすべての原因です。
原因は4つ
| # | 原因 | 何が起きるか |
|---|---|---|
| 1 | 完了条件が曖昧 | エージェントが「完了」を自己判定する。基準が甘い側に倒れる |
| 2 | 検証ステップの欠落 | typecheck / build / test を指示しないと実行されない |
| 3 | 判断が必要なタスクを下位モデルに委譲 | コスト目的で小さいモデルに投げた設計判断が雑になる |
| 4 | 報告フォーマットの指示なし | 「やりました」の一文だけ返ってきて、検証のしようがない |
このうち体感で最も効くのは 3 です。定型作業のコスト削減に下位モデルを使うのは有効ですが、「判断」が混ざるタスクを渡すと手戻りで逆に高くつきます。
委譲プロンプトの必須5項目（テンプレート）
上の4原因を潰すために、委譲プロンプトへ必ず次の5項目を入れます。そのまま使えるテンプレートです。
## タスク
（作業内容を1〜2文で）
## 完了条件（すべて満たすまで完了と報告しないこと）
- [ ] `src/features/foo/bar.ts` の `parseConfig()` を実装
- [ ] `npm run typecheck` がエラー0で通る
- [ ] `npm run test -- bar.test.ts` が全件パス
## 検証（実行必須）
完了報告の前に以下を実行し、出力をそのまま報告に含めること：
- `npm run typecheck`
- `npm run test -- bar.test.ts`
## 禁止事項
- 「だいたい完成」での終了
- 検証コマンド未実行での完了報告
- エラーに遭遇した際の独断での無視・スコープ縮小
## 詰まったとき
作業を放棄せず、「何が不明か」「何を試したか」を具体的に報告して指示を仰ぐこと。
## 最終報告フォーマット
1. 変更ファイル一覧（パス）
2. 検証コマンドの実行ログ（生出力）
3. 完了条件チェックリストの充足状況
ポイントは2つです。
-
完了条件はファイル名・関数名・コマンド名まで具体化する。「バリデーションを追加」ではなく「
parseConfig()を実装しbar.test.tsを通す」。曖昧さの分だけエージェントは甘い側に倒れます - 検証ログの生出力を報告に含めさせる。「テスト通りました」という自己申告は信用せず、ログで確認します
エージェント定義ファイル側にも「自己点検チェックリスト」を入れる
毎回の委譲プロンプトに加えて、.claude/agents/ の定義ファイル側にも返却前の自己点検を仕込んでおくと、プロンプト側の書き漏れを補えます。
実際に運用している監査系エージェントの定義ファイルの末尾は、こうなっています。
# チェックリスト（返却前に自己点検）
- [ ] 対象ファイル・ライブページ・実データを実際に取得した（記憶で判定していない）
- [ ] 各指摘に根拠を添えた（不明なものは「要判断」と明記した）
- [ ] 影響度で層別した
- [ ] 修正を一切実行していない（報告のみの役割のため）
- [ ] 確認した範囲（見たファイル・ページの一覧）を明記した
特に効いているのは最後の項目です。「見た範囲の一覧」を報告させると、「全部確認しました（実際は一部）」という網羅性の誤認をこちらが検出できます。
そもそも委譲すべきかの判断軸
テンプレート以前の問題として、委譲しない方が速いタスクを委譲しているケースも多くありました。サブエージェントはコンテキスト非共有のため、状況説明のコストが毎回かかります。運用の結果、委譲に構造的メリットがあるのは次の3型だけでした。
| 型 | 例 | 委譲する理由 |
|---|---|---|
| 大量読み込み | 数百ファイルの全件スキャン・裏取り調査 | メインセッションのコンテキストを食い潰すため分離必須 |
| 独立検証 | 成果物とルールの突き合わせ監査 | 作った本人は自分の盲点を検証できない |
| 並列バッチ | 5件超の同型作業・複数案の比較 | 並列化の恩恵が説明コストを上回る |
逆に、実装・設計判断・バグ修正はメインセッション直営が基本です。文脈を全部持っている側がやる方が、委譲のオーバーヘッドより安くて正確でした。
追加の工夫3つ
テンプレートと併用して効果があったものです。
- チェックリスト駆動にする — 「最初にタスクのチェックリストを作成し、各項目の完了時に更新すること」と指示する。進捗が構造化され、途中放棄が見えやすくなる
- worktree で隔離する — ファイルを変更させる場合は git worktree 上で作業させると、失敗してもメイン環境が汚れず、リトライが安全になる
- 小分けに委譲する — 1エージェント＝1ファイル変更程度まで分解する。大きく渡すほど「だいたい完成」の余地が生まれる
まとめ
- サブエージェントの早期終了は、完了条件・検証・禁止事項・詰まったときの行動・報告フォーマットの5項目をプロンプトに明示すれば大部分が防げる
- 検証は「実行したログの生出力」で確認する。自己申告は信用しない
- 判断が必要なタスクを下位モデルに渡さない
- そもそも委譲は「大量読み込み・独立検証・並列バッチ」の3型に絞り、それ以外はメインセッション直営にする
サブエージェントを「部署」に見立てた組織運用の設計論は、こちらにまとめています → 「AI組織」は組織図から作ると失敗する｜1人会社をAI会社化する正しい順序
SEOスコアチェックツール: SEO_CHECK — RINIAディレクターツール。
Web制作・SEO関連の技術情報サイト: CodeQuest.work