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本の関係が変わりました。

この変更の背景はv2.1.284のリリースノートにもあります。

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

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

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

v2.1.289の--helpに載っているeffortの値

フラグの値は、手元のヘルプで確かめられます。v2.1.289でclaude --helpを実行し、--effortの行を抜き出した出力です。

claude --version
claude --help | grep -A1 -e "--effort"

2.1.289 (Claude Code)
  --effort <level>                      Effort level for the current session
                                        (low, medium, high, xhigh, max)

ヘルプの値の一覧にultracodeは出ません。一方でmaxは載っています。--effort ultracodeはv2.1.203以降で受け付けられます。それより前の版ではUnknown --effort value 'ultracode'と表示され、セッションは既定のeffortで始まります。フラグの値を調べるときは、ヘルプの一覧だけで判断せず、model-configのeffortの節と突き合わせる必要があります。

逆にmaxは、セッション中のフラグでは使えても、永続するeffortLevelとmodelSettingsには書けません。保存できるのはlow・medium・high・xhighの4段です。

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

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

{
  "ultracode": true
}

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

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

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

キーは、--settingsオプションで渡す設定ファイルにも書けます。Agent SDKからはapply_flag_settingsの制御リクエストでも渡せます。

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

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

/effort ultracode
/effort ultracode off

1行目は今のセッションだけオンにし、2行目はオフに戻します。更新履歴には/effort ultracode [on|off]の形で載っているので、onを明示して書くこともできます。スライダーを使うなら、/effortでスライダーを開いてTabを押し、Ultracodeトグルを切り替えてEnterで確定します。

このTabキーはeffortSlider:toggleUltracodeというアクションで、割り当てを変えられます。手順はeffortSliderキーバインドの記事にあります。VS Code拡張では、Effortスライダーの下にUltracodeのオンオフスイッチがあります。

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

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

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

使い分けの目安

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

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

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

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

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

オンにしている間は、いくつかの安全確認も働きません。公式ドキュメントは、オンにした時点で大きな実行への同意が済んでいるため、と説明しています。

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

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を置くか、Claude Codeの管理設定ページのトグルを使います。

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は残る点に注意が必要です。

手元で確認する手順

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

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