Claude Codeの/advisorコマンドを使いこなす方法

はじめに

深夜、同じエラーに3回目の指示を出していた。「さっきの方法じゃダメだった、別のやり方で」「今度はこの制約も考慮して」。言い方を変えるたびにClaudeは違うパッチを当ててくるが、根本原因には触れない。1時間後に気づいたのは、直し方を変えても直らない種類の問題を、直し方を変えることで解決しようとしていた、という単純な事実だった。

こういう詰まり方は、実はモデル1つで全部のフェーズを回している構成そのものに起因することが多い。ルーチン作業も、方針転換の判断も、完了の確認も、同じモデルの同じ視点でこなしているから、行き詰まったときに視点を変える手段がない。

Claude Codeの/advisorは、この構造的な問題に対する回答として実装された機能だ。実行中のモデル（executor）が、方針を決める・エラーが繰り返す・完了を宣言するといった意思決定のタイミングで、もう1つの強いモデル（advisor）に一時的に相談できる。

先に前提を明記しておく。/advisorは実験的機能で、Claude Code v2.1.98以降かつAnthropic API利用時のみ動く。Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundry経由では使えない。公式ドキュメントにも「挙動・料金・提供状況は変更される可能性がある」と明記されている。まずは手元の環境が対象かどうかを確認してから読み進めてほしい。

/advisorが生まれた背景——単一モデルのコスト/性能トレードオフ

単一モデル運用には昔からある悩みがある。常に高性能なモデルを使えば精度は上がるがコストが跳ね上がる。常に軽量なモデルを使えばコストは抑えられるが、判断が必要な場面で見落としが増える。この二択のどちらかを毎回選ばされてきた。

Anthropicの公式ブログ「The Advisor Strategy」は、この構図を「executorがタスクを最初から最後まで実行し、判断が難しい局面だけadvisorに相談する」非対称な構成で緩和しようとした取り組みだと説明している。公式ブログが示すベンチマーク数値がこれだ。

• Sonnetをexecutor、Opusをadvisorにした構成: SWE-bench MultilingualでSonnet単体比+2.7ポイント、タスクあたりコストは11.9%削減
• Haikuをexecutor、Opusをadvisorにした構成: BrowseCompのスコアが19.7%から41.2%まで2倍以上に向上しながら、Sonnet単体運用比で85%のコスト削減

つまり「安いモデルを主に使いつつ、要所だけ賢いモデルに聞く」という構成が、コストと精度の両取りにつながることをAnthropic自身が数字で示している形だ。公式ドキュメントも「advisorはルーチン作業が大半を占めるが、計画の質が結果を左右する長いマルチステップタスクに向く」と明記しており、単発の質問応答やユーザー自身がコスト/品質のトレードオフを選びたい場面には向かないとも書かれている。万能の仕組みではない、という前提は覚えておきたい。

3つの設定方法とモデルの組み合わせ

設定方法は3つ用意されている。

1. /advisorコマンド。引数なしで実行すると利用可能なモデル一覧が表示され、/advisor opusのように指定すると即座に反映される。この設定はユーザー設定のadvisorModelに保存され、次回セッション以降も持続する。
2. settings.jsonのadvisorModelフィールド。恒久的なデフォルトとして設定したい場合はこちらを直接編集する。
3. 起動時の--advisorフラグ。そのセッション限定で有効になり、settings.jsonの設定より優先される。

どのモデルをexecutor・advisorにできるかは組み合わせルールが決まっている。公式ドキュメントのモデルペアリング表はこうなっている。

見てわかる通り、基本的には同格以上のモデルしかadvisorになれない。格下のモデルにお伺いを立てても意味がないので、この制約は理にかなっている。なおサブエージェントも設定済みのadvisorを継承するが、そのサブエージェント自身のモデルに対してペアリングの検証が行われる点は覚えておくといい。

呼び出しタイミングはClaudeの自律判断

いつadvisorに相談するかは、ルールベースではなくClaude自身の判断に委ねられている。公式ドキュメントは「方針を決める前」「同じエラーが繰り返し発生しているとき」「タスク完了を宣言する前」に相談する傾向があると説明しているが、これは目安であって強制ではない。呼び出し回数の上限や強制設定は用意されていない。

プロンプトで明示的に依頼することもできる。「consult the advisor before you continue」のように、他のツール利用を依頼するのと同じ感覚で書けばよい。セッション中はAdvisingという行が表示され、Ctrl+Oで展開すると助言の全文が読める。Claudeは基本的に助言に従うが、手元の証拠(実際に試して失敗した手順、助言と矛盾するファイル内容など)と矛盾する場合は無条件には従わず、その食い違いを表面化させる、との記述もある。

実務でどう使うか——リファクタからDB設計まで

公式ドキュメントは、advisorが「向いている」シーンをいくつか明記している。

大規模なリファクタリングでは、変更範囲が広いぶん方針決定のミスが後工程全体に波及する。着手前にadvisorへ相談させておくと、この手戻りのリスクを減らせる。同じエラーが繰り返し発生するデバッグセッションでも同様で、冒頭で書いた深夜の泥沼はまさにこのパターンに当てはまる。もう1つは、タスクの完了を宣言する前に独立したチェックを挟みたい場面だ。

