Claude Codeのultracode設定と/effort ultracodeの使い分け

ultracodeは、Claude Codeが実質的なタスクごとにワークフローを組むかどうかを決める、オンオフの設定です。settings.jsonに"ultracode": trueと書くと毎セッションがオンで始まり、/effort ultracodeは今のセッションだけをオンにします。v2.1.284以降は、どちらもeffortの段(low〜xhigh)を変えません。

入口が複数あるぶん、「どこで設定するか」で挙動が変わります。この記事では設定キーと/effort系の入口を並べ、どの場面でどれを選ぶかを比べます。

ultracodeはeffortの段ではなくオンオフの設定です

model-configの公式ドキュメントは、ultracodeを「モデルのeffortレベルではなくClaude Codeの設定」と位置づけています。オンのとき、Claudeはダイナミックワークフローを実質的なタスクごとに計画します。依頼されるのを待たず、Claude自身が判断します。

動作の軸は2本あります。

• ワークフローを組むか(ultracodeのオンオフ)
• どの深さで推論するか(effortの段)

v2.1.284より前は、この2本が結びついていました。ultracodeをオンにするとxhighに固定され、別の段を選ぶとultracodeが切れ、effortの上限がxhigh未満だとultracodeが使えませんでした。v2.1.284で独立したトグルになり、任意の段のままオンにできます。この変更の背景はv2.1.284のリリースノートにもあります。

ultracodeを有効にする4つの入口

同じultracodeでも、入口によって持続範囲とeffortへの影響が違います。

--effort ultracodeだけは例外です。オンにすると同時に、effortをxhighにします。「オンにしたらxhighのまま」という旧来の挙動が、フラグ経由では残っています。Agent SDKのeffortLevel: "ultracode"も同じ扱いです。

settings.jsonに書く: 毎セッション始めからオンにする

常にワークフロー主体で作業する環境なら、設定キーで固定できます。

{
  "ultracode": true
}

このキーの仕様は次のとおりです。

• 型は真偽値で、未設定ならオフ
• スコープはAny file。ユーザー・プロジェクト・ローカル・管理設定のどれにも書ける
• trueでも、ダイナミックワークフローが自分に有効で、モデルがxhighに対応しているときだけ実際にオンになる
• Claude Codeはこのキーを読むだけで、書き込まない

最後の点は見落としやすいところです。/effort ultracodeをどれだけ実行しても、settings.jsonの中身は変わりません。設定を永続させたいなら、自分でファイルへ書く必要があります。Agent SDKからはapply_flag_settingsの制御リクエストでも渡せます。

--settingsオプションで渡す設定ファイルにも書けます。CIや一時的な検証用に、プロファイルを切り替えたいときに向く形です。

セッション単位で切り替える: /effort ultracodeとTab

一度きりの大きな作業だけワークフローに任せたいなら、/effort系の入口が向いています。

/effort ultracode
/effort ultracode off

1行目は今のセッションだけオンにし、2行目はオフに戻します。スライダーを使うなら、/effortでスライダーを開いてTabを押し、Ultracodeトグルを切り替えてEnterで確定します。このTabキーはeffortSlider:toggleUltracodeというアクションで、割り当てを変えられます。手順はeffortSliderキーバインドの記事にあります。

覚えておきたいのは、スライダーでeffortの段を選んでも、/modelピッカーでモデルを選んでも、ultracodeの状態は変わらないことです。段とオンオフが別々に動くので、「xhighのままultracodeだけ切る」「mediumのままultracodeをオンにする」が成り立ちます。

設定キーがtrueのときにオフにする

settings.jsonで"ultracode": trueにしているとき、今日だけ普通のセッションにしたい場面があります。/effort ultracode offがそのための入口です。公式ドキュメントでは、このキーがtrueのときに1セッションだけオフにする手段として書かれています。ファイルは書き換わらないので、次の起動ではまたオンで始まります。

使い分けの目安

どの入口を選ぶかは、「どれくらいの頻度でワークフローを使うか」で決まります。

4行目のプロンプト中の語は、設定キーとは別の仕組みです。起動語のultracodeを書くと、その依頼だけがワークフローになります。この起動語の停止方法はworkflowKeywordTriggerEnabledの記事で扱っています。設定キーのultracodeとは別物で、片方を止めてももう片方には影響しません。

常時オンにするときのコスト

