「AIエージェントに自律的に動いてほしい」——この願いを持ったエンジニアが今、共通の壁に当たっている。デモでは動く。でも本番では壊れる。原因の多くはモデルの限界ではなく、モデルを動かす環境の設計不足だ。

その環境設計に体系的に取り組む方法論が「ハーネスエンジニアリング」だ。

この記事ではClaude Codeに特化して解説します。Claude Code全般は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。

この記事でわかること

  • ハーネスエンジニアリングの5つの流派と定義の違い
  • Fowlerの「Guides + Sensors」二軸モデルと実践への応用
  • Context Rot・長期タスク設計の最新知見
  • どの流派の考え方をどう使い分けるか——判断フロー

「ハーネスエンジニアリング」——なぜ定義が人によって違うのか

ハーネスエンジニアリングという言葉が急速に広まった2025〜2026年、奇妙な現象が起きている。言葉を使う人によって、指している範囲がまるで違うのだ。

「ハーネスって何ですか?」と5人の専門家に聞けば、5通りの答えが返ってくる。これは定義が未整備なのではなく、それぞれが異なる問題意識から同じ言葉に辿り着いたからだ。

日本語でのハーネスエンジニアリング論考（speakerdeck.com/kinopeee/hanesuenziniaringutoha）が整理した5つの流派は、この状況をよく表している。

