Effort Level Policy
概要
CC frontmatter の effort フィールドと Anthropic API の effort パラメータの対応関係、および Harness における採用方針を定義する。
Opus 5 移行ノート（2026-07-26 実測）
Opus 4.8 は 2026-07-25 の operator 裁定（feat(routing,breezing): retire Opus 4.8 commit d5d1b28d）で harness routing catalog から退役した。brain tier は claude-opus-5 へ全面移行済み。本ドキュメント内の Opus 4.8 固有の記述（thinking 既定 off、xhigh フォールバック挙動など）は、退役前に確立された観測として歴史的に残す。
Opus 5 (claude-opus-5) での effort 挙動を claude CLI v2.1.220 で実測した（各コマンド 1 回のみ実行、timeout 想定 120s）:
| コマンド | 実測結果 |
|---|---|
claude --model claude-opus-5 -p "reply exactly: OK" | 完了まで約 3-4 分（exit 0）。標準出力は空行のみで、指示した OK という文字列は返らなかった |
claude --model claude-opus-5 --effort xhigh -p "reply exactly: OK" | 完了まで約 10 分（exit 0）。標準出力は OK ではなく、リポジトリの状態（skill mirror drift、claude-opus-5 追加タスク、bin/harness shim 注意点）に言及する文脈依存の応答だった |
両方とも指示した「OK とだけ返す」を守らなかった。ネストした claude CLI 呼び出しがユーザーレベルの memory / プロジェクト文脈を引き継いだ可能性があるが、原因は本実測だけでは特定できない。xhigh 指定時に応答時間が約 3 倍（3-4 分 → 約 10 分）に伸びたことは観測事実として記録するが、これが effort tier 自体の効果か、文脈量の違いによるものかは未実測 (unknown)。ダウングレードの有無など、より深い内部挙動は本実測の範囲では判定できない。
CC Frontmatter と API Effort の対応マトリクス
CC v2.1.72 で max が廃止され、v2.1.111 で xhigh が追加された。
CC frontmatter effort 値 | API effort 実効値 | Opus 4.8 での動作 | 非 Opus 4.8 での動作 |
|---|---|---|---|
low | low | low（スコープ厳守、深掘りしない） | low |
medium | medium | medium | medium |
high | high | high | high |
xhigh | xhigh | xhigh（最高 effort tier） | high にフォールバック（changelog 明記） |
注記:
xhighは CC v2.1.111 で frontmatter に追加された（CLAUDE-feature-table.md参照）maxは CC v2.1.72 で廃止済み。frontmatter に書いても無効xhighを Opus 4.8 以外のモデル（Sonnet 系など）で指定した場合、CC がhighに自動ダウングレードする
Opus 4.8 の thinking モデル（重要）
Opus 4.8 では thinking は既定 off。thinking: \{type: "adaptive"\} を明示した時だけ adaptive thinking が働き、 effort と query 複雑度から思考量を自動調整する。budget_tokens 方式の extended thinking は deprecated。 CC frontmatter の effort は引き続き有効で、Opus 4.8 では推論深度の 主レバーになる（過去のどの Opus より effort の影響が大きい）。
そのため Harness は「深く考えさせたい」場面で free-text marker（旧 ultrathink）を使わず、effort tier で制御する （harness-work の effort スコアリングも tier 選択方式に統一済み）。
xhigh が CC 経由で API に渡せるかの判定
判定: 採用（xhigh を frontmatter で受け付ける証拠あり）
根拠:
docs/CLAUDE-feature-table.mdの v2.1.111 セクションにxhigh effortがA: 明示追従対象として記録されている- 同ファイルの Opus 4.7 セクションにも
xhigh effortがA: 明示追従対象として記録されている docs/cc-2.1.99-2.1.111-impact.mdに v2.1.111 でのxhigh追加が文書化されている- Harness の
claude-5-prompt-standard.mdにて「xhigh: 呼び出し側が選ぶ推論強度」と定義されている
xhigh を frontmatter に書いた場合、CC は Opus 4.8 に最高 effort tier のリクエストを送る。非 Opus 4.8 モデル（Sonnet 系など）ではサイレントに high 相当へダウングレードされる。reject や error にはならない。
Harness の採用方針
| フロー | 採用 effort | 理由 |
|---|---|---|
| Plan | high | 速さと整理力のバランスが良い |
| Work (Worker agent) | high | 実装は長考より反復確認が重要 |
| Review (Reviewer agent, harness-review) | xhigh | 比較・反証・抜け漏れ検知に thinking 増分の効果が出る |
| Advisor | xhigh | PLAN / CORRECTION / STOP の判断精度を優先 |
| Release / Setup | high | 手順遵守が中心で、常時 xhigh は過剰 |
frontmatter 更新対象
| ファイル | 変更前 | 変更後 | 理由 |
|---|---|---|---|
agents/reviewer.md | effort: medium | effort: xhigh | Review に xhigh を採用 |
agents/advisor.md | effort: high | effort: xhigh | Advisor に xhigh を採用 |
skills/harness-review/SKILL.md | effort: high | 変更なし | スキルの effort は呼び出し側が上書きするため high を維持 |
運用ルール
review と advisory を優先して
xhighの対象にする 理由: バグ検知や反証は、実装そのものより thinking 増分の効果が出やすい。work は既定
highを維持する 理由: 実装はトークン消費より、短いサイクルでの検証の方が効くことが多い。docs では「Opus 4.8 以外は
highへフォールバック」を明記する 理由: 利用者が「xhighと書いたのに効いていない」と誤解しやすい。全 skill / 全 agent を一律
xhighにしない 理由: コストとレイテンシが無駄に増加する。役割差で使い分けること。${CLAUDE_EFFORT}は参照専用にする 理由: Claude Code 2.1.120 以降、skill 本文から現在の effort level を参照できる。 ただし、これは呼び出し側が選んだ effort を読むための情報であり、skill 側が勝手に effort を上書きするための仕組みではない。
${CLAUDE_EFFORT\} guidance
CLAUDE_EFFORT は、現在の session / invocation で有効な effort level を skill 本文から参照するための変数。
使ってよい例:
Current effort: `${CLAUDE_EFFORT}`.
If effort is low, report only confirmed blockers.
If effort is xhigh, include adversarial checks and edge cases.避ける例:
- skill 本文で「必ず xhigh に変更する」と要求する
CLAUDE_EFFORTが空の環境を失敗扱いにする- user / parent workflow の effort 指定を無視する
Harness の方針:
- effort の選択権は呼び出し側に残す。
- skill は
CLAUDE_EFFORTを説明、分岐、出力粒度調整にだけ使う。 - media / announcement 系のような内部起動 skill では、effort より起動契約（
user-invocable/disable-model-invocation）を優先して明確化する。
見送り rationale（採用しないもの）
以下は採用しない。見送り理由を明記する。
| 項目 | 見送り理由 |
|---|---|
Worker agent を xhigh にすること | 実装ループは長考より速い反復が重要。xhigh のコスト増分に見合う品質向上が得られない |
Setup / Release スキルを xhigh にすること | 手順遵守が中心で、judgment より recall が重要な場面が多い |
max の復活 | CC v2.1.72 で廃止済み。xhigh がその後継 |
注意点
xhighは「賢くなる魔法」ではなく、より深く考えるための余白- 曖昧な指示のままだと、深く考えてもズレた方向に精密化される
- Opus 4.8 以外のモデルでは
xhighを指定してもhigh相当にフォールバックするため、期待した効果が出ない場合がある claude-5-prompt-standard.md「維持する規律 5」:xhighは「呼び出し側が選ぶ推論強度」であり、agent prompt が free-text marker から推測するものではない
関連ファイル
docs/CLAUDE-feature-table.md— v2.1.111 / Opus 4.7 の機能一覧docs/cc-2.1.99-2.1.111-impact.md— xhigh 追加の詳細docs/claude-code-setup-mcp-telemetry-provider.md—$\{CLAUDE_EFFORT\}と setup guidance.claude/rules/claude-5-prompt-standard.md— xhigh の運用ノブ定義agents/reviewer.md— Reviewer effort 設定agents/advisor.md— Advisor effort 設定