Claude Code を Opus 4.7 → 4.8 に移行する：ハーネスの差し替えポイント

📖 背景

モデル側の仕様変更（Opus 4.8 以降）が来た場合も、該当する層のみを差し替えれば追随できる。

その Opus 4.8 が来た。本記事は、SaaS 規模の EC 開発プロジェクトで実際に Opus 4.7 → 4.8 へハーネスを移行した差分 の実践録である。「モデルを上げたら設定はそのままで動く」では済まない落とし穴がいくつかあり、特に effort の既定値が変わった点は、知らずに使うと品質が静かに下がる。

裏取りは Anthropic 公式 docs（whats-new (Claude 4.8)・effort・migration guide・Claude Code model config）を 2026-05-29 時点で確認している。

🗺️ 差し替えマップ — どの層に何を入れたか

7層のうち、今回手を入れたのは 第1層 CLAUDE.md・第2層 Skills・第3層 Agents の 3 層。Hooks / Settings / Memory / Steering はモデル非依存なので無変更で追随できた。これが責務分離の効きどころである。

変更点	4.7	4.8	差し替えた層
effort 既定	`xhigh`（モデル既定）	`high`（モデル既定）	第1層 CLAUDE.md
サブエージェント model ID	`claude-opus-4-7`	`claude-opus-4-8`	第3層 Agents
最小キャッシュサイズ	4,096 tokens	1,024 tokens	第2層 prompt-cache Skill
fast mode	（4.6〜）言及なし	運用方針を新設	第1層 CLAUDE.md
mid-conversation system message	—	新機能を Skill 化	第2層 prompt-cache Skill
dynamic workflow / ultracode	—	活用シナリオを追記	第2層 parallel-execution Skill
1M context / Adaptive Thinking	あり	継続（対応モデルに 4.8 追加）	第2層 Skills
Claude Code 必須バージョン	—	v2.1.154+ が必要	第1層 CLAUDE.md

以下、運用インパクトの大きい順に解説する。

⚠️ 最大の落とし穴 — effort 既定が `xhigh` → `high` に下がった

これが今回の移行で一番効いた変更。Opus 4.7 のモデル既定 effort は xhigh だったが、Opus 4.8 はすべてのサーフェス（Claude API も Claude Code も）で既定が high に変わった（公式 effort docs）。

つまり 4.8 に切り替えた直後、何もしなければ effort は high で動く。コーディングや agentic workflow では Anthropic 自身が xhigh 開始を推奨しているため、既定のまま使うと「同じプロジェクト・同じ指示なのに、なぜか実装の詰めが甘い」という静かな品質低下が起きる。

Anthropic 公式 effort docs: “Start with xhigh for coding and agentic use cases, use high for most other intelligence-sensitive workloads.”

さらに厄介なのは、Claude Code はモデル切替時に前モデルの effort を引き継がず、新モデルの既定を適用する点（公式 model-config docs）。4.7 で xhigh に固定していても、4.8 に切り替えた瞬間 high にリセットされる。

運用ルール（CLAUDE.md に明記）

既定:        xhigh   ← コーディング・エージェント作業の既定（明示設定が必要）
正確追求時:  max     ← 公式仕様の裏取り・複雑な設計判断・難解バグ調査・レビュー

Effort	用途	留意点
max	仕様の正確な裏取り、ADR レビュー、複雑な SAGA 設計、難解バグ調査	公式が “prone to overthinking” / “diminishing returns” と注意。コーディングでは xhigh で十分。session-only
xhigh（コーディング既定）	通常の実装、テスト追加、リファクタ、サブエージェント orchestration、反復的ツール呼び出し	公式「coding/agentic は xhigh から開始」。high より明確にトークン消費増
high（4.8 システム既定）	コーディング以外の intelligence-sensitive 作業（設計判断・調査・レビュー応答）	多くの知的作業の balance point
low / medium	使わない（短い定型・低レイテンシ用途を除く）	複雑タスクで品質低下

運用フローはシンプルに 1 行で覚える — 「4.8 を起動したら、コーディング前に /effort xhigh を打つ」。max は session-only なので、裏取りが終わったら xhigh に戻す。

永続性の違い: low / medium / high / xhigh は次セッションへ持ち越すが、max と ultracode は session-only。