flowchart TD H["ハーネスエンジニアリング"] --> A["Chase派
「モデル以外のすべて」"] H --> B["Hashimoto派
「失敗を再発不能にする環境」"] H --> C["Fowler派
Guides + Sensors"] H --> D["Chawla派
プロンプト⊂コンテキスト⊂ハーネス"] H --> E["Codex派
プロダクションスケール対応"] style H fill:#4A90D9,color:#fff style A fill:#F5A623 style B fill:#7ED321,color:#fff style C fill:#BD10E0,color:#fff style D fill:#E74C3C,color:#fff style E fill:#50E3C2

各流派の中心にある考え方を整理する。

5つの流派の比較——何が同じで何が違うか

Chase派：「モデル以外のすべてがハーネス」

LangChain創業者のHarrison Chaseが体現する考え方だ。

“If you’re not the model, you’re the harness.”

ツール実行、メモリ管理、サブエージェント制御、ガードレール、オーケストレーション——これらすべてがハーネスに含まれる。包括的・総合的なフレームワーク設計の視点から語られるため、LangChain・LangGraphのような大型フレームワークの文脈で使われることが多い。

この定義の利点は「モデルへの入出力以外はすべてエンジニアリング対象」という明快さだ。一方で広すぎて、「ハーネスを改善しよう」という議論が何を指しているのか曖昧になりやすい。

Hashimoto派：「失敗を物理的に再発不能にする環境の累積」

HashiCorp創業者のMitchell Hashimotoが実践し発信している流派で、現場感覚に最も近いとされる。

プロセスはシンプルだ。

  1. エージェントが失敗する
  2. その失敗が「物理的に起きないような」ルールをAGENTS.mdやCLAUDE.mdに追記する
  3. 繰り返す

特別なアーキテクチャ設計から始まるのではなく、実際の失敗から学んでルールファイルを育てていく。後から振り返ると、ルールファイルが「蓄積されたハーネス」になっているという考え方だ。

この流派の強みは「今日から始められる」点だ。何か大掛かりなシステムを構築する前に、エージェントを実際に動かして失敗から学ぶ。その記録がそのままハーネスになる。

Hashimoto流の始め方: エージェントに何か作業させて、失敗したら「なぜ失敗したか」をAGENTS.mdに1行追加する。これを繰り返すだけでハーネスが育ち始める。設計から入るより実行から入る方が、現場では機能する。

Fowler派：「Guides（事前制御）+ Sensors（事後検証）」

ThoughtworksのDistinguished EngineerであるMartin Fowlerのハーネスエンジニアリング論文が提唱する構造化された二軸モデルだ。

Fowler派の定式は Agent = Model + Harness であり、HarnessをGuidesとSensorsの二軸で定義する。

軸 制御タイミング 役割
Guides（ガイド） 事前（フィードフォワード） エージェントが最初から正しい結果を出せるよう誘導
Sensors（センサー） 事後（フィードバック） エージェントの出力を外部から監視し自己修正を促す

GuideとSensorはさらにそれぞれ「計算的（deterministic）」と「推論的（probabilistic）」に分かれる。

flowchart LR subgraph Guides["Guides（事前制御）"] G1["計算的ガイド
LSP・自動補完
ブートストラップスクリプト"] G2["推論的ガイド
AGENTS.md・スキル定義
アーキテクチャ原則"] end subgraph Sensors["Sensors（事後検証）"] S1["計算的センサー
Lint・型チェッカー
構造テスト"] S2["推論的センサー
AIコードレビュー
E2Eテスト"] end M["モデル"] --> Guides M --> Sensors Sensors -->|"自己修正フィードバック"| M

Fowler派の強みは、何をどの層で対処するかを明確に区別できる点だ。「このチェックはLintでやる（計算的センサー）のか、AIレビューエージェントでやる（推論的センサー）のかを意識的に選択できる」という設計判断の軸になる。

また「コンテキスト設計の特定形式」としてハーネスを位置づけることで、CLAUDE.mdやAGENTS.mdの記述がどの軸に貢献しているかを整理できる。

Chawla派：「プロンプト⊂コンテキスト⊂ハーネスの三重構造」

教育系ライターのAvi Chawlaが提唱する初学者向けの可視化モデルだ。

ハーネス
  └─ コンテキスト
        └─ プロンプト

「LLMはCPU、コンテキストはRAM、ツールはデバイスドライバ、ハーネスはOS」というコンピュータアーキテクチャのアナロジーで説明する。

この流派はChase派と逆の包含関係になることがある点が注意だ。Fowler派では「ハーネス⊂コンテキスト設計」となる場合もある。

用語の混乱に注意: ハーネスエンジニアリングを語るとき、相手がどの流派の文脈で話しているかを確認しないと議論がすれ違う。「ハーネスってコンテキストより広い概念ですよね」（Chase派）vs「ハーネスはコンテキスト設計の一部ですよね」（Fowler派）——どちらも正しく、文脈による。

Codex派：「プロダクションスケール特有の故障モードへの対応」

OpenAI CodexチームのRyan Lopopoloが体現するスケール駆動の流派だ。「3人で百万行、95% AI生成」という実績から生まれた考え方で、小規模では現れない問題——Context Rot、コスト爆発、セッション間の記憶損失、再現不能なバグ——に対処するための構造設計を指す。

この流派が重要なのは、デモ環境と本番環境の差を最も直視しているからだ。

エンタープライズAIエージェントプロジェクトの88%が本番到達に失敗するという市場データは、Codex派が解くべき問題の大きさを示している。

5流派の比較と選択指針

流派 核心 強み 弱み 最適なシーン
Chase モデル以外すべて 包括的・明快 広すぎて議論が曖昧に フレームワーク設計・全体設計
Hashimoto 失敗から育てる 即実践可能・現場的 体系化しにくい 個人・小チームの開発
Fowler Guides + Sensors 設計判断を明確化 複雑・学習コスト高 チーム設計・大規模システム
Chawla 三重構造 初学者に伝わりやすい 現場応用に限界 教育・説明の場面
Codex 本番故障モード対応 実際の問題を直視 前提知識が必要 プロダクション展開

実務では単一の流派に縛られる必要はない。Hashimoto流で始めて（失敗から学ぶ）、Fowler流で整理し（Guides/Sensors）、Codex流でスケールに対応する——という重ね使いが現実的だ。

「言葉の定義は重要ではない。大切なのは期待した結果を得ること」——kinopeee

日本の現場は命名が広まる前から同じ実装を行っていた。名前がついたことで体系化できるようになったが、定義論争より手元の環境をどう改善するかが本質だ。

Fowler派の実践——Guides設計とSensors設計

Fowlerモデルは設計の判断軸として最も実用的だ。Claude Code環境での具体例を示す。

Guidesの設計

計算的ガイド（確定的・高速）

# .claude/settings.json — 許可ツールの明示的設定
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git diff *)",
      "Read",
      "Write(src/**)",
      "Edit(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  }
}

