Claude Code は、それ自体がよくできたハーネスの見本だ。この記事は、そのソースを解析した設計書に沿って、ハーネスの各層が実装でどう組まれているかを読む。Claude Code の使い方と設定は Claude Code|2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き に、ハーネスエンジニアリングという言葉の意味と経緯は ハーネスエンジニアリングとは?AIエージェントのハーネスの意味・具体例・始め方 にまとめている。

2026年4月、agentway.dev が Claude Code のソースコードを解析した108ページの設計書 “Harness Engineering: A Design Guide to Claude Code” を公開した。src/query.ts、src/services/tools/toolOrchestration.ts、src/memdir/memdir.ts などの実装ファイルを読み、Claude Code が内部でどう動いているかを逆引きした技術書だ。以下のファイル名・行番号・定数は、この設計書が示す値(2026-04-01版)による。

FIVE LAYERSClaude Code のハーネス

Claude Code のハーネスは5つの層でできている

  1. コントロールプレーン

    プロンプトを優先順位つきで合成

  2. クエリループ

    状態を持って回る queryLoop()

  3. ツール管理

    安全なものだけ並列に実行

  4. 権限と割り込み

    allow / deny / ask で判断

  5. エラーとリカバリ

    段階的な回復と遮断

出典: agentway.dev「Harness Engineering: A Design Guide to Claude Code」(2026-04-01版)

この記事でわかること

  • Claude Code の5層ハーネスモデル(実装ファイルつき)
  • queryLoop() の状態機械と、モデルを呼ぶ前の入力ガバナンス
  • コンテキスト予算の定数(MEMORY.md の上限・autocompact の閾値など)
  • Prompt Too Long / max_output_tokens からの回復の順番
  • マルチエージェントでの状態の隔離と、検証の独立

なぜハーネスエンジニアリングが必要か——5層モデルの解剖

「モデルが賢ければハーネスは不要」という誤解

多くのAIプロジェクトが抱える前提がある。「モデルが高性能ならコントロール問題は解決する」という考え方だ。

この前提が崩れる理由は、モデルの問題ではなく 実行の構造 にある。Claude Code ソースを見ると、設計者がこの問題に正面から向き合った跡が見える。

  • モデルは一貫した責任を持てない(モデルは間違える)
  • ツールは外部世界に結果を残す(amplification of consequence)
  • コンテキストは膨張する(context rot)
  • 状態は後続ターンに汚染される(state contamination)
  • ユーザーは割り込む(interrupts)
  • エラーは繰り返す(failure is structural, not occasional)

「賢さ」でこれらを解決しようとすると、賢さが不十分なとき(あるいは賢さが違う方向に向かうとき)にシステムが崩壊する。ハーネスが構造として問題を解決するのは、そのためだ。

Claude Code の5層ハーネスモデル

Claude Code ソースは5つの明確なハーネス層を持つ。これらは独立して設計されているのではなく、上位層が崩れると下位層全体が信頼できなくなる依存関係にある。

層 名称 核心実装 役割
1 コントロールプレーン constants/prompts.ts, utils/systemPrompt.ts プロンプトの多層合成・行動境界定義
2 クエリループ query.ts:241 継続的な状態機械・入力ガバナンス
3 ツール管理 services/tools/toolOrchestration.ts 並行性安全制御・順序付き実行
4 権限・割り込み hooks/useCanUseTool.tsx, BashTool/prompt.ts allow/deny/ask 三値判断
5 エラー&リカバリ query.ts:453+, compact/autoCompact.ts 構造的エラー処理・サーキットブレーカー

第1層が崩れると: プロンプトが「誰が最後に書いたか」次第になり、クエリループも権限も機能しなくなる。

第5層が崩れると: エラーを catch ブロックで握りつぶすだけになり、問題を後続ターンに転がし続ける。

第1の原則はここから来る: エージェントシステムの核心能力は制約された実行だ。

