Claude Codeの/advisorコマンドとAdvisor Toolを調べてみた

Claude Code v2.1.98以降で使える /advisor コマンドは、タスク実行中の重要な局面でより高性能な「アドバイザーモデル」に助言を求められる機能です。スラッシュコマンドとしては薄いラッパーですが、裏では Anthropic API の advisor_20260301（ベータ）ツールが動いています。

「実行は軽いモデル、判断は重いモデル」という二段構えは、エージェント的な長期タスクでよく語られるパターンです。Advisor Tool はそれを API レベルで標準化した仕組みと言えます。本記事では、Notion にまとめた調査メモをもとに、使い方からコスト・エラー時の挙動まで整理します。

Claude Code での使い方

コマンド

/advisor [model|off]
指定意味
opusOpus 系のアドバイザーモデルを使用
sonnetSonnet 系のアドバイザーモデルを使用
fableFable 系のアドバイザーモデルを使用（v2.1.170以降）
フルモデル ID例: claude-opus-4-8 のように直接指定
offアドバイザー機能を無効化
引数なしモデル選択のピッカーが開く

前提: Claude Code v2.1.98 以降が必要です。

settings.json での設定

Claude Code の設定ファイルは settings.json です（settings.yml ではありません）。アドバイザー関連で永続設定できるのは、実質的に アドバイザーモデルの指定 だけです。

{
  "advisorModel": "opus"
}
方法例備考
settings"advisorModel": "opus"/advisor 実行時にも自動保存される
コマンド/advisor opusユーザー設定に永続化
CLIclaude --advisor opusそのセッションのみ（settings より優先）
無効化/advisor off保存済みの advisorModel をクリア
完全無効化CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1/advisor 自体が使えなくなる

配置場所の例:

  • ユーザー全体: ~/.claude/settings.json
  • プロジェクト共有: .claude/settings.json
  • 個人ローカル: .claude/settings.local.json

公式ドキュメントでは、呼び出し回数の上限や強制呼び出しを settings で制御する項目はないと明記されています。頻度を変えたい場合は、プロンプトで指示する想定です。

Advisor Tool（API）の仕組み

Advisor Tool の基本設計は次のとおりです。

  • 実行モデル（executor）: より高速・低コストなモデルがメインの作業を担当
  • アドバイザーモデル（advisor）: 実行モデルが生成の途中で助言を求める、より高性能なモデル

向いているケース

長期にわたるエージェント的作業で効果を発揮します。具体例は以下のようなものです。

  • コーディングエージェント
  • コンピュータ操作
  • 複数ステップの調査パイプライン

大半のターンは機械的な処理ですが、「次に何をすべきか」の計画が重要になる場面でアドバイザーの価値が出ます。

モデル組み合わせの制約

アドバイザーには Claude Sonnet 4.6 以上 かつ 実行モデル以上の能力 が必要です。

例として、実行モデルが Sonnet 5 の場合、アドバイザーには Fable 5・Mythos 5・Opus 4.8・Opus 4.7 などが使用可能です。

呼び出しフロー

sequenceDiagram
    participant Executor as 実行モデル
    participant API as Anthropic API
    participant Advisor as アドバイザーモデル

    Executor->>API: server_tool_use（空の input）
    API->>Advisor: 全トランスクリプトを引用コンテキストとして渡す
    Advisor->>API: 推論（独自のシステムプロンプト下）
    API->>Executor: advisor_tool_result（助言テキスト）
    Executor->>Executor: 助言を踏まえて生成を継続

処理の流れをステップで書くと次のとおりです。

  1. 実行モデルが空の input を持つ server_tool_use ブロックを発行する（呼ぶタイミングは実行モデルが判断）
  2. Anthropic がサーバー側で、実行モデルの全トランスクリプトを引用コンテキストとしてアドバイザーモデルに渡し、別の推論パスを実行する
  3. アドバイスが advisor_tool_result として返る
  4. 実行モデルがその助言を踏まえて生成を継続する

補足:

  • アドバイザー自体はツールを持たず、コンテキスト管理もない
  • 思考ブロックは結果が返る前に破棄され、助言テキストのみ が実行モデルに渡される

呼び出しタイミングのルール

Advisor Tool の効果は「いつ呼ぶか」に大きく依存します。公式ドキュメントが示すルールを整理すると次のとおりです。

作業前に呼ぶのが基本

実質的な作業（コード記述・編集・答えの確定）の前に呼ぶのが基本です。

探索フェーズは対象外

ファイル探索・調査などの「オリエンテーション」段階では呼ばない。探索が終わってから advisor を呼びます。

タスク完了時にも呼ぶ

