この記事は playpark Blog からの転載です。
この記事で分かること
- サブエージェント呼び出しで
model/effortをなぜ毎回明示すべきか - 「省略」「都度明示」「明示+バリデーション」の3つのアプローチの比較
- どういう場面でこの運用が向いているか
背景: こういう課題があった
Claude Codeでは、Workflow や Skill からサブエージェントを呼ぶ際に model と effort を省略しても動作する。エラーにもならないため、軽い作業ほど省略しがちになる。ところが省略したときの挙動は「ちょうどいい中間値」ではなく、親セッションの設定をそのまま引き継ぐというものだった。親セッションがopusのxhighで動いていれば、typo修正やJSON整形のような軽い処理を投げたサブエージェントも、同じopusのxhighで動く。
選択肢の検討
サブエージェントのmodel/effortをどう扱うか、実務では大きく3つのアプローチがある。
| アプローチ | メリット | デメリット |
|---|---|---|
| 省略（暗黙継承に任せる） | 呼び出しコードが最短で書ける | 軽い作業でも親の重い設定をそのまま継承し、コスト・時間が想定外に膨らむ |
| 呼び出しごとに毎回明示 | 用途に応じてコストと速度を最適化できる | 呼び出し側が指定を忘れるとtypoや漏れのリスクが残る |
| 明示 + 保存前バリデーション（採用） | 指定漏れとtypoの両方を機械的に防げる | フック等の追加実装が要る |
なぜこのアプローチを選んだか
決め手は、「継承がデフォルトの安全側ではなく重い側に倒れる」という挙動そのものにある。原則を「軽量・機械的な作業はhaiku+low、重い判断だけopus+上位effort」と決めても、それを守れるかは呼び出し側が毎回どれだけ律儀に明示するかにかかっている。原則を唱えるだけでは実践されない。
さらに、effortはskillやagentのfrontmatterにも書けるため、hihgのようなtypoやxtrahighのような不正値を書いてしまうリスクもある。目視レビューでは案外見逃す。そこで「明示する運用」と「書いた値が壊れていないか機械的に検証する層」をセットで用意することにした。
実装例
呼び出し側の書き方はこう変わる。
// Bad: 何も指定しない → 親セッションのopus/xhighをそのまま継承する
{ "subagent_type": "general-purpose", "prompt": "このJSONをキー順に整形して" }
// Good: 軽量・機械的な作業だと分かっているなら明示する
{ "subagent_type": "general-purpose", "model": "haiku", "effort": "low",
"prompt": "このJSONをキー順に整形して" }
frontmatterに書いた値の検証は、保存前に閉じたenumでチェックするだけの単純なスクリプトで実現できる。
#!/usr/bin/env bash
# validate-effort.sh: 引数で受け取ったeffortの値を閉じたenumで検証する
echo "$1" | grep -qE '^(low|medium|high|xhigh|max)$' && echo "OK: $1" || { echo "NG: '$1' is not a valid effort tier"; exit 1; }
このチェックをPreToolUseフックの入り口に置けば、typoの混入をレビュー前に止められる。
まとめ: どういう場面で使うべきか
Workflow やSkillからサブエージェントを頻繁に呼ぶ構成であれば、model/effortの明示とバリデーションはセットで用意しておく価値がある。逆に単発のサブエージェント呼び出ししかない小規模な運用なら、まずは明示だけを徹底し、frontmatterでの管理が増えてきた段階でバリデーション層を足す、という順序でも十分だと思う。
さらに深掘りしたい方へ
この記事ではサブエージェントのmodel/effort継承問題と、明示+バリデーションというアプローチを選んだ理由を解説しました。
Claude Code の effort 設定、サブエージェント任せにすると高くつく理由 ではさらに：
-
effortLevelの既定値を実際に上げ下げした判断と、フォーマット変更・意味変更を混ぜて失敗した反省 - Codex CLIなど他のエージェント型コーディングツールとの設定名対応表
- 「上げれば安全」に対する反証と、実務チェックリスト
を扱っています。
playpark について
playpark LLC - 業務自動化・AI活用・Web開発