🚀 fast mode — 速度を「買う」モード

Opus 4.8 / 4.7 / 4.6 では /fast でトグルできる fast mode が使える。誤解しやすいが、fast mode は小型モデルに下げない。同一の Opus モデルを最大 2.5x 高速に出力する research preview で、知能は標準と同一、トレードオフは速度 ⇔ コスト（premium pricing）のみ。

プロジェクトでの方針は「既定では使わない」。

使う: 壁打ち応答・ドキュメント編集・軽量な調査など、レイテンシが体感に効く場面
使わない: TDD 実装・レビューなどコーディング本番（標準速度でコストを優先）

重要なのは、fast mode でも厳格ゲート（pre-push hook / TDD 必須 / evidence-gate / 証跡記録）は一切緩まないこと。第4層 Settings・第5層 Hooks はモデル速度と独立しているため、fast mode 下でも main 直接 Push 禁止などの保護はそのまま効く。これも責務分離の恩恵である。

💰 最小キャッシュサイズが 4,096 → 1,024 に低下

Prompt Caching のコスト構造は前記事で詳述したが、4.8 で一点だけ嬉しい変更があった。最小キャッシュサイズが Opus 4.7 の 4,096 tokens から 1,024 tokens に下がった（公式 whats-new）。

モデル	最小キャッシュサイズ
Opus 4.8	1,024 tokens
Opus 4.7 / 4.6 / Haiku 4.5	4,096 tokens
Sonnet 4.6	2,048 tokens
Sonnet 4.5 / 4	1,024 tokens

これまで「短すぎて cache 対象外」だったプレフィックスも、コード変更なしで cache entry を作れるようになった。短い system 指示や小さめのツール定義しか持たない構成でも cache hit を取りやすくなる。プロジェクトでは ENABLE_PROMPT_CACHING_1H=1 で 1 時間 TTL を既定にしているため、この変更と組み合わせて「短い・頻繁・長め TTL」のプロンプトが一段とコスト効率よく回る。

🆕 mid-conversation system messages — cache を壊さず指示を足す

Opus 4.8 の新機能。role: "system" メッセージをユーザー turn の直後に挿入できるようになった（配置ルールあり、beta header 不要で GA）。

何が嬉しいか。従来は system プロンプトを変更すると prefix cache が全無効化されていた（キャッシュ階層 tools → system → messages で上位の変更が下位を巻き込む）。mid-conversation system message は末尾追記なので、既存 turn の cache hit を保持したまま指示だけ後から足せる。

観点	内容
cache への効果	先頭が変わらないため prefix cache が生存。指示更新と cache 温存を両立
使いどころ	長い実装セッション中に「以降はこの規約で」と方針追加、サブエージェント orchestration 中の動的指示
前提	Claude Code CLI 利用時は内部で適用される想定。自前 API（hooks / MCP / 独自 agent）で agentic loop を組む際に、cache を壊さず指示を差し込む手段として活用

自分で Anthropic SDK を叩いて長時間ループを書く場面で、これは効く。

🧩 dynamic workflow / ultracode — 大規模 fan-out 専用

Opus 4.8 + Claude Code v2.1.154+ では、サブエージェントを決定論的に編成する Workflow ツールと、それを自動起動する ultracode モードが使える。手動の並列 Agent 起動（前記事の責務マトリクス）より構造化された fan-out が必要な場面向けだ。

	Workflow ツール	ultracode モード
実体	スクリプトで `agent()` / `parallel()` / `pipeline()` を記述	`/effort ultracode`（API の effort level ではなく Claude Code 設定）
中身	多数のサブエージェントを決定論的に orchestrate	`xhigh` + dynamic workflow の自動編成
規模	同時 min(16, cores-2)、総数最大 1,000 subagents	同上
永続性	—	session-only

使い分けの原則:

観点が独立した 2〜5 Agent の単発並列は、従来どおり手動 Agent 起動で十分
数十〜数百のサブタスクを段階的に流す（大規模移行 / 広域監査 / dimension ごとに find→敵対的 verify する多観点 review）場合のみ Workflow / ultracode を検討

プロジェクトでは「既定では使わない」方針。コストが大きく、明示承認・厳格ゲート運用を崩さない範囲に限定し、ユーザーが明示的に要求した場合のみ起動する。