プロンプトはコントロールプレーン——ペルソナ装飾ではない

「システムプロンプト=キャラクター設定」という误解

「あなたは優秀なAIアシスタントです」——このスタイルのシステムプロンプトを書いたことがある人は多いだろう。Claude Code の設計はこれを明確に否定している。

src/constants/prompts.ts:444 の getSystemPrompt() は、一本の文字列ではなく セクションの配列 を返す。これはアーキテクチャ上の主張だ。「プロンプトは構造を持つ実行規約であって、ひと続きのキャラクター説明ではない」という。

優先順位のある多層構成

src/utils/systemPrompt.ts:28 の buildEffectiveSystemPrompt() が明示する合成順序:

優先度: override > coordinator > agent > custom > default
└─ appendSystemPrompt は常に最後に付加

重要な設計判断: proactive モード のとき、agent プロンプトは default を置き換えない。default の後ろに追加される。「職務記述書が一般規約を上書きできない」という組織設計の類比だ。

proactive_mode + agent_prompt:
  base = default + agent  (置き換えではなく拡張)
  return base + appendSystemPrompt

この構造を破ると、最後に書いた人がすべてのルールを上書きできる「落書き板」になる。

4つのプロンプトセクション

Claude Code のシステムプロンプトは少なくとも4カテゴリに分離されている:

System Prompt
(多層合成)

アイデンティティ&ミッション
src/constants/prompts.ts:175
インタラクティブエージェント定義

システムルール
src/constants/prompts.ts:186
ユーザーに見える情報・拒否された
アクションの再試行禁止

エンジニアリング制約
src/constants/prompts.ts:199
不要な最適化禁止・未検証の
完了報告禁止

メモリ&CLAUDE.md
utils/claudemd.ts:1153
プロジェクト・ローカル・チーム・
自動メモリの多層統合

クエリループ——エージェントシステムの心臓部

QUERY LOOPクエリループ

1回の呼び出しではなく、状態を持ったループで動く

  1. 入力ガバナンス

    履歴とツール結果を予算内に整える

  2. モデル実行

    出力をイベントとして受ける

  3. ツール実行

    安全なものは並列、ほかは順に

  4. 回復と継続

    失敗を回復し、続けるか決める

出典: agentway.dev の設計書(query.ts:241 の queryLoop())

「一問一答」ではなく「継続的状態機械」

「Claude は一回の API 呼び出しで動く」——この前提でハーネスを設計すると、本番で必ず壊れる。

Claude Code の中心は src/query.ts:219 の query() だが、本体は src/query.ts:241 の queryLoop() だ。この関数が持つ State オブジェクトを見れば、設計意図が明確になる:

// src/query.ts:203–217 (skeleton)
state = {
  messages,                       // 会話履歴
  toolUseContext,                  // ツール実行状態
  autoCompactTracking,             // コンパクト追跡
  maxOutputTokensRecoveryCount,    // max_tokens リカバリ回数
  hasAttemptedReactiveCompact,     // リアクティブコンパクト試行済みフラグ
  pendingToolUseSummary,           // 保留中ツール要約
  stopHookActive,                  // stop-hook 有効フラグ
  turnCount,                       // ターン数
  transition,                      // 遷移状態
}

この State は各イテレーションで丸ごと更新される。「スクリプトは『このステップが終わったか』だけ問う。エージェントシステムは『次のステップが失敗したステップの状態から継続できるか』も問わなければならない」——設計書の核心的な主張だ。

フェーズ1: 入力ガバナンス(モデル呼び出し前に整備する)

queryLoop() が最初にすること: モデルに渡す前にコンテキストを整備する。

多くのシステムとの違いはここにある。「大量のコンテキストをそのまま渡してモデルが大事なものを選ぶ」のではなく、「ランタイムが先に整理する」。