設定キーで常時オンにすると、公式が挙げるコストの前提が毎セッション効きます。

• 1つの依頼が、理解・変更・検証のように複数のワークフローに分かれることがある
• ワークフローを使わない同じ依頼より、トークンも所要時間も増える
• サブスクリプションでは、その分がセッションや週の使用量上限を早く消費する

オンにしている間は、いくつかの安全確認も働かなくなります。大規模ワークフロー(Large workflow)の警告は出ません。Agentツールで生成するサブエージェントには、同時実行数の上限がかかりません。autoモードでも、最初のワークフロー起動の承認を求められません。公式ドキュメントは、これらを「ultracodeをオンにした時点で大きな実行への同意が済んでいるため」と説明しています。

だからこそ、常時オンは「ワークフローが日常の作業単位」の環境に絞るのが無難です。使い方全体の設計はダイナミックワークフローの解説に譲ります。

effortの上限とultracodeの関係

v2.1.284で変わった点の1つが、effortの上限との関係です。maxEffortLevelのような上限は、セッションが走るeffortの段を下げますが、ultracodeをオフにはしません。

たとえば次のように、上限をmediumにした環境を考えます。

{
  "maxEffortLevel": "medium",
  "ultracode": true
}

この構成では、ultracodeがオンのまま、mediumのeffortで動きます。v2.1.284より前は、上限がxhigh未満だとultracodeが使えませんでした。maxEffortLevelの詳細はv2.1.267のリリースノートにあります。

環境変数のCLAUDE_CODE_EFFORT_LEVELでセッションの段が決まっている場合も同様で、その段のままultracodeがオンになります。

ultracodeが効かなくなる条件

設定キーをtrueにしても、次の条件ではultracodeはオンになりません。

• ワークフローが無効になっている
• モデルがxhigh effortに対応していない

ワークフローの無効化は、/configのDynamic workflowsのオフ、settings.jsonの"disableWorkflows": true、環境変数CLAUDE_CODE_DISABLE_WORKFLOWS=1のいずれかで行います。無効化されると、/effortからUltracodeトグルも消えます。組織全体で止めるには、管理設定に"disableWorkflows": trueを置きます。

逆に、ultracodeだけを禁止する管理設定はありません。ワークフローが有効でモデルが対応していれば、ユーザーは/effort ultracodeでオンにできます。組織でultracodeを避けたい場合、現状の手段はワークフロー全体の無効化です。

--effort ultracodeで起動した場合、条件を満たさなければultracodeはオフのまま始まります。そのときのeffortは、モデルと上限が許す最も高い段(xhighまで)になります。

よくあるつまずき

effortLevelにultracodeと書いても効かない

effortLevelはlow・medium・high・xhighの設定です。永続するeffortLevelにも、CLAUDE_CODE_EFFORT_LEVELにもultracodeは書けません。永続化には専用のultracodeキーを使います。

{
  "effortLevel": "xhigh",
  "ultracode": true
}

この2行は別々の役割です。1行目が推論の深さ、2行目がワークフロー主体の動きを決めます。モデル別にeffortを保存する仕組みはmodelSettingsの記事で扱っています。

古い版でオフにできない、xhighに固定される

/effort ultracode off、スライダーのトグル、xhigh以外の段でのオンは、v2.1.284以降の機能です。それ以前の版では、オンにするとxhighへ切り替わり、別の段を選ぶとオフになります。claude --versionで版を確認してください。

意図せず重い作業になる

ultracodeは全タスクをワークフロー候補にします。簡単な修正にも、大がかりな段取りが組まれることがあります。大きな作業が終わったら/effort ultracode offで戻すのが、いちばん手軽な対処です。effortの段を下げても、ultracodeは残る点に注意が必要です。

手元で確認する手順

設定の効き方は、次の順に確かめられます。

1. claude --versionでv2.1.284以降か確認する
2. settings.jsonに"ultracode": trueを書いて起動する
3. /effortを開き、Ultracodeのトグルがオンで、effortの段が変わっていないことを見る
4. /effort ultracode offを実行し、トグルがオフになることを見る
5. 再起動して、設定キーによってまたオンで始まることを確かめる

トグルが表示されない場合は、ワークフローの無効化かモデルのxhigh非対応が原因です。effortの段そのものの選び方はeffortレベルの解説にまとめています。