日本語圏の実践例では、start-link.jpがDB設計・セキュリティレビュー・CRM設計という3つの業務シーンでの活用を紹介している。DB設計では正規化やインデックス戦略の妥当性確認、セキュリティ設計では権限昇格パターンへの防御チェック、CRM設計ではHubSpotのカスタムオブジェクトが過剰設計になっていないかの確認、といった具合だ。同記事は/planコマンドと組み合わせる使い方を推奨しており、計画フェーズでadvisorに設計方針を見てもらってから実装に進む流れは試す価値がある。

Sonnetをexecutorに、Opusをadvisorに据えた構成での実例として、azukiazusa.devがSvelteコンポーネントのリファクタリングを紹介している。Sonnetが立てた実装計画に対し、Opusが「モジュールエイリアス解決の不確実性」「グローバルクエリの問題」「DOM要素のクリーンアップ漏れ」という3点のリスクを指摘したという。軽量モデルで日常的な作業をこなしつつ、判断が必要な局面だけ強いモデルに相談する、という設計思想を具体的に示す事例だ。

コストと限界を正しく理解する

コストと無効化、知っておきたい仕組み

advisorを呼ぶたびに、会話全体がadvisorモデルに送られる。つまりメインモデルの利用に加えて、advisorモデルのレートでトークンが消費される。API課金の場合はadvisorモデルの入出力レートで課金され、サブスクリプションプランの場合はプランの利用上限に加算される。/usageコマンドを見ればセッション合計に反映されているのが確認できる。

プロンプトキャッシュについては、地味だが知っておくと得をする豆知識がある。セッション中に/advisorのオン・オフを切り替えても、メインモデル側のプロンプトキャッシュは壊れない。advisorが返した助言はトランスクリプトの一部としてキャッシュされる。ただしadvisor自身が会話を読み込む処理はキャッシュされず、呼び出すたびに全トランスクリプトを新規に処理する。つまりキャッシュはメインモデル側とadvisor側で別々に管理される2層構造になっている、というのが公式ドキュメントの説明だ。もう1つの豆知識として、advisorの推論はストリーミングに対応しておらず、呼び出し中はメインモデルの出力ストリームが一時停止する。

不要になったら止める手段も用意されている。セッション中だけなら/advisor offで、これはadvisorModelの設定もクリアする。環境ごと完全に無効化したい場合はCLAUDE_CODE_DISABLE_ADVISOR_TOOL=1を設定すればよい。これを設定すると/advisorコマンド自体が使えなくなり、--advisorフラグを付けてもエラーにならず単に無視される。

類似機能との使い分け

Claude Codeには強いモデルを差し込む方法が他にもいくつかある。公式ドキュメントが挙げる比較はこうだ。

opusplanは「計画フェーズだけ強いモデル、実行フェーズは軽いモデル」というフェーズ分離型の設計だ。advisorはフェーズを分けず、実行中のどのタイミングでも差し込める点が異なる。サブエージェントは独立したコンテキストウィンドウで動くため、会話の流れに引きずられない新鮮な視点が得られるのが強みで、advisorの「文脈込みの助言」とは補完関係にあると考えるとよい。/modelはセッション全体の切り替えなので、コスト最適化の観点では常時強いモデルを使うより、advisor経由で必要な瞬間だけ相談する方が有利になりやすい。

実践知見が示す限界

過信を避けるために、実践報告にも触れておきたい。readysolutions.aiは17日間で159回のadvisor呼び出しを記録したという運用データを公開している。この報告によると、方針転換につながった判断(HIGHティア)が約16%、計画の改善(MIDティア)が約44%、変化なし(LOWティア)が約35%だったという。同記事は公式が推奨する「作業前」と「完了前」の2回呼び出しに対し、「完了前の呼び出しは費用対効果がほぼゼロだった」として、実質的な作業に着手する前の1回に絞る独自ルールを提案している。あくまで一開発者の実践報告であり、公式ガイダンスと矛盾する部分がある点は留意してほしい。

同記事はadvisorの構造的な弱点も報告している。advisorはファイルシステムにアクセスできずトランスクリプトしか見ていないため、変数名やインポートパスの実値に依存する欠陥は検出できない。呼び出すかどうかはClaudeの裁量なので、必須の検証ステップの代替にはならない。サブエージェントのレビュアーからはadvisorが検証済みの判断が見えず、矛盾した指摘が起こることもあるという。イエスマン的な同調傾向(sycophancy)についても触れられており、「30〜40%のプロンプトで同意バイアスが増加した」という言及があるが、この数値の一次ソースは記事内で示されておらず、あくまで一開発者が挙げた参考値として扱うべきだろう。

まとめ——まず試してほしいこと

/advisorは、単一モデルに全部を背負わせる構成の限界を、コストを抑えたまま緩和するための実験的な仕組みだ。深夜に同じエラーを言い方を変えて直そうとした経験があるなら、次に同じ状況になったときは/advisor opusと打ってみてほしい。セッション終了後は/usageでどれだけコストが増えたかを確認し、大規模リファクタリングや繰り返すデバッグなど、advisorが効きやすい場面から使い所を見極めていくのがいいと思う。ただし完了チェックへの過信は禁物で、必須の検証手順の代わりにはならないことは覚えておいてほしい。

参考リンク

• Claude Code公式ドキュメント: Advisor
• Claude API公式ドキュメント: Advisor tool
• Anthropic公式ブログ: The Advisor Strategy
• readysolutions.ai: Claude Code Advisor — When to Call and Where It's Blind
• azukiazusa.dev: Claude Advisor Tool
• start-link.jp: Claude Code Advisorコマンドの実践