Haiku 5.5をClaude Codeの読み取り専用サブエージェントに使い、実行モデルを検証する

安全な設計は、Claude Codeのセッション全体を小型モデルへ切り替えることではありません。Haiku 5.5に任せるのは、範囲が明確で、読み取り専用で、結果を確認しやすい作業だけにします。たとえば、シンボル参照の検索、import経路の追跡、設定ファイルの特定、指定したファイル群の要約です。判断、編集、テスト、最終承認はSonnetまたはOpusを使うメイン会話に残します。

設定が正しいことを示すには、プロンプトに「Haikuを使う」と書いたり、ファイルにmodel: haikuと置いたりするだけでは不十分です。次の3層を確認してください。エージェント定義に書かれた明示的なモデル、実行中のタスクについてClaude Codeが表示するモデル、そしてプロバイダーのリクエスト記録に残った実際のModel IDです。この3つが一致して初めて、切り替えを検証済みと扱えます。

委譲できる作業を決める

AnthropicはHaiku 5.5を、要約、コンパクション、データベース問い合わせ、分類など、速く反復的な作業向けに位置付けています。また、Sonnet 5.5やOpus 5.5と組み合わせるコーディング用サブエージェントとして明示的に説明しています。一方、複雑なエージェント型コーディングには、引き続き大きなモデルを推奨しています。詳しくはHaiku 5.5の公式発表を参照してください。

最初は次の分担が実用的です。

作業	推奨担当	理由
クラス、関数、設定の全参照箇所を探す	読み取り専用の小型モデル・サブエージェント	入力、出力、終了条件が明確
1つのディレクトリにあるファイルの役割を要約する	読み取り専用の小型モデル・サブエージェント	必要なのは読解と統合であり、変更ではない
エントリーポイントからDB呼び出しまでリクエスト経路を追う	読み取り専用の小型モデル・サブエージェント	ファイルパスと行番号で検証できる
アーキテクチャ、移行戦略、セキュリティ境界を決める	Sonnet／Opusのメインエージェント	広い文脈でのトレードオフと重要な判断が必要
コード変更、マイグレーション、依存関係更新、権限変更	Sonnet／Opusのメインエージェント	ワークスペースを変えるため厳格なレビューが必要
調査後に最終修正を決めて実装する	Sonnet／Opusのメインエージェント	証拠を統合し、結果に責任を持つ必要がある

判断基準は簡単です。「何を探すか」「何を返すか」「どこで止めるか」を1文で言え、ファイルを書き換えずに終えられるでしょうか。そうでなければ、メイン会話に残してください。

4種類のモデル制御を区別する

Claude Codeには、混同しやすい複数のモデル制御があります。

1. メイン会話のモデル： /model、起動オプション、設定から選びます。
2. サブエージェントのfrontmatterにあるmodel： そのエージェント定義に適用されます。
3. エイリアスと完全なModel ID： haikuはエイリアスで、解決先はプロバイダーやバージョンにより変わり得ます。claude-haiku-5-5はAnthropicが公開した完全なIDです。
4. 1役割だけの上書きと全体上書き： Exploreという名前のカスタムエージェントは組み込みExploreだけを置き換えます。CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1は、ほぼすべてのサブエージェントに影響します。

現在の公式サブエージェント文書では、モデルは次の優先順位で解決されます。呼び出しごとのモデル、エージェント定義のmodel、CLAUDE_CODE_SUBAGENT_MODEL、最後にメイン会話のモデルです。したがって、CLAUDE_CODE_SUBAGENT_MODELだけでは既定値にすぎず、エージェント定義や個別呼び出しに上書きされる可能性があります。Claude Codeのサブエージェント文書も確認してください。

この構成では、まず明示的な名前を持つ読み取り専用エージェントを1つ作ります。最初からグローバルな強制上書きを使わないでください。Plan、general-purpose、teammate、workflowなどのエージェントまで小型モデルへ移る可能性があるためです。

手順1：Claude CodeのバージョンとプロバイダーのIDを確認する

まずクライアントのバージョンを確認します。

claude --version

バージョンにより、操作画面と検証方法の両方が変わります。

• Claude Code v2.1.198以降では、/agentsは作成ウィザードを開きません。Claudeにファイルを作らせるか、.claude/agents/または~/.claude/agents/を直接編集するよう案内します。
• v2.1.197以前では、/agentsがRunningとLibraryタブを持つ対話型ウィザードを開きます。
• v2.1.242以降では、/tasksが実行中のサブエージェント行にモデルを表示します。古い版では、プロバイダーのリクエスト記録をより重視してください。
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1は、すべてのサブエージェントへ同じモデルを意図的に適用したい場合だけ使います。この動作にはv2.1.257以降が必要です。

次に、利用中のプロバイダーが受け付ける正確なIDを確認します。

