この記事は playpark Blog からの転載です。
この記事で分かること
- Claude Code subagent の呼び出しで品質がばらつく根本原因
- 呼び出しプロンプトに必ず含めるべき5つの要素と、その選定理由
- どの要素を省略するとどのトラブルが起きるか
背景：「subagentが不安定」の正体
Claude Code の Task tool で subagent を呼び始めると、こういう疑問が出てきます。
「同じ依頝を投げているのに、返ってくるフォーマットが毎回違う」
「探索タスクのはずなのに、勝手にファイルを書き換えてくる」
「token消費が読めない」
最初は「モデルの挙動が安定しない」と思いがちですが、実際の原因は別にあります。
なぜ呼び出しプロンプトが品質を決めるのか
Claude Code の Task tool では、呼び出した側のコンテキストに返ってくるのは subagent の 最終出力だけ です。途中の Read / Grep / WebFetch などの操作ログはメインセッションに流れ込みません。
これは便利な分離（context isolation）ですが、裏返すと 「呼び出し時点のプロンプトが subagent に与えられる唯一の指示」 になることを意味します。メインが途中で軌道修正できない構造なので、プロンプトの品質がそのまま出力品質に直結します。
Anthropic の Multi-agent research system 解説 でも、delegation 品質が成否の大半を決めると報告されています。
選択肢の検討：なぜ「5要素固定」を選んだか
呼び出し品質を担保する方法は複数あります。
| アプローチ | メリット | デメリット |
|---|---|---|
| 都度レビューで口頭指摘 | 柔軟、ルール化不要 | Skill が増えると人的コストが線形増加 |
| チェックリスト文書化 | 記録が残る | 読まれない、適用忘れが起きる |
| プロンプト構造を仕様化 + lint | 機械的に担保、新規Skillにも自動適用 | 初期設計コストがかかる |
「都度レビュー」は Skill が10本を超えたあたりからコストが見合わなくなります。「文書化」は実際には守られませんでした。結果として、プロンプト構造そのものを仕様として固定し、lint で機械的に検査する アプローチを選びました。
なぜこの5要素か
仕様化した要素と、各要素が対処するトラブルの対応は以下のとおりです。
| 要素 | 対処するトラブル | 省略したときの症状 |
|---|---|---|
| Objective | 終了条件なし問題 | subagent が延々と探索し続ける |
| Output format | フォーマットばらつき | 同じ依頼でも毎回別の体裁が返る |
| Tools | 副作用漏れ | 探索タスクなのにファイルを書き換える |
| Boundary | スコープ膨張 |
node_modules/ に潜り込んでtokenが溶ける |
| Token cap | 出力量無制限 | 「簡潔に」と書いても500行レポートが返る |
特に Token cap の「簡潔に」が機能しない、という点は見落とされやすいです。「簡潔」は定性的な表現で、モデルが「自分の判断で簡潔なもの」を返します。「1500語以内」「上位10件まで」のような計測可能な数字でないと担保できません。
実装例：5要素テンプレート
Task(
subagent_type: "general-purpose",
description: "Short 3-5 word description",
prompt: """
## Objective
[単一の明確なゴール - 完了条件が自明なもの]
## Output format
[JSON schema / Markdown section / 語数上限]
## Tools
- 使用可: Read, Grep, Glob
- 禁止: Bash, Write, Edit, WebFetch
## Boundary
- 除外: vendor/, node_modules/, dist/
- 禁止: commit, git 操作, ネットワーク
- scope: <対象ファイル/ディレクトリ>
## Token cap
- 出力: 1500 語以内
- 最大探索ファイル数: 20
"""
)
Objective の書き方ポイント: 「調べる」「確認する」ではなく、「〇〇が A か B かを判定する」「〇〇のリストを返す」と書く。判定結果か成果物か、どちらが返ってくるべきかを明示することが重要です。
まとめ：どういう場面で使うべきか
subagent を呼ぶ dispatch が増えてきたタイミング（目安：同一リポジトリ内で5個以上）で、この5要素を「全 dispatch の最低ライン」として導入するのが費用対効果が高いです。
dispatch が少ないうちは都度確認で回せますが、Skill が増えると「このdispatchはToken capあったっけ」というレビューコストが積み上がります。早めに構造化しておくほうが結果的にコストが低くなります。
さらに深掘りしたい方へ
この記事では subagent 呼び出しプロンプトの5要素と、その選定理由を解説しました。
エージェントへの「丸投げ指示」をやめる――Claude Codeのsubagent運用ルール ではさらに：
- タスク性質（探索 heavy / 実装 / plan / review）ごとの subagent routing 表と判断軸4つ
- 全 SKILL.md を走査して5要素を CI で強制する lint スクリプトの実装詳細
- 「dispatch ばらつき → Skill I/O 設計の再整理」という構造的な副作用の経緯
playpark について
playpark LLC - 業務自動化・AI活用・Web開発