モデル呼び出し前の実行順序:
1. メモリプリフェッチ      query.ts:297  — MEMORY.md インデックス読み込み
2. スキル検出プリフェッチ  query.ts:323  — 利用可能スキル一覧
3. メッセージスライス      query.ts:365  — compact境界以降のみ選択
4. tool result budget     query.ts:369  — ツール結果を予算内に収める
5. history snip           query.ts:396  — 履歴を切り詰め
6. microcompact           query.ts:412  — 軽量コンパクト
7. context collapse       query.ts:428  — コンテキスト圧縮
8. autocompact            query.ts:453  — 自動コンパクト(最後の手段)

これは「制御を渡す前に現場を整備する」という伝統的なエンジニアリングの発想だ。洗練とは言えないが、安定性は高い。

フェーズ2: モデル実行はループの一フェーズ

入力ガバナンスの後、query.ts:652 付近でモデル呼び出しに入る。重要なのは、出力を イベントストリームとして消費する こと。最終的な大きなブロブを一度に受け取るのではない。

// skeleton
events = stream_model(state)
for e in events:
  if e.is(tool_use):     schedule(e, state.toolUseContext)
  if e.is(api_error):    return surface(e)
if interrupted:          drain_tools_with_synthetic_results(state); break

「割り込み」の処理が特徴的だ。 ユーザーが実行を中断したとき、進行中のツール呼び出しに合成結果(synthetic result)を付与して閉鎖する。これにより tool_use/tool_result の対応表(ledger)が必ず閉じた状態を保つ。dangling tool_use ブロックを残さない。

フェーズ3: ツールの並行制御

ツール実行は toolOrchestration.ts が管理する。partitionToolCalls() がツール呼び出しを分類し、isConcurrencySafe() で並行安全性を判定:

  • 安全なツール: バッチ実行(並列)
  • 危険なツール: 逐次実行(シリアル)

並行パスでは、コンテキスト変更をバッファしてオリジナルブロック順序で再適用する(toolOrchestration.ts:31–63)。これはファイルシステム・ターミナル・Git という不可逆的な外部世界に触れるツールを扱うための保守的設計だ。

無制限な並列化はブラスト半径を拡大する
ツールを並列実行するほど「何かが失敗したとき」の影響範囲が広がる。Claude Code がここで保守的な戦略を取っているのは、ファイルシステムへの変更・シェル実行・Gitリポジトリへの操作が「元に戻せない結果」を生むからだ。

3つのループ不変条件

assert state.turnCount_{t+1} >= state.turnCount_t   # ターン数は単調増加
assert every emitted tool_use has a tool_result      # ledgerは必ず閉じる
assert hasAttemptedReactiveCompact => no further compact  # 再コンパクトループ防止

これらのうち1つでも崩れると、クエリループ全体が信頼できなくなる。

第3の原則: クエリループはエージェントシステムの心臓部だ。入力ガバナンス・ストリーム消費・ツールスケジューリング・リカバリ・停止条件はすべてハートビートに属する。

ツール・権限・割り込み——モデルが世界に触れる層

「言える」から「残せる」へのリスク転換

モデルがテキストのみ出力するとき、最悪でも「過信した文体」になる。ツールを呼べるようになると、リスクは 言語リスクから実行リスク に転換する。

Claude Code の答えは明確だ: ランタイムがツールの実行可否を決める。モデルが決めるのではない。

allow / deny / ask の三値判断

src/hooks/useCanUseTool.tsx が実行可否を三値で決定する:

// permission decision skeleton
decision = hasPermissionsToUseTool(tool, input, ctx)
match decision:
  allow: exec(tool, input)
  deny:  reject(reason)
  ask:   route_to(coordinator | reviewer | operator)

// 不変条件
assert decision ∈ {allow, deny, ask}   // 三値、絶対に崩さない
assert ask => never auto-escalates to allow  // askは自動的にallowにならない

「ask」が自動的に「allow」にエスカレートしないことが重要だ。三値が二値(allow/deny)に縮退するとき、人間の承認ポイントが意味を失う。