許可・拒否リストは確定的ガイドの典型だ。モデルがどんな推論をしても、このリストで決まったツールしか使えない。

推論的ガイド（確率的・柔軟）

# CLAUDE.md — 推論的ガイドの例

## アーキテクチャ原則
- 新規ファイルは必ず src/features/{feature-name}/ 配下に作成する
- 外部APIコールは必ず src/lib/api/ 経由にする（直接fetchは禁止）
- テストファイルは実装ファイルと同ディレクトリに置く

## コミットルール
- 動作確認済みのコードのみコミットする
- マイグレーションファイルは単体でコミットする

CLAUDE.mdの記述はモデルへの確率的な影響を与える。「絶対に守られる」保証はないが、大半のケースでモデルは従う。LintルールやCI設定（計算的センサー）と組み合わせて使う。

Sensorsの設計

計算的センサー（確定的・自動）

コード変更後に自動で走るLint・型チェック・テストは計算的センサーだ。Claude Codeのフックシステムで実装できる。

#!/bin/bash
# .claude/hooks/post-write.sh — PostToolUse フック
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

case "${FILE_PATH##*.}" in
  ts|tsx)
    # 型エラーをエージェントにフィードバック
    TYPE_RESULT=$(npx tsc --noEmit 2>&1)
    if [ -n "$TYPE_RESULT" ]; then
      jq -n --arg fb "$TYPE_RESULT" \
        '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":$fb}}'
    fi
    ;;
esac
PostToolUseフックの活用: エラーをフィードバックするとエージェントは次のツール呼び出し前に修正しようとする。「書く → Lintエラー → 修正 → 再確認」のループが自動化される。これが計算的センサーの最も効果的な使い方だ。

推論的センサー（確率的・高コスト）

AIレビューエージェントや人間のコードレビューが推論的センサーに当たる。計算的センサーが検出できない意味的な問題——過剰設計、ドメインロジックの誤り、セキュリティの論理的欠陥——を補う。

コストが高いため、CI後段や週次レビューなど、適切なタイミングに置くことが重要だ。

Context Rot——長期タスクで必ず直面する問題

Codex派が最も重視する問題のひとつがContext Rot（コンテキスト腐敗）だ。

Context Rotとは何か

ツール実行結果が積み重なるにつれ、コンテキストウィンドウは肥大化する。LLMの注意機構はウィンドウ内の後半部分に弱い——前半の指示が「薄れ」、古いコンテキストを無視した処理が増え始める。

flowchart LR subgraph Early["初期（良好）"] E1["指示 ✓"] --- E2["ツール実行 ✓"] --- E3["結果 ✓"] end subgraph Mid["中期（劣化）"] M1["指示 ✓"] --- M2["ツール×5 △"] --- M3["指示の一部を忘却"] end subgraph Late["後期（Context Rot）"] L1["指示 △"] --- L2["ツール×20 ✗"] --- L3["重複処理・矛盾"] end Early --> Mid --> Late style Late fill:#f8d7da style Mid fill:#fff3cd style Early fill:#d4edda

Context Rotの症状：

  • タスクが「完了した」と誤報告する
  • 以前に書いたコードと矛盾するコードを書く
  • 同じ処理を重複して実装する
  • 指示の細部を無視し始める

Context Rotの対策戦略

戦略1：外部アーティファクトへの記憶の外出し

コンテキスト内に長大な作業履歴を蓄積しない。代わりにAGENTS.mdやtodo.mdなどのファイルに状態を書き出し、次のセッションで読み込む。

Anthropicが推奨する「Initializer + Coding Agent」の二段構成はこの考え方の実装だ。InitializerがセッションごとのAGENTS.mdを生成し、Coding Agentが読み込んで継続する。

<!-- claude-progress.txt の例（セッション間で引き継ぐファイル） -->
## セッション2 終了時点（2026-04-25）

### 完了
- src/auth/login.ts — JWT認証実装済み、テスト全通過
- src/auth/middleware.ts — 認証ミドルウェア実装済み

### 次のセッションで着手
- [ ] src/users/profile.ts — ユーザープロフィールAPI
- [ ] メール確認フロー（POST /auth/verify-email）