🔁 据え置きで追随できたもの

差し替え不要だった部分も記録しておく。「変えなくていい」と確認できることも移行作業の成果である。

機能	状態
1M context	継続。対応モデルに 4.8 を追加（Opus 4.8 / 4.7 / 4.6・Sonnet 4.6）。`claude-opus-4-8` 指定で既定 1M、`claude-opus-4-8[1m]` で明示指定も可。compact 閾値 500K は据え置き
Adaptive Thinking	継続。Manual `thinking: {budget_tokens: N}` は 4.8 でも 400 エラー。`display` 既定は `omitted` のまま。effort 粒度に `xhigh` も継続
Server-side Compaction（beta）	対応モデルに 4.8 追加。運用ポリシーは不変
Context Rot 対策	兆候ベース検知は不変。4.8 は公式 whats-new で “better long-context handling / fewer compactions” を謳うが、attention budget が有限である原則は変わらない（上限まで使い切らない運用を維持）
第4〜7層（Settings / Hooks / Memory / Steering）	モデル非依存。無変更で追随

4.8 の adaptive thinking は per-turn 判断が精緻化し、同 effort でも wasted thinking tokens が減る（bimodal workload で顕著）という改善はあるが、運用ルール自体を変える必要はなかった。

🚨 移行時のチェックリスト

実際に踏んだ手順を、そのまま再利用できる形でまとめる。

Claude Code を v2.1.154+ に上げる（Opus 4.8 利用の必須要件）
サブエージェント frontmatter の model: を claude-opus-4-8 に更新（date 付きが必要な Haiku は据え置き）
起動直後に /effort xhigh（4.8 既定は high。切替時にリセットされる）
prompt-cache 系ドキュメントの最小キャッシュサイズを 1,024 に訂正
1M / Adaptive Thinking / Server-side Compaction の「対応モデル」表に 4.8 を追記
fast mode・mid-conversation system message・dynamic workflow の運用方針を必要に応じて追記
Hooks / Settings は無変更で良いことを確認（モデル非依存）

✅ まとめ

Opus 4.7 → 4.8 で手を入れたのは 第1〜3層のみ。Hooks / Settings / Memory / Steering は無変更で追随でき、責務分離の投資が回収された
最大の落とし穴は effort 既定が xhigh → high に低下したこと。切替直後にリセットされるため、コーディング前に /effort xhigh を明示するのを運用ルール化する
fast mode は小型モデルに下げず同一 Opus を 2.5x 高速化する「速度を買う」機能。厳格ゲートは一切緩まない
最小キャッシュ 1,024（4.7 比で低下）で短いプロンプトも cache 対象に。1h TTL 既定と相性が良い
mid-conversation system message は cache を壊さず指示を後追いできる新機能。自前 agentic loop で効く
dynamic workflow / ultracode は数十〜数百サブタスクの大規模 fan-out 専用。2〜5 Agent の単発並列には従来手法で十分

モデル世代交代を「設定を全部書き直す大工事」にしないために、ハーネスを層で分け、モデル依存の記述を特定の層に閉じ込めておく。これが Opus 4.8 移行で改めて確認できた、コンテキストエンジニアリングの実利である。

🔗 参考資料

What’s new in Claude 4.8 — 最小キャッシュ 1,024・long-context 改善・fast mode
Effort — 既定 high / coding は xhigh の公式推奨
Migrating to Claude 4.x — モデル移行ガイド
Claude Code model configuration — effort リセット挙動・v2.1.154+ 要件
Prompt caching — 最小キャッシュ・TTL・breakpoint 仕様

🔗 関連記事

Claude Code 7層ハーネスエンジニアリング：Opus 4.7 新機能の最適化 — 本記事の前提。7層の責務分離と Opus 4.7 機能の運用ルール化
コンテキストエンジニアリング編 — 1M context / compact 戦略の上位概念
Gemini API モデル移行ガイド — モデル世代交代をハーネスで吸収する姉妹記事

🔗 関連用語

Context Rot — 長コンテキスト下で想起精度が劣化する現象
コンテキストエンジニアリング — 本記事が扱う上位ディシプリン
ハーネスエンジニアリング — 層で責務を分ける構造そのもの