Bash に高密度制約が必要な理由

Bash は最も危険なツールだ。ファイル・プロセス・ネットワーク・Git リポジトリに直接アクセスでき、シェルリダイレクトとパイプラインのセマンティクスまで持つ。ドメイン境界がほぼない。

src/tools/BashTool/prompt.ts:42 以降には詳細なオペレーションルールが列挙されている:

git config をランダムに変更しない
フックをスキップしない (--no-verify 禁止)
git add . は避ける
pre-commit失敗後に --amend で前のコミットを畳み込まない
明示的に指示されない限りコミットしない
デフォルトでpushしない

「細かすぎる」と感じる人もいる。しかし高リスクなインターフェースは高密度の制約が必要だ。能力が強いほど制御は細かくする ——これはハーネスエンジニアリングの核心原則の一つだ。

コンテキストガバナンス——メモリ・CLAUDE.md・コンパクトの設計

「コンテキストを増やすほど賢くなる」という危険な神話

エージェントシステムはライブラリではない。コンテキストは「倉庫に保管」するものではなく、高コストで膨張しやすく自己汚染する予算だ。

claudemd.ts:1153
層別ロード

memdir.ts:187
インデックス参照

SessionMemory/prompts.ts
継続ブリーフ

slice / snip / compact

コンテキストガバナンス

長期記憶: CLAUDE.md
stable rules / team norms

永続メモリ: MEMORY.md + body files
cross-session facts

セッションメモリ: SessionMemory
within-session continuity

一時対話: chat history
current turn context

モデル入力

CLAUDE.md 階層:「誰の命令か」で優先度が変わる

src/utils/claudemd.ts の先頭でメモリ層が明確に定義されている:

