ハーネスエンジニアリング入門：なぜCLAUDE.mdがエージェント制御の中核なのか

Posted at 2026-04-07

CLAUDE.mdを書いている人は、すでにハーネスエンジニアです

大げさに聞こえるかもしれません。
しかし、AIエージェントの行動規範をファイルに定義し、出力品質を構造で制御する行為は、まさにハーネスエンジニアリングそのものです。

2025年は「AIエージェント元年」でした。
Claude Code、Codex CLI、Devin、Cursor Agentが次々と登場し、AIが自律的にコードを書く世界が現実になりました。
2026年、パラダイムは次のフェーズに入っています。
エージェントを作る時代から、エージェントが動く基盤を設計する時代へ。

この記事では、ハーネスエンジニアリングとは何か、類似概念とどう違うのか、CLAUDE.mdの設計思想、そしてAnthropicが公式に推奨する2層構造までを解説します。

3つの概念を整理する：Context / Agentic / Harness

2025年後半から2026年にかけて、AI開発の進め方を表す概念が3つ登場しました。
混同されやすいため、まず区別を明確にします。

Context Engineering

Philipp Schmid（Google DeepMind、元Hugging Face）が提唱した概念です。
「モデルに何を見せるか」を設計する技術であり、限られたコンテキストウィンドウの中で、必要な情報をいかに効率的に取得・圧縮・配置するかに焦点を当てます。

Schmidはコンテキストウィンドウを「RAM」に例えています。
RAMが大きくても、載せるデータの質と順序が悪ければCPUは本来の性能を発揮できません。
Context Orderingの最適化だけでコスト4倍削減を達成した実例も報告されています。

Agentic Engineering

Andrej Karpathyが、自ら2025年2月に名付けた「Vibe Coding」の次として提唱しました。
「人間がコードを書く」のではなく「人間がエージェントを指揮する」への移行を説いています。

Karpathy本人の言葉を引用します。

"agentic" because the new default is that you are not writing the code directly 99% of the time, you are orchestrating agents who do.

出典：The New Stack - Vibe coding is passe

Agentic Engineeringの焦点は「人間の役割の変化」です。
アーキテクト・ガバナーとして、高レベルの目標・品質基準・ボトルネックを定義し、AIに実装を委ねます。

Harness Engineering

Mitchell Hashimoto（HashiCorp共同創業者）が2026年2月のブログ記事で「Engineer the Harness」と名付けました。
エージェントが間違いを犯すたびに、二度と同じ間違いを起こさないよう環境側を改修する実践です。

SchmidはこれをOS（オペレーティングシステム）に例えています。
モデルがCPU、コンテキストウィンドウがRAMなら、ハーネスはOS。
OSがプロセス管理やドライバを担うように、ハーネスはコンテキスト管理・ツール呼び出し・エラーハンドリングを担います。

なぜ区別が必要なのか

3つの概念は対立するものではなく、抽象度の異なるレイヤーです。

概念	焦点	設計対象	問い
Context Engineering	情報の質と配置	コンテキストウィンドウの中身	モデルに何を見せるか
Agentic Engineering	人間の役割転換	人間とエージェントの分業	人間は何をすべきか
Harness Engineering	環境・制約・基盤	エージェントが動く外側の仕組み	エージェントをどう囲むか

Context Engineeringはハーネスの「内側」の設計です。
Agentic Engineeringは開発プロセス全体のパラダイムです。
Harness Engineeringは、その両方を包含する「外側の基盤設計」です。

CLAUDE.mdにルールを書く行為は、Harness Engineeringそのものです。
コンテキストの配置を工夫するのはContext Engineering。
エージェントに仕事を委ねる判断をするのはAgentic Engineering。
3つを意識的に使い分けることで、エージェント制御の精度が上がります。

なぜ今ハーネスが必要なのか

エージェントの能力向上が制御の必要性を生む

補完ツール（Copilot等）の時代は、人間がコードを1行ずつ確認していました。
エージェント（Claude Code等）の時代は、数十ファイルを一気に変更します。
人間のレビュー能力が追いつかない規模の変更を、エージェントは数分で行います。

JetBrainsの2025年調査では、開発者の85%がAIツールを定常的に利用しています。
Claude Codeは8ヶ月でGitHub CopilotとCursorを抜き、AIコーディングツールの利用率トップに到達しました。
これだけの規模でエージェントが動いている以上、制御なしでは事故が起きます。

速さだけでは品質は保証されない

トランスコスモスのVibeOpsメソッドは、小規模ツール開発で工数87%削減を達成しました。
生産性の向上は実証されています。

