Claude Code 7層ハーネスエンジニアリング：Opus 4.7 新機能の最適化

📖 背景

Claude Code を SaaS 規模の長期プロジェクトで使い続けると、CLAUDE.md に全ルールを書き込む運用はすぐに限界が来る。ファイルが 500 行を超え、毎ターン cache の温度が揺らぎ、Opus 4.7 の 1M context を使っても recall が劣化する（Context Rot）。

この問題に対して、CTS の SaaS 開発プロジェクトでは 7 層にコンテキストを分離する「ハーネスエンジニアリング」 を採用している。本記事では各層の役割と、Opus 4.7 固有機能を CTS がどう運用ルールに落とし込んでいるかを紹介する。

🧱 7層の全体像

この7層には明確な責務分離の原則がある。「常時ロード」に載るのは第1層と第4層のみ、それ以外はすべて条件付き遅延ロード。これが 1M context 時代でもコンテキストを「細く長く」保つための核心だ。

🎯 層ごとの設計意図

第1層: CLAUDE.md — 「やらないこと」の集約

CLAUDE.md は全ターンで暗黙的に読まれるため、肥大化すると cache prefix が揺れて全無効化を招く。そこでプロジェクトでは 10 個の必須ルール（禁止事項中心） に絞り、詳細は Skills に委譲する構造にした。

## STOP: 必須ルール（10個）
1. main への直接 Push 禁止
2. Push と MR 作成は同時に実行
# 以下 8 項目（抜粋）

“STOP:” プレフィックスを統一してモデルの注意を引き、記述密度を上げている。

第2層: Skills — paths: frontmatter で条件発火

Skills は paths: frontmatter でロード条件を宣言する。

---
name: dotnet-development
description: .NET バックエンド開発ルール
paths: "dotnet/**/*.{cs,json}"
---

これによって dotnet/ 配下を編集するターンでのみ .NET ルールがロードされ、frontend 作業中は cache を汚染しない。Opus 4.7 の 1M context でも、attention budget は有限という前提に立つと、不要な層のロードは常に害。

第3層: Agents — 責務マトリクスで並列化

サブエージェントは単なる「別タスク」ではなく、観点重複を設計的に排除して並列起動する対象として扱う。例えばコードレビューは 2 エージェントに分割:

責務マトリクスが明示されているため、並列起動しても出力が被らない。wall-clock が約半分になる。

第4層: Settings — deny で破壊的操作を宣言的に禁止

allow だけで運用するケースが多いが、実運用では deny も必須。

"deny": [
  "Bash(rm -rf /*)",
  "Bash(git push --force*)",
  "Bash(git reset --hard*)",
  "Bash(dropdb:*)",
  "Bash(terraform destroy*)"
]

Hooks でも branch-guard は実装しているが、宣言的 deny の方が後から読んだ人間が監査しやすい。

第5層: Hooks — 自動ゲートの主戦場

このプロジェクトで特に効いているのが 5 種のフック。

UserPromptSubmit の evidence-gate は特に効く。「先ほどの設計を思い出して」とユーザーが打った瞬間、hook がキーワードを検知して「記憶ではなくツール実行で裏取りせよ」という system メッセージを注入する。Claude 自身の confidence を運用側が外部から押し下げる設計。

第6層: Memory — 失敗事例の永続化

エージェントごとの学習は .claude/agent-memory/<agent-name>/ に、プロジェクト全体の学習は .serena/memories/ に分けて永続化する。特に doc-reviewer の memory には「どのドキュメントで過去どんな指摘が出たか」が蓄積されており、レビュー再実行時の精度が上がる。

第7層: Steering — タスク単位の SSoT

対話の状態をすべて .steering/YYYYMMDD-<title>/ に書き戻す。requirements.md / design.md / tasklist.md / decision.md の4点セットで、セッションが切れても文脈を復元可能。これが Context Rot 対策の最後の砦でもある。

🚀 Opus 4.7 新機能への対応

1M context と Context Rot

Opus 4.7 は 1M context を持つが、Anthropic 公式の Context engineering ガイドも「attention budget は有限」「トークン上限まで使い切ることは非推奨」としている（Context windows ドキュメントも同様）。プロジェクトでは 兆候ベースの Context Rot 検知 を採用した。

兆候チェックリスト:

• 直前の指示を忘れる・反復を求められる
• Read 済みファイルの内容を誤引用する
• tasklist.md の項番を取り違える
• 「先ほどの〜」の参照先が不正確

1 つでも該当したら即座に:

1. Read / Grep で裏取り（Evidence over Claims）
2. 進行中タスクを tasklist.md に書き戻す
3. 500K 未満でも /compact を前倒し
4. セッション分離（/resume で再開）