タスク完了と判断した時にも呼びます。ただしその前に成果物を保存し、セッションが途中で終わっても結果が残る状態にしておくことが推奨されます。

アドバイスと証拠が食い違ったとき

  • アドバイスに従って失敗した場合や、手元の一次情報の証拠と矛盾する場合は対応を調整する
  • 「テストが通った」こと自体は、アドバイスが誤りだった証拠にはならない（テストがアドバイスの検証点をチェックしていないだけの可能性がある）
  • 証拠とアドバイスが食い違う場合は、その場でアドバイザーに矛盾点を提示して再度判断を仰ぐのが安上がり

ベストプラクティス（コーディング / エージェントタスク向け）

複雑なタスクでは、2回の呼び出しが改善効果を牽引するとされています。

タイミング目的
早い段階（数回の探索的な読み込みの後）全体方針・アプローチの確認
最終段階（ファイル書き込み・テスト結果が出た後）成果物の妥当性チェック

「最初に方針を確認し、最後に仕上げを確認する」という二段構えは、人間のコードレビューにも通じるパターンです。

コスト面のポイント

アドバイザー呼び出しは別のサブ推論として実行され、アドバイザーモデルのレート料金が適用されます。

項目目安
アドバイザーの出力（テキストのみ）400〜700 トークン
思考込み1,400〜1,800 トークン程度

注意: max_tokens / caching / max_uses は API 側の話

記事や Platform Docs で出てくる次のパラメータは、Messages API で自分で advisor ツールを定義するときの話です。Claude Code の settings.json には書けません。

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-8",
        "max_tokens": 2048,  # 推奨の出発点（最小 1024）
        "max_uses": 5,       # 1リクエスト内の呼び出し上限
        "caching": {"type": "ephemeral", "ttl": "5m"},  # 3回以上呼ぶとき
    }
]
パラメータ意味Claude Code settings
max_tokensアドバイザー出力（thinking + text）の上限不可
max_uses1リクエスト内の呼び出し上限不可
cachingアドバイザー側プロンプトキャッシュ不可

補足:

  • トップレベルの max_tokens や環境変数 CLAUDE_CODE_MAX_OUTPUT_TOKENS は 実行モデル側 の上限で、アドバイザー出力は縛らない
  • Claude Code 公式ドキュメントでは、アドバイザー側の読み取りは呼び出しごとに全文再処理され、advisor-side cache は使われないと説明されている
  • API で自前実装する場合、max_tokens: 2048 が推奨の出発点。Anthropic の社内テストでは上限なしと比べ平均出力が約 1/7 に減り、切り詰めもほぼ 0% だった

Claude Code だけで使う場合は、コスト最適化のレバーは主に アドバイザーモデルの選択（advisorModel）と、プロンプトでの呼び出し頻度の指示になります。

エラー時の挙動

Advisor Tool はフェイルセーフに設計されています。

  • アドバイザー呼び出しが失敗しても、リクエスト自体は失敗しない
  • 実行モデルは advisor_tool_result_error（例: overloaded）を受け取り、追加のアドバイスなしで処理を継続する
  • レート制限は、そのモデルへの直接呼び出しと同じバケットを共有する

つまり、アドバイザーが一時的に使えなくてもタスク全体は止まりません。助言が取れないだけで、実行モデル単体で続行します。

エージェント構成への応用アイデア

maker / checker / orchestrator / optimizer のような多層構成を検討している場合、Sonnet 実行 × Opus 助言の /advisor を checker レイヤーの代替・補完として組み込む余地があります。

.worktreeinclude や pre-commit フック、カスタムガードスクリプトのような機構と組み合わせれば、「軽いモデルで実装し、重いモデルでレビューする」フローを Claude Code ネイティブに近い形で実現できるかもしれません。実際のコーディングタスクで検証する価値がありそうです。

参考リンク

まとめ

Claude Code の /advisor は、実行モデルとアドバイザーモデルを組み合わせる「二段構えエージェント」を手軽に使える機能です。

  1. 使い方: /advisor [model|off] でモデルを指定（v2.1.98 以降）。永続設定は settings.json の advisorModel
  2. 仕組み: 実行モデルが server_tool_use を発行 → アドバイザーが助言 → 実行モデルが継続
  3. タイミング: 探索後の早い段階と、書き込み・テスト後の最終段階の2回が効果的
  4. コスト: アドバイザーモデルの料金が別途発生。max_tokens / caching / max_uses は API ツール定義側の話で、Claude Code の settings では制御できない
  5. エラー時: 失敗してもタスクは継続。フェイルセーフ設計

長期タスクで「計画の質」がボトルネックになりがちな場面では、試す価値がある機能だと思います。