しかし、品質面の課題も明らかになっています。
CodeRabbitが470件のオープンソースPRを分析した結果が参考になります。
470件のうちAI共著が320件、人間のみが150件。
AI共著PRの課題検出密度はPRあたり10.83件で、人間のみのPRの6.45件に対して約1.7倍でした。
90パーセンタイルではAI PRの課題数が26件に達し、人間のベースラインの2倍以上です。

Fortune誌の報道では、Cursor、GitHub Copilot、Google GeminiのAIコーディングツールに、プロンプトインジェクション攻撃の脆弱性が発見された事例も報告されています。

速く走れる馬も、手綱がなければ崖に向かって走ります。
制約を定義していない環境では、セッションごとに出力がぶれ、意図しないファイル変更や機密情報のコミットが頻発します。
エージェントが悪いのではなく、環境が悪いのです。

ハーネスの実証：モデルよりも環境が成果を決める

Morph社のSWE-bench分析が、ハーネスの価値を定量的に示しています。

同じモデル（Claude Opus）を使った場合、基本的なSWE-Agentスキャフォールドでは23%、250ターン最適化されたスキャフォールドでは45%以上のスコアを記録しました。
フロンティアモデル同士の比較では、ハーネス設計の違いでスコアが最大22ポイント変動した一方、モデルの入れ替えではわずか約1ポイントしか変わりませんでした。

「何を使うか」より「どう使わせるか」が成果を決めます。
これはベンチマークの話だけではありません。
日常の開発でも、CLAUDE.mdの有無がエージェントの出力品質を大きく左右します。

CLAUDE.mdの設計思想：なぜこのルールが必要になったか

CLAUDE.mdは単なる「ルールの羅列」ではありません。
それぞれのルールには、失敗から学んだ背景があります。
筆者のCLAUDE.mdから具体例を挙げて、設計思想を説明します。

「シンプル第一」を最初に置く理由

# 行動原則
- シンプル第一：変更をできる限りシンプルに。影響するコードを最小限にする
- 手を抜かない：根本原因を見つける。一時的な修正は避ける
- 影響を最小化する：変更は必要な箇所のみにとどめる

「シンプル第一」を筆頭に置いたのは、エージェントが過剰な変更を好む傾向に対処するためです。

ある日、「ログ出力のフォーマットを変えて」と頼んだところ、エージェントはログ出力だけでなく、ログ基盤ごとリファクタリングしました。
変更差分は300行を超え、レビューに1時間かかりました。
求めていたのは5行の修正です。

この経験から、行動原則の1行目に「シンプル第一」を置くようにしました。
エージェントはコンテキストの冒頭に書かれた指示を最も重視します。
最初の1行で「余計なことをするな」と伝えることが、過剰変更の最も効果的な抑止になります。

禁止事項がなぜ必要か

# 禁止事項
- クライアント名・契約内容・報酬金額等の機密情報を外部出力に含めない
- 重要な判断を独断で進めない。必ずユーザーに確認を取る

「やるべきこと」だけでは不十分です。
エージェントは「書いていないことはやっていい」と解釈します。

ある記事の下書きで、エージェントがクライアント名を具体的に挙げて成功事例を書いたことがありました。
内容は正確でしたが、NDAの観点で公開できません。
それ以降、禁止事項を明示するようにしました。

「やるべきこと」の列挙は方向性を示しますが、「やってはいけないこと」の明示は境界線を引きます。
特にセキュリティや機密性に関わる制約は、禁止事項として書く方が確実です。

コンテキスト圧迫時の安全弁

# コンテキスト圧迫時の行動規範（焦ったら止まれ）
- コードを読まずに書かない
- 検証を省略しない
- 中途半端に終わらせるなら止まる
- 焦りを自覚したら宣言する

これは最も後から追加されたルールですが、最も効果が高いルールです。

長時間の作業セッションでは、コンテキストウィンドウが逼迫します。
するとエージェントは、ファイルを読まずにコードを書いたり、テスト実行を省略したりします。
人間の「焦り」と同じ現象がエージェントにも起きるのです。

「焦ったら止まれ」のルールを追加してから、品質が突然崩れるセッションが激減しました。
「ここで一度区切ります」とエージェントが宣言し、現状をファイルに保存して次のセッションに引き継ぐ。
この行動を明示的に許可することが重要でした。

検証の義務化

「テストを書いてね」では不十分です。
筆者のCLAUDE.mdには「動作を証明できるまでタスクを完了とマークしない」と書いています。
コードを書いた時点ではなく、テストが通った時点を「完了」にした。
この1行で、テストスキップが消えました。

Anthropic公式：2層構造のハーネス設計

AnthropicはEffective Harnesses for Long-Running Agentsで、長時間稼働エージェントのハーネス設計を解説しています。
この記事の核心は「初期化エージェント」と「コーディングエージェント」の2層構造です。

単一エージェントの限界