### 既知の問題
- Refreshトークンのローテーションは Sprint 3 以降
- エラーメッセージのi18n未対応

戦略2：KVキャッシュの安定化

Anthropicの実測データによれば、プロンプトの先頭部分が安定しているとKVキャッシュが効き、トークンコストが最大10分の1になるケースがある。

動的な要素（タイムスタンプ、セッションIDなど）をプロンプトの先頭に置くと、毎回キャッシュが無効化される。CLAUDE.mdのような静的な文書を先頭に固定し、動的な要素は後半に置く構成がコスト面でも有利だ。

戦略3：セッション分割とHandoff

長期タスクを「スプリント」に分割し、スプリント境界でコンテキストをリセットする。前セクションのProgressファイルがHandoffドキュメントになる。

目安：1スプリントでのコンテキスト消費量は50〜60%以内に収めると品質が安定する。claude --verboseで使用率を観察しながら適切なスプリント粒度を見つける。

判断フロー——何から始めるか、何を使うか

ハーネスを設計するとき、最初に悩むのは「どこから手をつけるか」だ。以下の判断フローで整理できる。

flowchart TD START["エージェントを使い始めた"] --> Q1{"今、何が問題か？"} Q1 -->|"まだ失敗事例がない"| H["Hashimoto流でスタート
動かして失敗から学ぶ"] Q1 -->|"失敗パターンが溜まってきた"| Q2{"主な問題は？"} Q2 -->|"品質のばらつき"| F["Fowler流でGuides強化
AGENTS.md・スキル定義を整備"] Q2 -->|"バグの見落とし"| S["Fowler流でSensors強化
Lint・テスト・AIレビュー導入"] Q2 -->|"長期タスクで壊れる"| C["Codex流でスプリント設計
Context Rot対策・Handoff設計"] Q1 -->|"チームで使う"| T["Fowler流で全体設計
Guides/Sensors の役割分担を明文化"] H --> IMPROVE["実際の失敗を観察"] IMPROVE --> Q2 style START fill:#4A90D9,color:#fff style H fill:#7ED321,color:#fff style F fill:#BD10E0,color:#fff style S fill:#E74C3C,color:#fff style C fill:#F5A623 style T fill:#50E3C2

Guides vs Sensorsの設計バランス

どちらを先に強化すべきかは、今の問題によって変わる。

症状 推奨アクション
エージェントが意図しないファイルを変更する Guides強化：許可パスをsettings.jsonで明示
コードは動くが品質が低い Sensors強化：Lint・型チェックをフックに追加
最初は良いが長時間で劣化する Context Rot対策：外部アーティファクト設計
チームメンバーによって品質がばらつく Guides強化：AGENTS.mdのアーキテクチャ原則を充実
デプロイ後にバグが頻発する Sensors強化：E2EテストをCI後段に追加
同じ失敗が繰り返される Hashimoto流：失敗パターンをAGENTS.mdに追記
「まず最も単純な解決策から始め、失敗した部分にのみ複雑さを追加する」——これがAnthropicが推奨するハーネス設計の第一原則だ。Guides一枚のCLAUDE.mdから始め、問題が起きた箇所にSensors（フック）を追加する。最初から完璧な設計を目指すと、使われないハーネスができあがる。

Fowler論文が指摘する「未解決の課題」

ハーネスエンジニアリングの現在地を正確に把握するため、Fowlerが「まだ解けていない問題」として挙げる課題を紹介する。

1. ハーネスの一貫性維持

AGENTS.mdのルールが増えるにつれ、矛盾するルールが混在し始める。人間のコードベースと同様、ハーネス自体も「リファクタリング」が必要になる。しかしハーネスの品質をどう評価するかの方法論はまだ確立していない。

2. 行動レベルの信頼性

Lint（計算的センサー）が通った、型エラーが0になった——でも機能の動作が正しいかどうかは別問題だ。「仕様に対して正しく動く」という行動レベルの検証は、LLMベースのセンサー（確率的）に頼らざるを得ない部分が多く、信頼性が低い。

3. 矛盾する指示への対処

「コードはシンプルにしろ」と「テストカバレッジを100%にしろ」は場合によって矛盾する。人間なら文脈でバランスを取るが、エージェントは指示を字義通りに解釈しがちだ。ハーネスで「優先度の高いルール」を明示する方法が求められる。

4. Ashby’s Law問題

制御工学の「必要多様性の法則（Ashby’s Law）」によれば、制御者がシステムを制御するには同等の複雑性が必要だ。エージェントが複雑になるほど、それを制御するハーネスも複雑になる——理論的な限界だ。だからこそ「ハーネスを定期的にシンプル化する」という原則が重要になる。

モデルが賢くなるにつれ、以前は複雑なフィードバックループが必要だった処理が、シンプルな指示で解決できるようになる。ハーネスは育てながら削るもの、という意識を持つと長期的に維持しやすくなる。

ハーネスエンジニアリングとプロンプトエンジニアリングの違い

よく混同される概念との整理をしておく。

比較軸 プロンプトエンジニアリング ハーネスエンジニアリング
対象 単一のリクエスト・応答 エージェントの実行環境全体
スコープ リクエスト単位 セッション〜プロジェクト単位
永続性 都度変更 環境として固定・育てる
制御方法 自然言語による誘導（確率的） 外部制約＋フィードバックループ
典型的な成果物 プロンプトテンプレート AGENTS.md・Hooks・CI設定
主な解決問題 出力品質の向上 信頼性・再現性・安全性

プロンプトエンジニアリングは「何を言えばいい出力が出るか」を最適化する。ハーネスエンジニアリングは「エージェントが長期にわたって安全・確実に動ける環境を作る」ことを目的とする。

両者の関係: プロンプトはGuides（推論的）の一部に含まれる。ハーネスエンジニアリングの方が上位概念で、プロンプトエンジニアリングをその内側に包含する。Chawla派の「プロンプト⊂コンテキスト⊂ハーネス」という三重構造がこれを視覚化している。

Claude Codeでのハーネス設計の実践ロードマップ

具体的にClaude Code環境でハーネスを育てる順序を整理する。Claude Skillsを徹底解説で解説したスキルシステムも、ここで言うGuides（推論的）の一形態だ。

flowchart LR W1["Week 1
CLAUDE.md作成
（推論的ガイド初期化）"] --> W2["Week 2
Hooks追加
（計算的センサー）"] W2 --> W3["Week 3
スキル定義
（推論的ガイド充実）"] W3 --> W4["Week 4
ログ・可観測性
（センサーの記録化）"] W4 --> M2["Month 2
スプリント設計
（長期タスク対応）"] M2 --> M3["Month 3
ハーネスレビュー
（不要な複雑さを削る）"] style W1 fill:#d4edda style W2 fill:#d4edda style W3 fill:#fff3cd style W4 fill:#fff3cd style M2 fill:#f8d7da style M3 fill:#f8d7da

Month 3の「ハーネスレビュー」はよく忘れられるが重要なフェーズだ。Fowlerが指摘するように、モデルが賢くなると以前は必要だったHooksやルールが不要になる。定期的に「このSensorがまだ必要か」「このGuideはモデルが自然に守れるようになったか」を見直す。

まとめ——どの流派を使うか、より何を解くか

ハーネスエンジニアリングは定義が揺れている分野だが、各流派が解こうとしている問題は共通している：「AIエージェントを長期にわたって、安全に、再現性高く動かすための環境設計」だ。

定義を巡る論争より、手元の問題に最も効く考え方を選んで使う——これがkinopeeeの言う「言葉の定義より結果」の意味だ。

  • 今日から始めるなら Hashimoto流（失敗から学ぶ）
  • 品質を体系化するなら Fowler流（Guides/Sensors）
  • 本番に持っていくなら Codex流（プロダクション故障モード）

それぞれの流派は競合ではなく、成熟フェーズに応じた補完関係にある。ハーネスは設計して終わりではなく、エージェントと共に育て、モデルの進化に合わせて削ぎ落としていくものだ。

ハーネスの実装パターン（Generator-Evaluator、スプリント分解、Hooksセキュリティ）を詳しく知りたい場合は Claude Code Hooksガイド も参照してほしい。

参照ソース