実運用閾値:

Adaptive Thinking

Opus 4.7 は Adaptive Thinking のみをサポートし、Manual thinking: {budget_tokens: N} を渡すと 400 エラーで拒否される（Opus 4.6 からの silent breaking change）。また display デフォルトが summarized → omitted に変更されているため、思考内容を表示したい場合は display: "summarized" の明示指定が必要。

自前 API を書く場面での effort 選択基準:

Server-side Compaction との使い分け

Anthropic API の beta 機能 compact-2026-01-12（Context management 公式アナウンス）は、入力 150K トークンを超えると自動で古い履歴を要約する。ローカル /compact との最大の違いは cache への影響:

運用上は Claude Code CLI ではローカル /compact を SSoT とし、自作 API 実装時のみ server-side を opt-in する。

Prompt Caching の 5 分 TTL 意識

一言でいえば 「サブエージェントはまとめて一気に呼べ」。背景には Prompt Caching の 5 分 TTL というコスト構造がある。

なぜ同時発射か — API コスト構造

Claude Code は内部で Anthropic API の cache_control ブロックを自動設定している。CLAUDE.md / Skills / Agents 定義はキャッシュブロックとして保存され、5 分以内に再利用すれば読み込みコストが基本入力の 1/10（90% 割引） になる。

計算上、2.5 回ヒットすれば書き込み時の割増分を回収できる。CLAUDE.md + Skills + Agents 定義で軽く 30K tokens を使う運用では、cache hit 率の差が請求額に直結する。最小キャッシュサイズは Opus 4.7 で 4,096 tokens、Sonnet / Haiku で 1,024 tokens（これ以下の短いプレフィックスはキャッシュされない）。

バラバラ起動 vs まとめ起動

❌ バラバラ起動（cache 切れの連鎖）
  10:00  code-reviewer 起動   → cache 新規作成（1.25 倍）
  10:08  test-runner 起動     → 5 分超過で expired → また 1.25 倍
  10:20  doc-reviewer 起動    → また expired → また 1.25 倍
  書き込み × 3 回、cache hit ゼロ

✅ まとめ起動（同じメッセージ内で並列発射）
  10:00  code-reviewer + test-runner + doc-reviewer  同時
  書き込み × 1 回、残り 2 つは cache hit（0.1 倍）

副次的に wall-clock も 1/2 〜 1/3 に短縮し、モデルの attention も同じ文脈で揃うため判断の一貫性が上がる。

運用ルール（cache を壊す典型パターン）

300 秒ルール — ScheduleWakeup の delay 選択

300 秒（5 分ちょうど）はワーストオブボース。TTL 境界に乗るため cache miss が確定しやすく、かつその miss を償却できる長さでもない。取るべきは 270 秒（cache 温存） か 1200 秒以上（cache を諦めて長く待つ） の二択。

# ✅ cache 温存（4 分 30 秒で戻る）
ScheduleWakeup(delaySeconds=270, reason="bun build ~8min wait, cache warm")

# ✅ cache 諦めて長く休む
ScheduleWakeup(delaySeconds=1200, reason="CI deploy 20min wait")

# ❌ 最悪パターン（cache miss 確定、しかも償却されない）
ScheduleWakeup(delaySeconds=300, reason="wait 5 min")

Cache の仕組みが CLI では、あまり知られていない

Claude Code CLI を使う限り、cache は完全に裏方で、ユーザーが cache_control ブロックを直接意識する設計にはなっていない。ところが起動タイミングと指示順序で cache hit 率は 10% ～ 80% の差が出る。API 従量課金や Max プランの上限到達時に、請求書やレート制限として初めて表に出てくるため、平時は気付きにくい構造である。Anthropic SDK を直接叩く実装では cache_control / cache_creation_input_tokens / cache_read_input_tokens が API レスポンスに露出するため、そちらを触って初めて挙動が腹落ちするケースも多い。

CTS の 7 層ハーネスでは、この「裏方のコスト構造」を Claude Code 運用者が起動タイミングと指示順序で最適化できる運用ルールに翻訳している。TTL 5 分という API 側の制約があるからこそ、「サブエージェントはまとめて起動」「300 秒 delay を避ける」といった具体的なルールが導出される。

💰 モデル割り当てとコストパフォーマンス

Claude Code は Agent 単位でモデルを指定できる（agent frontmatter の model: opus | sonnet | haiku）。これを第 3 層の責務マトリクスと組み合わせることで、重い Opus を常時呼ばず、検証・整形系は Sonnet、軽量処理は Haiku に振り分けられる。

CTS での Agent 別モデル割当

重い Opus の出番は Phase 境界・計画立案に限定、日常のレビュー / 実装ループは Sonnet、構造化整形は Haiku が主役。これだけで Opus 呼び出し回数は体感 1/3 以下になる。

