メインコンテンツへスキップ
Dev Tools 16分で読める

Claude Codeのコスト爆発を防ぐ新環境変数|v2.1.316のサブエージェント制御とultrathink停止ガイド

「サブエージェントが請求全体の48%を占めていたが、その実際の出力は全体のわずか0.9%だった」。DEV Communityのji_aiはそう書いた(出典)。別のエンジニアは自動化スクリプトを一晩走らせ、翌朝に6,000ドルの請求を受けた(出典)。

問題の根は同じだ。Claude Codeのサブエージェントは、v2.1.316以前、親セッションのeffortレベルをそのまま無条件に継承していた。セッションをmax effortで動かしているチームでは、子サブエージェントも全員maxで動く。思考トークンは出力トークンと同率で課金されるため、並列サブエージェントが多いほどコストは指数的に膨らんだ。

2026年10月31日リリースのv2.1.316はこの問題に正面から応えた。

この記事はこんな人におすすめ
  • Claude Codeのサブエージェントや並列実行でコストが予想外に膨らんだ経験がある開発者
  • チームでClaude Codeを使っており、ultrathinkの誤用やコスト超過を防ぎたいエンジニアリングマネージャー
  • Uber型のAI予算崩壊を事前に防ぎたい、企業のAI担当・情シス担当者

v2.1.316で何が変わったのか

v2.1.316(2026年10月31日)では、コスト制御に関する2つの環境変数が同時に追加された。

変数名効果デフォルト
CLAUDE_CODE_SUBAGENT_EFFORTサブエージェントのeffort下限を設定未設定(親セッション継承)
CLAUDE_CODE_DISABLE_ULTRATHINKultrathinkキーワードのxhigh強制実行を無効化未設定(ultrathink有効)

これに先立つv2.1.311(2026年10月26日)では、「ultrathink」という文字列をチャットに入力すると、そのターンが強制的にxhigh effortで実行されるという変更が加わっていた。それ以前はultrathinkは単なるヒントにすぎなかったが、v2.1.311以降は「魔法の呪文」として機能する。v2.1.316はその制御弁としてDISABLE変数を追加した形だ。

なぜサブエージェントがコストを爆発させるのか

固定overheadという見えない支出

Claude Codeのサブエージェントには、タスク内容とは無関係に発生する固定起動コストが存在する。DEV CommunityのrulestackがCode Explorerエージェントで計測したところ、何も処理しない「空のサブエージェント」でも約54,000トークンのキャッシュ作成が発生し、セッション全体で436,000トークン超の固定overheadが確認された(出典)。

「コストのレバーはペイロードのサイズではなく、エージェントの数だ」というrulestackの結論は多くの開発者に衝撃を与えた。

effort継承という静かな罠

v2.1.316以前の動作はシンプルかつ危険だった。セッションをmax effortで開始すると、そのセッション内から生成されるすべてのサブエージェントも自動的にmax effortで動作した。ドキュメントに明示されていなかったため、多くの開発者が気づかないまま高コストの並列処理を走らせていた。

Gabriel Anhaiaがv2.1.316のリリース直後にDEV Communityで報告した内容が端的に問題を示している(出典)。彼が計測した例では、ultrathink(xhigh effort)で同じ5行の説明タスクを処理した場合は10,921トークン、low effortでは586トークンと約18.6倍の差があった(wmedia.es)。

新環境変数の使い方

CLAUDE_CODE_SUBAGENT_EFFORT

サブエージェントのeffortデフォルト値を設定する変数だ。親セッションのeffortに依存せず、サブエージェント固有のベースラインを持たせられるのが最大の特徴。

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_SUBAGENT_EFFORT": "medium"
  }
}

または環境変数として直接設定:

export CLAUDE_CODE_SUBAGENT_EFFORT=medium

有効な値はlow / medium / high / xhigh / max。設定しない場合は従来通り親セッション継承となる。

優先順位: エージェントのfrontmatterにeffort: highのように明示指定されている場合は、そちらが優先される。この変数はあくまで「指定なし時のデフォルト」として機能する点に注意。

CLAUDE_CODE_DISABLE_ULTRATHINK

v2.1.311以降、「ultrathink」と入力するとそのターンが強制xhigh effortで実行される。チームの誰かが無意識に(あるいは習慣で)ultrathinkと打つだけで、高額な推論が走る可能性がある。これを止めるのがこの変数だ。

// .claude/settings.json(プロジェクト全体に適用)
{
  "env": {
    "CLAUDE_CODE_DISABLE_ULTRATHINK": "1"
  }
}