• Anthropic Claude APIにおけるHaiku 5.5の公式Model IDはclaude-haiku-5-5です。公式モデルページを参照してください。
• クラウド基盤やサードパーティーのゲートウェイでは、同じIDがすでに使えるとは限りません。デプロイ名、独自エイリアス、選別されたカタログが使われることがあります。
• このガイドを2026年10月10日に確認した時点で、BetterTokenの公開カタログにはclaude-haiku-4-5-20251001、claude-sonnet-5-5、claude-opus-5-5がありましたが、claude-haiku-5-5はありませんでした。BetterTokenを使う場合、新しいAnthropicのIDをそのままコピーせず、現在のカタログに実在するIDを選んでください。現在のBetterTokenカタログで確認できます。

「Anthropicがモデルを公開した」と「自分のゲートウェイがそのモデルを提供している」は別の事実です。プロバイダーのカタログにIDがない場合、自然言語の指示やファミリー名のエイリアスだけから利用可能だと推測しないでください。

手順2：プロジェクト用の読み取り専用サブエージェントを作る

プロジェクトエージェントは.claude/agents/に置き、リポジトリと一緒に管理できます。~/.claude/agents/に置くユーザーエージェントは、複数プロジェクトで利用できます。

リポジトリのルートでプロジェクト用ディレクトリを作ります。

mkdir -p .claude/agents

.claude/agents/repo-researcher.mdを作成します。Anthropic Claude APIを使う場合は、次の定義を利用できます。

---
name: repo-researcher
description: Finds symbols, traces call paths, and summarizes selected files before code changes. Use only for bounded read-only repository research.
tools: Read, Grep, Glob
model: claude-haiku-5-5
---

You are a read-only repository researcher.

For each task:
1. Search only the scope named by the caller.
2. Do not edit, create, delete, or rename files.
3. Return file paths and line numbers for every important finding.
4. Separate direct evidence from inference.
5. Stop when the requested question is answered; do not propose unrelated refactors.

Return:
- Findings
- Evidence: file:line
- Uncertainties
- Suggested next check for the main agent

重要なのは次の3点です。

• toolsはRead、Grep、Globだけを許可し、Write、Edit、Bashを与えていません。
• descriptionが委譲すべき場面を説明するため、メインエージェントが変更作業を誤って送る可能性を下げます。
• modelには、単にHaikuを使うよう頼む文ではなく、プロバイダーが受け付ける完全なIDを指定します。

Claude CodeをBetterToken経由で接続する場合、確認時のカタログにあった小型Claudeモデルは次のとおりです。

model: claude-haiku-4-5-20251001

これは現在のカタログを使った例であり、永続的な保証ではありません。マッピングを変更する前に、カタログまたはModel Plazaを再確認してください。BetterTokenのClaude Code文書は、正確なModel IDを使用し、ANTHROPIC_BASE_URLをhttps://bettertoken.aiに設定して、末尾に/v1を付けないよう案内しています。BetterTokenのClaude Code設定ガイドを参照してください。

現在のセッション開始時に.claude/agents/が存在せず、作成後もClaude Codeが新しいエージェントを認識しない場合は、Claude Codeを一度再起動します。公式文書では、セッション開始時になかった最初のagentsディレクトリは、実行中のwatcherが検出しない場合があると説明されています。

手順3：メインエージェントはSonnetまたはOpusのままにする

メイン会話のモデルは別に選びます。たとえば次のように指定します。

/model sonnet

または：

/model opus

ゲートウェイを使う場合、エイリアスの背後で最終的に使われるモデルは、そのゲートウェイのマッピングに依存します。特定バージョンへ固定したい場合は完全なプロバイダーIDを使用し、その後にプロバイダー記録で確認してください。

1つの調査エージェントだけを小型モデルにするために、グローバルなforce変数を設定してはいけません。次の設定は、はるかに広い範囲へ作用します。

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Plan、general-purposeサブエージェント、teammate、workflowエージェントまで同じモデルへ従わせたい場合だけ使ってください。自動的なコード探索だけを変えたい場合は、Exploreという名前のプロジェクトまたはユーザーエージェントを定義し、その定義だけにmodelを指定します。これにより組み込みExploreだけが置き換わり、他のサブエージェントは変わりません。

手順4：監査できるテストでエージェントを起動する

最初から「リポジトリ全体を理解して」と頼まないでください。人間が確認できる狭い課題を使います。

Use the repo-researcher agent to find every call site of PaymentService.createCharge.
Return file:line, the caller's purpose, and the path from the public entry point.
Do not edit files. Stop after covering this symbol and its direct callers.

実行後は次の4点を確認します。

1. メイントランスクリプトにrepo-researcherへの委譲行があり、メインエージェントが黙って自分で検索していないこと。
2. サブエージェントがファイルパスと行番号を返し、直接の証拠と推論を分けていること。
3. 作業ツリーが変わっていないこと。

git status --short

4. 後続の判断やコード変更は、調査エージェントではなくメインエージェントが担当すること。

調査結果を残したい場合は、まずメイン会話で内容をレビューします。その後、メインエージェントに、承認した結果をプロジェクト文書やIssueへ保存させます。保存のためだけに調査エージェントへ書き込み権限を追加しないでください。

手順5：実際に実行されたモデルを検証する

1. エージェント定義を確認する。ただし、そこで終わらない