managed memory  → /etc/claude-code/CLAUDE.md         (最高優先: システム管理者)
user memory     → ~/.claude/CLAUDE.md                 (ユーザー設定)
project memory  → CLAUDE.md / .claude/CLAUDE.md       (リポジトリ設定)
              → .claude/rules/*.md                   (ルールファイル群)
local memory    → CLAUDE.local.md                     (ローカル上書き、git管理外)

現在のディレクトリに近いファイルほど優先度が高く、モデルのアテンション前部に配置される。安定したチームルールを一時的なチャットと混ぜない のが設計の意図だ。

@include は許可された拡張子のテキストファイルのみ対象にする。バイナリ・巨大ドキュメント・プロンプトインジェクションリスクのあるファイルの誤包含を防ぐ実践的な抑制だ。

MEMORY.md はインデックス、本文ではない

src/memdir/memdir.ts の設計判断: ENTRYPOINT_NAME は MEMORY.md だが、直接コンテンツを書く場所ではない。インデックスだ。

正しい使い方:
  1. 具体的メモリ内容を専用ファイルに書く(例: feedback_testing.md)
  2. MEMORY.md に1行ポインタを追加する

  MEMORY.md の役割 = 目次
  body file の役割 = 本文

なぜこの分離が重要か。MEMORY.md は頻繁にロードされる。肥大化するとコンテキストがインデックス重みで圧迫される。

buildMemoryLines() が設定するハードリミット:

定数名 値 目的
MAX_ENTRYPOINT_LINES 200 MEMORY.md の最大行数
MAX_ENTRYPOINT_BYTES 25,000 MEMORY.md の最大バイト数

超過時: truncateEntrypointContent() が自動切り捨て+警告を追加する。

autocompact: コンテキストガバナンスは予算管理だ

src/services/compact/autoCompact.ts の実装:

getEffectiveContextWindowSize()
  = コンテキストウィンドウサイズ
  - MAX_OUTPUT_TOKENS_FOR_SUMMARY (20,000)  ← compact自体のコスト予約
  - AUTOCOMPACT_BUFFER_TOKENS (13,000)       ← 早期警告バッファ

重要な設計哲学: 酸素が尽きてから行動するのではなく、余裕があるうちに compact を実行する。準備なしのシステムは通常ケースでは倹約に見えるが、リスク決済を後のターンに先送りしているだけだ。

autocompact のバジェット定数一覧:

定数名 値 ソース
MAX_OUTPUT_TOKENS_FOR_SUMMARY 20,000 compact/autoCompact.ts
AUTOCOMPACT_BUFFER_TOKENS 13,000 compact/autoCompact.ts
MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES 3 compact/autoCompact.ts
MAX_ENTRYPOINT_LINES 200 memdir/memdir.ts
MAX_ENTRYPOINT_BYTES 25,000 memdir/memdir.ts

AutoCompactTrackingState は compacted・turnCounter・turnId・consecutiveFailures を追跡する。失敗は追跡され、制限される。

サーキットブレーカー: MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3 を超えると遮断。これは「大量のAPIコールが繰り返しのautocompact失敗で無駄になった」という具体的な過去の教訓から来ている設計だ。

第5の原則: コンテキストは作業メモリだ。ガバナンスはシステムが作業を継続できる状態を保つためにある。

エラーとリカバリ——失敗はメインパスだ

3つのエラーリカバリパス — PTL(Prompt Too Long)・max_output_tokens・autocompact失敗のそれぞれのリカバリ手順とサーキットブレーカー定数

「例外」ではなく「構造的条件」として設計する

多くのソフトウェアが成功パスをメインテキストとして、失敗パスを例外として扱う。エージェントシステムにこのアプローチは通じない。

トークン上限ヒット・プロンプト長超過・ツール拒否・ユーザー割り込み・フックブロック・APIリトライ——これらは「たまに起きること」ではない。長時間セッションでは構造的に発生する。

3つのリカバリパスの詳細

PTL (Prompt Too Long) リカバリ:

on prompt_too_long:
  if stagedCollapse > 0:          # Step 1: 段階的コンテキスト縮小
    recoverFromOverflow()
  elif not hasAttemptedReactiveCompact:  # Step 2: 強制compact(1回のみ)
    tryReactiveCompact()
  else:                           # Step 3: エラーサーフェス
    surface(e)
    skip_stop_hooks()             # stop-hookをスキップ

# 破壊性: Step1 < Step2 < Step3

リアクティブコンパクトを「1回のみ」に制限しているのは、hasAttemptedReactiveCompact フラグが管理する。compact がループを作ることを防ぐ不変条件: assert hasAttemptedReactiveCompact ⇒ no further compact。

max_output_tokens リカバリ:

on max_output_tokens:
  if cap < MAX:                   # Step 1: 上限引き上げ
    raise(maxOutputTokensOverride)
    retry()
  else:                           # Step 2: 継続メタメッセージ
    append(meta_continue_msg)
    retry()

ここで重要なのは「要約より継続を優先」する設計哲学だ。切断後にユーザーを失敗状態に閉じ込めず、「続きはここから」という形で再開させる。

autocompact 失敗リカバリ:

AutoCompactTrackingState:
  compacted: bool
  turnCounter: int
  turnId: str
  consecutiveFailures: int       # ← 失敗を追跡

# circuit breaker
if consecutiveFailures >= MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES:
  break  # サーキットブレーカー発動、エラーを報告

停止条件は複数が必要

多くのシステムが停止条件を1つしか持たない。これは問題だ。完了と失敗が同じ停止条件を共有すると、失敗したまま「完了」として終わるか、永遠に終わらないかのどちらかになる。

Claude Code は4つの停止セマンティクスを持つ: 完了 / 失敗 / リカバリ / 継続。これらは transition state として管理される。

第6の原則: エラーパスはメインパスだ。PTL・max_output_tokens・割り込み・フックループ・compact失敗は長時間エージェントにとって通常の気象現象だ。

マルチエージェントと検証——不確実性を分割する

マルチエージェント設計 — Coordinator-Workerパターン・状態隔離・検証独立・親子abort伝播の詳細図(src/utils/forkedAgent.ts)

マルチエージェントの本当の価値は速度ではない

「並列実行で速くなる」——これはマルチエージェントの最も表面的な価値だ。より深い価値は不確実性の分割にある。

リサーチ・実装・検証・統合を異なる責任コンテナに分割することで:

  • 状態が隔離される(汚染が伝播しない)
  • 役割が分離される(自己評価バイアスが構造的に防がれる)
  • コーディネーターが理解を再収束させる

コーディネーターの責任:転送ではなく統合

src/coordinator/coordinatorMode.ts が示すコーディネーターの責任:

やるべきこと: Worker出力の矛盾を解消し、優先順位付けし、一貫した最終出力に統合する。

やってはいけないこと: Worker出力をそのままユーザーに転送する。

「マルチエージェントを使っているが全員が似たような作業をして、誰も統合や検証を担当していない」——これは並列化された混乱だ。コーディネーターが統合責任を持たないと、マルチエージェントの複雑さだけが増えて品質は向上しない。

検証は独立フェーズでなければならない

src/skills/bundled/verify.ts が実装する独立検証ステージ。

実装者は自分の変更を自然と信頼しすぎる。モデルはさらにそうなる傾向がある。だから重要な作業では、検証を独立した専用フェーズにする必要がある。

Verifier エージェントの設計原則:

  • 懐疑的なシステムプロンプトでチューニング
  • Generator/Implementer とは別のコンテキストで動作
  • 「問題がなければ承認」という明確な判断権限を持つ
  • Generator に差し戻す権限も持つ
Verifierの評価軸を事前に定義する
「なんでも批判してください」という曖昧な指示は機能しない。機能要件充足・エッジケース・エラーハンドリング・パフォーマンスなど、評価軸を事前に定義すると Verifier の一貫性が上がり、Generator との往復が効率化する。

第7・8の原則: マルチエージェントは不確実性を分割するためにある / 検証は実装から独立しなければならない。

10の原則——設計書の結論

108ページが最終的に圧縮される10の原則を、実装の根拠と一緒に示す。

1. モデルを不安定な
コンポーネントとして扱う
チームメイトではない

2. プロンプトは
コントロールプレーンの一部
ペルソナ装飾ではない

3. クエリループが
心臓部
一問一答ではない

4. ツールは
管理された実行I/F
能力の自然延長ではない

5. コンテキストは
作業メモリ
倉庫ではない

6. エラーパスが
メインパス
afterthoughtではない

7. リカバリは
継続を最適化する
要約優先ではない

8. マルチエージェントは
不確実性を分割する
速度のためだけではない

9. 検証は
独立でなければならない
自己評価はバイアスがかかる

10. チーム制度が
個人技術より重要
習熟依存は拡張しない

設計書の最終文:

ハーネスエンジニアリングが問うのは、モデル自体が信頼できないときに、それでもシステムが工学的に振る舞えるかどうかだ。

Claude Code ソースが本当に教えているのは自制心だ: 不安定さを既知の入力として受け入れ、その入力を前提にプロンプト・ループ・ツール・メモリ・コンパクト・リカバリ・検証・チームワークフローを設計する。

ハーネスより興奮、制度より賢さ、確信より検証——これらを逆転させたチームが、ハーネスエンジニアリングの入り口に立っている。

まとめ:Claude Code のハーネスから持ち帰ること

設計書の結論は、モデルを「間違える部品」として扱い、プロンプト・ループ・ツール・メモリ・回復・検証を構造で固めることだった。自分のエージェントに移すときは、まず入力ガバナンスと回復の順番、検証の独立の3つから真似るとよい。本番に出すための設計パターン(Generator/Evaluator 分離・ラチェット原則)は AIエージェントのハーネス設計パターン で扱っている。

参照ソース