各 Agent の agents/*.md 定義（フロントマターでの model 指定、責務マトリクス、チーム構成、マルチエージェント協調）の実装詳細は、Agent Teams 編で扱う（ステアリング駆動開発シリーズ #8）。

実運用コスト感

この割当で SaaS 規模の EC プロジェクトを毎日フル稼働で運用しても、Claude Max 20x プランの利用制限に到達した月は一度もない。ハーネスがモデルを適切に振り分けるため、常時運用でも枠に収まる。

「Claude Code はすぐ制限、Codex 併用を」論との距離

巷では「Claude Code はすぐ利用制限に引っかかる」「Codex（OpenAI）を併用すべき」という言説も見られる。CTS の運用実感では、これは Claude Code そのものの限界ではなく、ハーネス設計が不足しているケースがほとんどである。

モデルそのものの能力以上に、ハーネスが既存機能を引き出せているかが運用寿命を決める。他モデル（Codex 等）の併用は、OpenAI SDK 固有の挙動調査など特殊タスクに限定すれば十分で、日常の開発運用で標準化する理由にはならない。

🔄 7層が噛み合う瞬間

ある MR 前の検証フローを例に、7層がどう連動するか示す。

① ユーザー: /pre-push

② Hook (PreToolUse) → push-readiness スタンプを確認
③ Skill (steering/common) → tasklist.md の未完了確認
④ Agent 並列起動（5分 TTL 内）
   ├─ code-reviewer            (Sonnet 4.6)
   ├─ implementation-validator (Sonnet 4.6)
   └─ test-runner × 3 layer    (Sonnet 4.6)
⑤ Memory (agent-memory/*) → 過去の指摘パターンを参照
⑥ Settings.deny → 万一の git push --force を宣言的にブロック
⑦ Steering (tasklist.md) → 結果を書き戻して永続化

並列起動は cache 温存を前提に 5 分 TTL 内に集約、責務マトリクスで観点重複を排除、Memory で過去のミスを学習済み、という設計が揃って初めて Opus 4.7 の 1M context を「細く長く」使える。

⚠️ 失敗例から学んだこと

実際に運用して判明した落とし穴:

🏁 7層ハーネスの完成度

本 7 層ハーネスは、Anthropic が 2026 年までに公開した最新のコンテキスト制御機能をすべて運用レイヤーに取り込んでいる。

つまり本ハーネスは「Opus 4.7 の新機能に後追いで対応した構成」ではなく、Anthropic が公開しているハーネスエンジニアリングの原則を、SaaS 規模のプロジェクトで運用可能な形に具体化したリファレンス実装である。モデル側の仕様変更（Opus 4.8 以降）が来た場合も、該当する層のみを差し替えれば追随できる。

✅ まとめ

• CLAUDE.md / Skills / Agents / Settings / Hooks / Memory / Steering の 7 層で責務を分離
• 常時ロードは最小限（第1層・第4層のみ）、他は条件発火で attention budget を節約
• Opus 4.7 の Adaptive Thinking・Server-side Compaction・1M context は「機能として知っている」では不十分。運用ルールに落とし込んで初めて使える
• Context Rot は兆候ベースで検知、数値閾値だけに頼らない
• Prompt Cache は運用側の指示順序で温度を保つ（5 分 TTL を跨がない / 300 秒 delay を避ける）

Claude Code の真価は、モデル単体の能力ではなく モデルとハーネスを一緒に設計すること で初めて引き出せる。1M context を「使い切る」のではなく「細く長く保つ」設計が、Opus 4.7 時代のコンテキストエンジニアリングの本質である。

🔗 参考資料

• Effective context engineering for AI agents — Anthropic 公式の Context Engineering 総論
• Effective harnesses for long-running agents — ハーネス設計の原則
• Managing context on the Claude Developer Platform — Server-side compaction を含む context 管理機能
• Building with extended thinking — Adaptive Thinking 仕様
• Prompt caching — 5 分 TTL / 4 breakpoint の仕様
• Context windows — 1M context と compaction の API ガイド
• Long context prompting tips — 長いコンテキストでの指示順序のベストプラクティス

🔗 関連記事

• ステアリング駆動開発とは：概要 — 本ハーネスを動かす上位概念。シリーズ #1
• Agent Teams 編 — 本記事で扱った Agent 別モデル割当・責務マトリクスの実装詳細（.claude/agents/*.md 定義、チーム構成、マルチエージェント協調）。ステアリング駆動開発シリーズ #8
• Gemini API モデル移行ガイド — モデル世代交代をハーネス側でどう吸収するかの姉妹記事

🔗 関連用語

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