長時間タスクでは、エージェントは複数のコンテキストウィンドウにまたがって作業します。
新しいセッションが始まるたびに記憶はゼロです。
単一エージェントだと、環境構築にコンテキストの大半を消費し、一度に多くの機能を実装しようとして品質が崩壊します。

初期化エージェント + コーディングエージェント

初期化エージェントは最初の1回だけ実行され、feature_list.json（200以上の機能を「failing」状態で列挙）、Gitリポジトリ、claude-progress.txt（進捗ログ）、init.sh（環境構築スクリプト）を作成します。
後続のコーディングエージェントは「今何をすべきか」だけに集中できます。

コーディングエージェントの動き方

コーディングエージェントは、新しいセッションが始まるたびに以下を行います。

claude-progress.txtとGit履歴から現在の作業状態を把握する
feature_list.jsonから次の「failing」機能を1つだけ選ぶ
実装する
テストを実行し、通ったら機能のステータスを「passing」に更新する
Gitにコミットし、進捗ログを更新する

「1つだけ選ぶ」が重要です。
Anthropicの検証では、エージェントに自由にやらせると一度に複数の機能を実装しようとし、品質が崩壊しました。
1機能ずつ進める制約を入れたことで、各セッションの成功率が大幅に向上しました。

エージェントにはセッション間の記憶がありません。
しかし、claude-progress.txtとGit履歴が「記憶」の代替になります。
進捗ファイルで作業状態を把握し、git revertで失敗を巻き戻す。
この仕組みが、コンテキストウィンドウの限界を補います。

ハーネス設計の失敗パターン

筆者が実際に経験した失敗パターンを紹介します。

制約が曖昧だと解釈がぶれる

「きれいなコードを書いて」と書いていた時期がありました。
あるセッションでは関数を細かく分割し、次のセッションでは1つの関数にまとめる。
「きれい」の解釈がセッションごとに変わるのです。

「関数は30行以内」「1ファイル1責務」のように定量的な制約に変えたところ、一貫性が生まれました。
曖昧な形容詞ではなく、測定可能な基準を書くことが重要です。

ツールが多すぎると迷う

MCPで20以上のツールを接続していた時期があります。
似た機能のツールが複数あると、毎回異なるツールを使い、出力が安定しません。
現在はベースのツールを必要最小限に絞り、CLAUDE.mdにツールの優先順位を明記しています。

検証なしの自己申告を信じてしまう

エージェントが「完了しました」と報告しても、テストを実行していないケースが頻発しました。
対策は、CLAUDE.mdでの検証義務化に加え、CIパイプラインでリンター・テスト・型チェックを自動実行する仕組みの導入です。
エージェントの自己申告ではなく、外部の検証結果で判断する。これが「ハーネス」の本質です。

ルールが多すぎて守れない

一時期、CLAUDE.mdが150行を超えたことがあります。
すると、優先度の低いルールが無視され始めました。
エージェントも人間と同じで、ルールが多すぎると取捨選択します。

現在は「行動原則3つ、禁止事項を明示、検証ルール1つ」を核にし、詳細はサブファイルに分離しています。
核となるルールは少なく、検証は仕組みで担保する。これが鉄則です。

ハーネスの3要素：CLAUDE.md / AGENTS.md / MCP

ハーネスは3つの要素で構成されます。

要素	役割	設計のポイント
CLAUDE.md	行動規範（エージェントの「憲法」）	ルールの背景にある「なぜ」を理解して設計する
AGENTS.md	チーム編成（マルチエージェントの役割分担）	1サブエージェントにつき1タスクに絞る
MCP	外部接続（使えるツール群の定義）	必要最小限のツールに絞り、優先順位を明記する

3つは独立して機能しますが、組み合わせたときに真価を発揮します。
CLAUDE.mdで「テストを必ず実行せよ」と書き、MCPでテスト実行ツールを提供し、AGENTS.mdでテスト専門のサブエージェントを定義する。
3層が揃って初めて、検証が構造的に保証されます。

まとめ：始め方

エージェントを作る時代は終わりつつあります。
2026年は、エージェントが動く基盤を設計する時代です。

Morph社の分析が示す通り、フロンティアモデルの性能差は僅少です。
成果を分けるのは、ハーネスの設計です。

まずはCLAUDE.mdを書くことから始めてみてください。

行動原則を3つ書く（1行目に最も重要な制約を置く）
禁止事項を書く（セキュリティ・機密性に関わるものは必須）
検証ルールを1つ書く（「完了」の定義を明確にする）

それだけで、エージェントの出力は変わります。
そしてエージェントが間違いを犯すたびに、その間違いを二度と起こさないルールをCLAUDE.mdに追加する。
この積み重ねが、あなただけのハーネスになります。

参考資料

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up