.claude/agents/repo-researcher.mdに意図した完全なIDがあることを確認します。ここで分かるのは静的設定だけです。個別呼び出しのモデル、組織ポリシー、ゲートウェイのマッピングによって、実際のリクエストは変わり得ます。

2. 実行中に/tasksを確認する

次を実行します。

/tasks

Claude Code v2.1.242以降では、サブエージェントの行にモデルが表示されます。ファイルの指定と異なる場合は、次を調べてください。

• Claudeが今回の呼び出しに別モデルを渡したか。
• CLAUDE_CODE_SUBAGENT_MODEL_FORCEが有効か。
• 組織のavailableModelsポリシーが許可済みモデルへ置き換えたか。
• クライアントが古い優先順位ルールを使うバージョンか。

3. プロバイダー側のリクエスト記録と照合する

同じ時間帯のリクエストを探し、実際のModel IDを確認します。サードパーティーのゲートウェイでは特に重要です。クライアントに表示されたエイリアスが、ゲートウェイ側でもう一度マッピングされる可能性があるためです。

BetterTokenは、モデル、トークン数、最終請求額、ステータスを1つのリクエスト記録にまとめて表示します。この手順では、検証に使うのはモデルとステータスのフィールドだけです。その記録から根拠のない節約効果を主張しないでください。サブエージェントの実行時間帯とタイムスタンプが一致してから、そのリクエストだと判断します。

次のような小さな受け入れ表を使えます。

確認箇所	期待する証拠	異なる場合
エージェントファイル	正確なModel ID	IDを修正し、必要なら再読み込みまたは再起動
/tasks	対象サブエージェントと実行モデル	呼び出し設定、force変数、組織ポリシーを確認
プロバイダー記録	同じ時間帯の実際のModel IDと成功ステータス	カタログ、エイリアスマッピング、ルーティング、アカウント権限を確認
git status --short	予期しないファイル変更がない	ツールを制限し、変更を戻して再実行

最初の3つの確認箇所でモデルの証拠が一致した場合だけ、「モデル切り替えを検証済み」と記録してください。Haikuと書いたプロンプト、画面上のエージェント名、回答が完了したという事実だけでは証明になりません。

トラブルシューティング

エージェントが呼び出されない

ファイルが.claude/agents/または~/.claude/agents/にあり、frontmatterにnameとdescriptionがあり、YAMLとして解釈できることを確認します。セッション開始後に初めてエージェントディレクトリを作った場合は、Claude Codeを再起動してください。それでも読み込まれなければ、--debugを付けてClaude Codeを起動し、読み込みエラーを確認します。

/agentsに作成ウィザードが出ない

通常は正常です。v2.1.198以降の/agentsは、エージェントファイルを直接編集するための案内を表示します。対話型ウィザードはv2.1.197以前の動作です。古い画面キャプチャではなく、実際に使っているバージョンの文書に従ってください。

model: haikuだけではHaiku 5.5だと証明できない

haikuは固定バージョンではなくエイリアスです。Claude Codeのバージョン、プロバイダー、ゲートウェイのマッピングにより解決先が変わる可能性があります。監査できるルーティングにするには、現在のプロバイダーカタログにある完全なIDを使い、/tasksとプロバイダー記録の両方を確認してください。

ゲートウェイがmodel not found、403を返す、または黙ってフォールバックする

まず、ゲートウェイのライブカタログにそのIDがあり、アカウントに利用権限があるか確認します。カタログにclaude-haiku-5-5がなければ、その文字列を繰り返し試さず、掲載されている適切なモデルを選ぶか、追加されるまで待ちます。組織のallowlistが別モデルへ置き換えたままタスクを継続させることもあるため、実行時の証拠を確認してください。

すべてのサブエージェントが小型モデルになった

CLAUDE_CODE_SUBAGENT_MODEL_FORCEを探して削除します。1つのエージェントだけを固定するには、そのエージェントのfrontmatterに完全なIDを置きます。自動探索だけを変えるなら、代わりにExploreを上書きしてください。

調査エージェントがファイルを変更した

git status --shortで範囲を確認し、意図しない変更を戻します。toolsをRead, Grep, Globに制限し、システムプロンプトにも読み取り専用の境界を繰り返し明記します。書き込み可能なツールを外すほうが、プロンプトに「編集しない」とだけ書くより確実です。

最小構成で導入する

まず次の5段階だけ実施します。

1. Claude Codeを更新し、claude --versionを実行する。
2. プロバイダーのカタログから、現在実際に使える完全なModel IDをコピーする。
3. Read、Grep、Globだけを持つrepo-researcherを1つ作る。
4. 1つのシンボルまたはディレクトリに限定した課題で起動する。
5. /tasks、プロバイダーのリクエスト記録、git status --shortを照合する。

目的は、あらゆる作業を最小モデルへ送ることではありません。目的は監査可能な役割分担です。小型モデルは確認可能な読み取り専用の証拠を集め、SonnetまたはOpusのメインエージェントが重要な判断と変更に責任を持ちます。まず狭い1件を検証し、同じ受け入れ基準が成立する範囲だけへ広げてください。