はじめに

第2回も多くの方に読んでいただきありがとうございます、嬉しい限りです！

第2回では skillの frontmatter設計に絞り、description / when_to_use / TRIGGER when: / SKIP: の使い分けと Progressive Disclosureを掘り下げました。
これで「skillが呼ばれない問題」はほぼ解決したと思います。

ただ、ここまでは リーダー（メインのClaude）の挙動 の話でした。
本気でカスタマイズしようとすると、もう一つ大きな壁が立ちはだかります。それが subagent です。

第1回で軽く触れた model を省くとリーダーの Opusが継承される 問題、覚えてますでしょうか。
Agentツールを叩く度に Opusが起動して、軽い集計タスクなのにコストがじわじわ膨れる、いわゆる モデル指定忘れによるコスト爆発 です。

第3回はこの問題を構造的に解決する話、つまり 役割別subagentでモデルと toolsを固定する設計 を紹介します。
「教えてくれ Anthropic！」と毎回叫んでいるんですが、subagent定義のベストプラクティスもやっぱり公式 docsだけだと足りない、自分で組み上げるしかない。

この記事で得られること

  • subagentの モデル解決優先順位 4 階層 の実例ベースの理解、そして model 省略時の継承の罠
  • ~/.claude/agents/*.md に 8 役割 を定義してモデル・tools・memoryを固定する設計パターン
  • testerは Writeを持たない、reviewerは read-only、というような 責務に応じた最小権限化 の考え方
  • agentTeamsとの連携、teammateDefaultModel の役割と落とし穴

モデル解決優先順位 4 階層のおさらい — 省略するとリーダーが継承される

第1回でも触れましたが、subagentのモデルは以下の優先順位で決まります。

1. CLAUDE_CODE_SUBAGENT_MODEL 環境変数（全 subagentを強制上書き）
2. Agent tool 呼び出し時の model パラメータ
3. subagent 定義ファイルの model frontmatter
4. メインセッションのモデル（inherit / default）

ポイントは 4 番目「メインセッション継承」 です。
リーダーが Opusで動いているセッションで、Agent({subagent_type: "general-purpose", prompt: "..."}) のように model を省略すると、優先順位の上位 3 つが全部スキップされて、最下層の 継承 に落ちます。

つまり「ファイルを 30 個 grepしてリストアップする」みたいな軽量タスクで、Opusが本気を出してしまう。
1 タスクなら誤差ですが、これが agentTeamsで 5 並列とかになると、Opus × 5 が並列に走るんですよ、もはや投げ銭状態に。

これに気づかず 1 週間動かして請求書を見た瞬間、ｺﾞﾒﾝﾅｻｲと呟きながら Anthropicに頭を下げた記憶があります、本当に。

解決策: 役割別subagentでモデルを固定する

「Agentツール呼び出し時に毎回 model: "haiku" って書けばいいんじゃないの？」と思った方、鋭い、その通りです。
でもこれ 毎回書くの忘れます、人間だもの。

そこで効くのが優先順位 3 番目、subagent 定義ファイルの model frontmatter です。
~/.claude/agents/*.md に役割別の subagent定義を置いておけば、Agent({subagent_type: "tester"}) と呼ぶだけで、定義ファイルの model: haiku が自動適用されます。
リーダー側でモデルを意識しなくて良い、忘れても被害ゼロ、これが構造的解決です。

公式 docsにはこう書かれています:

Subagent definitions from any of these scopes are also available to agent teams. (Subagents 公式 より引用)

つまり、agentTeamsで teammateを spawnする時も 同じ subagent定義が再利用される ということ。
1 箇所にモデル・tools・memoryをまとめて固定しておけば、リーダー単独でも agentTeamsでも同じ挙動になります、これは良いものだ。

8 役割の subagent定義 — 私の運用構成

私は ~/.claude/agents/ 配下に 8 つの subagent定義を置いています。
役割と modelの対応はこんな感じです。

implementer（model: sonnet）

  • 用途: コード実装・修正専門。設計仕様に基づいて新規実装・既存コードの修正
  • tools: Read, Edit, Write, Bash, Grep, Glob
  • 思想: 実装は判断と精度が要るので sonnet、Edit/Writeも持つフル装備

tester（model: haiku）

  • 用途: テスト実行・結果集計のみ。設計判断はしない
  • tools: Read, Bash, Grep, Glob
  • 思想: テストを走らせて pass/fail 数を数えるだけなら haikuで十分、Writeを持たせない ことでテスト中に勝手にコードを直す事故を防止

reviewer（model: sonnet）

  • 用途: コード・設計書のレビュー、指摘のみで修正はしない
  • tools: Read, Grep, Glob, Bash
  • 思想: レビュー観点は sonnet級の推論が要る、ただし Edit/Writeを持たせない ことで「ついでに修正もしておきますね」事故を撲滅

auditor（model: sonnet）

  • 用途: 複数リポジトリ・モジュール間の横断整合性監査
  • tools: Read, Grep, Glob, Bash
  • 思想: 共有DBスキーマ・API契約・Enum等を比較するので sonnet、書き込みは不要

security-reviewer（model: sonnet）

  • 用途: OWASP Top 10、認証認可、入力検証等のセキュリティレビュー
  • tools: Read, Grep, Glob, Bash
  • 思想: 脆弱性パターンの推論は sonnet、reviewer同様 read-only

debugger（model: sonnet）

  • 用途: バグ調査・根本原因分析、再現→仮説→検証→修正
  • tools: Read, Edit, Bash, Grep, Glob
  • 思想: 仮説検証で修正トライが要るので Editを持つ、ただし Writeは不要（既存ファイル修正のみ）

data-scientist（model: sonnet）

  • 用途: SQL・BigQuery・データ集計・データ品質チェック
  • tools: Bash, Read, Write, Grep, Glob
  • 思想: クエリ実行と結果ファイル出力が要るので Bash + Write、Editは不要

researcher（model: haiku）

  • 用途: 深い調査専門の読み取り専用 subagent、依存関係追跡や履歴調査
  • tools: Read, Grep, Glob, Bash
  • 思想: 大量ファイル横断の調査は haikuで並列起動した方がコスト効率が良い、Edit/Writeは持たせず読み取り専用

ぱっと見、sonnet が 6 個・haikuが 2 個。
ポイントは testerと researcherを haikuに落としている ことです、ここを Opusや sonnetにしていると並列起動で死ぬ。

subagent定義ファイルの中身 — 実例

実際の ~/.claude/agents/tester.md の冒頭はこんな感じです。

---
name: tester
description: テスト実行・結果確認専門のエージェント。設計判断は行わず、既存テストの実行、結果の集計、失敗箇所の特定のみ担当する。PHPUnit/pytest/jestなど任意のテストフレームワーク対応。Use when:テスト実行と結果報告のみ必要、テスト失敗の一次切り分け、CI再現確認。Do not use when:テスト設計から必要（test-design skill+implementerを使う）、根本原因の深い分析（debuggerを使う）、テストコード修正が必要（implementerを使う）。
model: haiku
tools: Read, Bash, Grep, Glob
memory: user
---

あなたはテスト実行のスペシャリストです。設計判断はせず、テスト実行と結果報告に専念します。

frontmatterの 4 フィールドを順に見ていきます。

name

Agent({subagent_type: "tester"}) で呼ぶ時のキー。
ファイル名と一致させるのが流儀（tester.md なら name: tester）。

description

skillの descriptionと同じく 自動マッチング用 です。
Claudeが「この作業は testerに振るべきだな」と判断する材料、ここに Use when と Do not use when を両方書くと精度が上がります、skillと同じ TRIGGER/SKIP発想。

model

これが本記事の核、haiku / sonnet / opus を指定。
省略すると優先順位の 4 番目（リーダー継承）に落ちるので、必ず書く。
書き忘れるとコストが化けるので、定義作成時のチェックリストに入れておくと良いです。

tools

そのsubagentが使えるツールを列挙。
Edit/Writeを持たないと 絶対に書き込みができない ので、レビュー系の事故防止に効きます。
ここは絞れば絞るほど安全、デフォルトで全許可するくらいなら明示的にゼロから足す方が良い。

memory

memory: user で、CLAUDE.mdなどのユーザー設定をsubagent側にも読み込ませる指定。
これを書かないと subagentが CLAUDE.mdの前提ルール（日本語で返す、AskUserQuestion使う等）を知らずに動くので、運用上は ほぼ必ず付ける のが正解です。

tools最小権限化の威力 — testerは Writeを持たない

ここまでで「役割ごとに toolsを絞る」と何度か言いましたが、改めて整理します。
8 役割の tools構成を Edit/Writeの観点で見ると:

  • Edit/Writeあり: implementer / data-scientist（一部）
  • Editのみ: debugger
  • read-only（Read/Grep/Glob/Bash）: tester / reviewer / auditor / security-reviewer / researcher

read-onlyが 5 役割、半分以上が 書き込み禁止 という構成です。
これ意図的にこうしています、というのも…

「reviewerがレビュー中に勝手にコードを直し始めた」「testerがテストコードを書き換えてテストを通した」みたいな事故、過去にやらかしました。
頭ポンコツ状態でゆるふわプロンプトしちゃった時に限って、Claudeは気を利かせて「修正もしておきますね」と Editを叩いてくれます、気が利きすぎる。

なので 役割に対して不要なツールは最初から渡さない、これが防衛策です。
権限を持っていなければ、どれだけ気を利かせようとしても物理的に発火しない、これは確実。

allowed-tools（第2回で紹介した skill側のフィールド）が「skillレベルの権限制御」だとすると、agent定義の tools は「agentレベルの権限制御」。
レイヤーで権限を絞っておくと、組み合わせ事故が減ります、安心して agentTeamsを並列で回せる。

agentTeamsとの連携 — 同じ定義が再利用される

agentTeams（複数 subagentの並列オーケストレーション）を使う時、teammateの定義はどこから来るのか問題があります。
答えは 同じ ~/.claude/agents/ 配下から再利用される です、これは公式 docsにも書かれています。

つまり agentTeamsで 5 並列の researcherを spawnしても、5 つとも model: haiku・tools: read-onlyで起動します。
1 箇所で modelと toolsを固定しておくと、agentTeams側で毎回書く必要が無い、これは本当に楽。

例えば「3 つの仮説を並行検証したい」というケースで:

agentTeams起動
├── researcher（仮説1: 型比較バグの可能性）
├── researcher（仮説2: トランザクション境界の問題）
└── researcher（仮説3: 多言語切替の副作用）

3 並列で researcherが走りますが、全部 haiku なのでコストは軽量、しかも read-onlyなのでどれかが暴走しても被害ゼロ。
役割定義をしっかり仕込んでおくと、agentTeamsの心理的ハードルが一気に下がります。

teammateDefaultModel の落とし穴 — フォールバックは効くが油断は禁物

agentTeams関連でもう一つ重要な設定があります、/config の teammateDefaultModel です。

これは agentTeamsで spawnした teammateの subagent_typeを指定しなかった場合のデフォルトモデル を指定するフィールド。
私は sonnet に設定しています。

/config
teammateDefaultModel: sonnet

「役割を指定しなければ sonnetで動く」というセーフティネット、これがあるとリーダー継承で Opusが暴発するリスクを下げられます。

ただし落とし穴があって、teammateDefaultModel は subagent_typeを明示した時には効きません。
あくまで「subagent_type無し spawnのフォールバック」です。
つまり Agent({subagent_type: "tester"}) と呼べば tester.md の model: haiku が優先される、これは正しい挙動。

問題は subagent_typeを指定しないケースが何かの拍子に発生した時。
例えば agentTeamsで「general-purposeにとりあえず任せる」みたいな雑な spawnを Claudeがやりがちで、その時に teammateDefaultModel が無いとリーダー継承で Opusが起動してしまいます。

なので:

  • agents/*.md で modelを固定 → 主たる防衛線
  • teammateDefaultModel でフォールバック → 二次防衛線

の二段構えにしておくのが安心です、保険は厚いに越したことない。

カスタマイズ前後の定量比較

役割別subagent定義を導入する前後で、どう変わったかを観点ごとに整理します。

モデル指定の信頼性

  • Before: Agent呼び出し時に model を毎回指定、忘れるとリーダー継承で Opus起動
  • After: subagent_type だけで定義ファイルの modelが自動適用、書き忘れ事故ゼロ

コスト

  • Before: 軽量タスク（テスト実行・ファイル検索）でも Opus が走る、agentTeams並列で乗算
  • After: tester/researcherは haiku固定、5 並列でも haiku × 5 で済む

権限事故

  • Before: reviewerが「ついでに修正しておきますね」と Editを叩く、testerがテストコード書き換え
  • After: tools最小権限化で物理的に書き込み禁止、暴走しても被害ゼロ

agentTeams起動のしやすさ

  • Before: 並列起動するたびに modelと toolsを心配して構成、心理的ハードル高
  • After: 役割を指定するだけで全 teammateに modelと toolsが適用、気軽に並列起動できる

コードレビューでの差分

  • Before: 「Agent呼び出しに model指定が無い」がレビュー指摘の常連
  • After: subagent_type 指定で十分、レビュー観点が一つ減った

役割別subagent運用のチェックリスト

ここまでの内容を、新規 subagent定義を作る時のチェックリストに落とすとこうなります。

  • [ ] name をファイル名と一致させた
  • [ ] description に Use when / Do not use when を両方書いた
  • [ ] model を明示した（省略すると継承で Opus が暴発する）
  • [ ] tools を必要最小限に絞った（書き込みが不要なら Edit/Writeを外す）
  • [ ] memory: user を付けた（CLAUDE.mdの前提ルールを引き継ぐ）
  • [ ] 既存 8 役割と重複していないか確認した

特に 3 つ目の model 明示、これは何度も言いますが 絶対に書きましょう。
書き忘れたまま運用すると、本当にある日請求書を見て涙を流すことになります。

次回: skillの発動率を観測してメンテする

第4回（Claude Codeを本気でカスタマイズしてみた:【第4回】skill発動率の観測）では、いよいよシリーズ最終回。
ここまで作り込んだ skill・subagentが「本当に思った通り発動しているのか」を観測する話に踏み込みます。

  • PostToolUse フックで skill発動ログを蓄積する仕組み
  • 発動率の可視化（どの skillが呼ばれていない／呼ばれすぎているか）
  • description調整 → 観測 → 再調整、のフィードバックループ
  • 副作用 skill（commit, voice等）の誤発火検出

「作って終わり」ではなく 作ってからのメンテループ が運用の本番、というシリーズ完結編です。
お楽しみに、と言いたいところですが、実は私もまだ観測基盤を絶賛改修中です、ｺﾞﾒﾝﾅｻｲ。

シリーズ全 4 回の予定

  1. Claude Codeを本気でカスタマイズしてみた:【第1回】4つの拡張点
  2. Claude Codeを本気でカスタマイズしてみた:【第2回】skillの自動発動
  3. 本記事: Claude Codeを本気でカスタマイズしてみた:【第3回】役割別subagentでモデルを固定する
  4. Claude Codeを本気でカスタマイズしてみた:【第4回】skill発動率の観測（近日公開）

参考リンク