値1でultrathinkを無効化。unset(未設定)でデフォルト動作(ultrathink有効)。

意図的に深い推論が必要な場面では、代わりに--effort xhighフラグを明示するか、/effort xhighコマンドを使う。こちらはチームメンバーが意図的に操作している証跡が残る。

CLAUDE_CODE_SUBAGENT_MODEL

v2.1.316と同時期に追加されたもう一つの変数。サブエージェントが使うモデルをセッション本体と切り分けられる。

// 本体はFable 5.2を使いつつ、サブエージェントにはHaiku 5.5を使う例
{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-5-5"
  }
}

effortとモデルの両方を落とすと、コストに対してより大きなインパクトを与えられる。

光と影 — 新変数で何が変わり、何が変わらないのか

変わること

サブエージェント起動コストの予測可能性が上がる。 v2.1.316以前は「並列でいくつエージェントを走らせるとコストがいくらになるか」の見通しが立てにくかった。effortを固定できるようになったことで、コスト試算がしやすくなった。

チームでのultrathink事故が防げる。 開発者が「本気で考えてほしい」という意図でultrathinkと入力するのは理解できる。しかしCI環境やペアプロ中に誰かがultrathinkと打つたびに高コスト推論が走るのはリスクだ。DISABLE変数で制御層を設けられる。

変わらないこと

サブエージェントの固定overheadは解消されない。 CLAUDE_CODE_SUBAGENT_EFFORTはeffortを下げるだけで、起動時の436,000トークン固定overheadは残る。サブエージェント数の削減が根本的なコスト対策になる点は変わらない。

深い推論が必要なタスクでは効果が反転する可能性がある。 サブエージェントをlow effortに落とした結果、答えの品質が下がり、やり直しが発生するケースもある。タスクの複雑度に応じた設定が重要だ。

Uber型コスト崩壊を防ぐ3段階設定

5,000人のエンジニアを擁するUberでは、2026年2月にClaude Codeを導入直後から採用率が急上昇した。2月の32%が3月には84%になり、4月には年間AI予算を使い切った。CTO Praveen Neppalli Nagaは「予算の前提をゼロから見直さなければならない」と語っている(詳細記事)。

Uberが後付けで導入した$1,500/ツール/月の支出上限を、事前に仕込む設定を紹介する。

Level 1: 個人開発者

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_SUBAGENT_EFFORT": "medium",
    "CLAUDE_CODE_MAX_TURNS": "25"
  }
}

サブエージェントをmediumに落とし、ループ暴走をMAX_TURNSで食い止める。ultrathinkは個人判断で使えるよう有効のままにしておく。

Level 2: チーム(プロジェクト共通設定)

// .claude/settings.json(リポジトリに含める)
{
  "env": {
    "CLAUDE_CODE_SUBAGENT_EFFORT": "low",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-5-5",
    "CLAUDE_CODE_DISABLE_ULTRATHINK": "1",
    "CLAUDE_CODE_MAX_TURNS": "20"
  }
}

サブエージェントをlow + Haikuに落とし、ultrathinkを禁止。高負荷タスクは個別に--effort highで明示指定する運用にする。

Level 3: エンタープライズ(admin設定 + pooled budget)

v2.1.316から正式にサポートされたpooled group budgetを管理コンソールから設定する。チーム全体のトークンプールを設け、個人が使い切ってもチーム上限でセーフガードが入る。さらにLayered policyにより、org層で設定した上限を個人・プロジェクト層が超えることはできない。

⚠️ 緊急: Opus 4.8 fast modeが2026年11月30日に廃止

Opus 4.8のfast modeは2026年11月30日に完全廃止される。廃止後はfast modeのリクエストがエラーを返す(サイレントフォールバックなし)。現在Opus 4.8 fast modeを使っているワークフローがあれば、今すぐOpus 5.5への移行計画を立てること。移行先のモデルや料金についてはOpus 4.8完全ガイドを参照。

Claude Codeの実践的な使い方をもっと知りたい方は、Claude Code v2.1.292 effortガイドも参考にどうぞ。サブエージェントへのeffort引数の渡し方と、プラグイン導入の最新手順を解説しています。

詳しく見る

関連記事


本記事の情報は2026年11月15日時点のものです。Claude Codeの仕様・価格・変数の動作はAnthropicの公式ドキュメントで常に最新情報を確認してください。コスト削減効果は環境・タスク・モデルによって異なります。

Share