はじめに
本稿では、ハーネスエンジニアリングを、背景・定義・よく使われる構成・今後の展望の順に紹介します。あわせて、シンプルなハンズオンを通じて、最小限かつ本質的な内容をすばやく体感できる構成にしました。ハーネスエンジニアリングを初めて耳にする方を主な対象とした記事です。
背景 — なぜハーネスが必要になったのか
ここ数年、生成AIの影響力は目覚ましく拡大してきました。しかし、モデルの性能だけでは、望む結果を安定して得ることはできませんでした。ペルソナ指定や出力形式の調整、RAGなど、精度を高めるための工夫を重ねても、「生成」モデル特有の制約はなかなか解消されませんでした。代表的な手法であるプロンプトエンジニアリングやコンテキストエンジニアリングも、結局はモデルへの「お願い」にとどまっていたからです。特に長期タスクや複数セッションにまたがる作業では、大きな限界となってきました。
そこで登場したのがハーネスエンジニアリングです。ハーネス(harness)とはもともと馬具のことです。優れた馬を思い通りに走らせたいとき、馬(モデル)そのものではなく、馬を取り巻く馬具(構造)を整える ── そういう発想です。
定義 — 各社・各人によるハーネスの捉え方
ハーネスエンジニアリングは、モデルが正確な結果を出し続けられるよう、構造として仕組みをつくることです。
以下に、各社・各人から提示されてきたハーネスおよびハーネスエンジニアリングの定義をまとめます。
- Mitchell Hashimoto (My AI Adoption Journey, 2026.02): エージェントが失敗するたびに、同じ失敗が二度と起きないように環境をエンジニアリングすること。(「ハーネスエンジニアリング」という用語が本格的に使われるようになった出発点)
- Vivek Trivedy / LangChain (The Anatomy of an Agent Harness): エージェント = モデル + ハーネス。モデル以外のすべてがハーネスです。モデルが知能を担い、ハーネスがその知能を有用にします。
- Ryan Lopopolo / OpenAI (Harness engineering: leveraging Codex in an agent-first world, 2026.02): 環境、意図仕様、フィードバックループを設計する仕事。エンジニアの主業務が「コードを書くこと」から「環境を作ること」へ移りました。
- Anthropic Engineering Blog (Effective Harnesses for Long-Running Agents): ハーネスのすべての構成要素は、「モデルが単独でできない何か」を前提に作られます。モデルが進化すれば、その前提は古くなります。
- Martin Fowler (Harness Engineering, Birgitta Böckeler 著): ガイド・センサー・自己修正ループから構成される一貫したシステム。
原則 — 性能を分ける5つの要点
同じモデルを使っても、ハーネスの設計次第で性能は大きく変わります。LangChain はモデル(gpt-5.2-codex)を一切変更せず、ハーネスだけを改善することで Terminal Bench 2.0 のスコアを 52.8 から 66.5 へと引き上げました。モデルのバージョンアップを待たずとも、ハーネスの工夫だけで性能を伸ばせる ── これこそがハーネスエンジニアリングの実力です。
以下は、ハーネスを設計するうえで繰り返し強調されてきた原則です。
| # | 原則 | 一行説明 | 主な出典 |
|---|---|---|---|
| 1 | 目次型の指示ファイル管理 |
AGENTS.md / CLAUDE.md は百科事典ではなく主にマップとして機能。詳細は docs/ に分散して段階的に開示 |
OpenAI |
| 2 | 機械的な強制 | 「こうしてください」と頼まず、リンター・テスト・フックで検証を自動化し、強制力を持たせる | OpenAI / Fowler |
| 3 | 外部メモリ | AIが一度に記憶できる情報量は有限。Git など外部ストレージに状態を書き出し、セッション間で引き継ぐ | Anthropic |
| 4 | 評価者の分離 | 自己検証は楽観バイアスを持つ。作るAIと評価するAIを別々に分ける。さらに「テストが通った証拠」が出せない限り、デフォルトは「失敗」とみなす | Anthropic |
| 5 | フィードバックループ | AIが失敗するたびに、その原因を指示ファイルなど環境に1行追記し、同じ失敗を二度起こさないようにする | Hashimoto / OpenAI |
指示ファイル(AGENTS.md / CLAUDE.md)とは
プロジェクトのルートに置く Markdown ファイルで、「このプロジェクトは何か」「どんなルールを守るか」「ビルド・テストのコマンドは何か」を人間が読める文章で書いた指示書です。AI エージェントは起動のたびに自動で読み込むため、毎回プロンプトで説明し直さなくても、書かれた内容を前提に動きます。
ファイル名はツールごとに分かれます:
-
AGENTS.md— Codex、Cursor、GitHub Copilot、Gemini CLI など多くのツールが対応するオープン標準(Linux Foundation 傘下)。 -
CLAUDE.md— Claude Code 専用(現時点でAGENTS.mdには未対応)。
役割はどちらも同じ ── 「セッションごとに自動で読まれる指示書」です。
要するにモデルに頼むのではなく、別の道に行けない環境を作る。そしてその環境が自己改善する仕組みを仕込むことです。
実践 — 30分でMVHを敷く
これは核心的な原則を含んだ最小限のハンズオンです。つまり、MVH(Minimum Viable Harness) というハーネスの最小構成です。短時間で構築可能であり、実際に一度構築してみることで、その原理を体感できます。
MVH の目的は、「お願い」を「仕組み」に置き換えることです。
頼まなくても環境が自動で動く状態を作ります。必要なのは次の3点です。
-
指示ファイル(
CLAUDE.md) — エージェントが毎セッション自動で読む、ルール・禁止事項・コマンドの早見表 - 完了の客観的定義 — 「完了」を人間の主観ではなく、テストの緑/赤で判定する
- 自動検証フック — 決まったタイミングでチェックを強制実行する仕掛け
この3点が揃った瞬間から、エージェントは「自分で間違いに気づいて、自分で直す」状態になります。
ここでは Claude Code を例に進めます。
準備(3分)
-
Node.js 18 以上(
node --versionで確認) - Claude Code をインストール(macOS / Linux / WSL):
curl -fsSL https://claude.ai/install.sh | bash
Windows は 公式インストール手順 を参照。以降の作業はすべてプロジェクトのルートディレクトリで行います。
ステップ① 指示ファイル CLAUDE.md を作る(5分)
エージェントに毎回伝えていたルール・コマンド・禁止事項をまとめた指示ファイルを作成します。Claude Code は CLAUDE.md をセッション開始のたびに自動で読み込むよう設定されているため、ここに書いた内容は毎回自動的に適用されます。プロジェクトのルートに作り、以下を貼り付けます。
# プロジェクト名
一文でアイデンティティ(例:社内向けコミュニケーションツール)
## ビルドとテスト
- ビルド: `npm run build`
- テスト: `npm test`
- リント: `npm run lint`
## コーディングルール
- ロギングは structured logging のみ(`console.log` 禁止)
- ファイルは300行以下
## 繰り返された失敗(やってはいけないこと)
- ❌ 失敗したテストを削除しない
- ❌ catch ブロックを空のままにしない
## 完了前の検証
変更後は必ず: `npm test && npm run lint && npm run typecheck`
各セクションの役割は次の通りです。
| セクション | 役割 |
|---|---|
| 冒頭の一文 | このプロジェクトが何なのかを一言で伝える。AIが最初に読んで「何を作っているのか」を理解できるようにする |
## ビルドとテスト |
このプロジェクトでよく使うコマンドをまとめておく。AIが間違ったコマンドを使わなくなる |
## コーディングルール |
AIが新しいコードを書くときに守るべきルール。スタイルや禁止事項など |
## 繰り返された失敗 |
これまでにAIがやらかしたミスを残しておく。次から同じミスをしないようにするためのメモ |
## 完了前の検証 |
「終わりました」と言う前に必ず実行するチェック手順。動作確認せずに完了報告するのを防ぐ |
ステップ② テストを1つ用意する(2分)
テストとは? — 「このコードはちゃんと動いてる?」を人間の代わりに自動で確かめてくれる小さなプログラムのことです。
このステップではまず、1 + 1 は 2 になる? を確かめるだけの最小のテストを1つ置きます。
やること
ターミナルに以下をコピーして貼り付け、Enterを押してください。
① テスト用フォルダを作る
mkdir -p __tests__
なぜ
__tests__という名前?
テストを実行するツール(Jest)が「このフォルダの中身はテストだよ」と自動で認識してくれる、決まった名前だからです。
② テストファイルを1つ作る
cat > __tests__/sanity.test.js << 'EOF'
test('1 + 1 = 2', () => {
expect(1 + 1).toBe(2);
});
EOF
なぜ
1 + 1なのか?
指示ファイルに「npm test を完了前に必ず実行」と書いた以上、テストが1つも無いと仕組みが回らないため、ダミーを置いただけです。実際の開発では、機能を追加するたびにエージェントがその機能に対応する本物のテストを書いていきます。本物が増えたら、このダミーは削除して構いません。
③ 動作確認
次のコマンドを実行します。
npm test
ターミナルに緑色の PASS(=成功の意味)が表示されればOKです。
ステップ③ 自動検証フックを仕込む(15分)
フックとは? — 「ある出来事が起きたら、自動でコマンドを走らせる」仕組みです。エージェントの「気をつけます」に期待するのではなく、環境の側で強制的にチェックをかけるのが目的です。
仕掛けるタイミングは2つです。
| タイミング | 走らせるもの | 何を防ぐか |
|---|---|---|
| ファイルを編集した直後 | リント自動修正 + 型チェック | ルール違反や型エラーをそのまま残すこと |
| 返事を返す直前 | テスト全体 | 壊れたまま「完了」と宣言すること |
エラー時の処理の流れ
フックが動いた結果は、次の流れでエージェントに戻ります。
- フックを実行 → 標準出力・標準エラー(画面に出るメッセージ)を取得
- その内容を、エージェントが次の応答を組み立てるときに読む入力(=コンテキスト)に自動で追加する
- exit code(コマンドの終了コード。
0= 成功、それ以外 = 失敗)を確認0以外なら → エージェントのターンを終わらせず、修正作業を続けさせるつまり「エラー文をエージェントに見せる」+「失敗なら止まらせない」の2つで、自己修復ループが回ります。
やること
① 設定フォルダと設定ファイルを作る
Claude Code は、プロジェクト直下の .claude/settings.json を起動時に自動で読み込みます。場所と名前は固定なので、この通りに作ります。
mkdir -p .claude
touch .claude/settings.json
このフォルダとファイルの正体
.claude/… 先頭にドット(.)が付く「設定用の隠しフォルダ」という慣習。Claude Code はこの名前のフォルダを自動で探しに行きます。settings.json… Claude Code の振る舞いを定義する設定ファイル本体。「いつ、何を、自動で走らせるか」をここに書いておけば、起動時に自動で読み込んでフックを仕掛けてくれます。
② 設定ファイルに以下を貼り付ける
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{ "type": "command", "command": "npm run lint:fix && npm run typecheck" }
]
}
],
"Stop": [
{
"hooks": [
{ "type": "command", "command": "npm test" }
]
}
]
}
}
設定ファイルの構造
全体は「hooksの中に、イベント名ごとに走らせるコマンドを並べる」という構造です。PostToolUseとStopは Claude Code が定義しているイベント名で、この名前で書くと該当タイミングで自動的に発火します(自由に命名できるわけではありません)。
PostToolUse— エージェントがツール(ファイル編集や書き込み)を使い終わった直後に発火。
matcher: "Write|Edit"… 「Write または Edit ツールを使ったときだけ」と反応条件を絞る。これがないと、ファイルを読んだだけでもリントが走ってしまいます。command: "npm run lint:fix && npm run typecheck"… リント自動修正 → 型チェックの順に実行(&&は「前が成功したら次へ」)。
Stop— エージェントが応答を終えようとする直前に必ず発火。
command: "npm test"… 最後の関門として全テストを実行。落ちていれば「完了」を許さず、エージェントは修正作業に戻ります。役割分担:
PostToolUseは編集ごとに細かく /Stopはターンの最後に1回だけ ── これで漏れと重複の両方を防ぎます。
動作確認 — お願いではなく、仕組みを作る(5分)
Claude Code で小さな実装を頼んでみます(例:「送信ボタンの色を青に変えて」)。以前と違う2つの動作が見えるはずです。
-
ファイルを編集した直後 —
PostToolUseフックが走り、エージェントが自分でリント/型エラーを見つけて、自分で直し始めます。 -
「完了しました」の直前 —
Stopフックが走り、全テストが自動実行されます。失敗すると応答が止まり、エージェントが作業をやり直します。
毎回プロンプトで頼んでいた検証作業が、環境に組み込まれた強制に置き換わりました。これが「環境を設計する」ことの具体的な手触りです。
完成したらこの3つが手元にある
| ファイル | 役割 |
|---|---|
CLAUDE.md(指示ファイル) |
ルールと禁止事項の目次 |
| テストスイート(緑) | 「完了した」と言える条件を、人間の感覚ではなくテストの合否で決める |
.claude/settings.json |
編集後の自動検証 + 完了前の全テスト実行 |
この3点セットが MVH ── ハーネスの土台です。あとは失敗が繰り返される領域から、1フォルダずつ・1ルールずつ育てていきます。最初から完璧を目指す必要はありません。
構造 — 本格的なハーネスの形(参考)
MVH が安定して動き出すと、ハーネスは自然と大きな構造へと育っていきます。下記は OpenAI Codex チームが100万行のコードベースで使う実際の構造 です。
AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│ ├── index.md
│ ├── core-beliefs.md
│ └── ...
├── exec-plans/
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/
│ └── db-schema.md
├── product-specs/
│ ├── index.md
│ ├── new-user-onboarding.md
│ └── ...
├── references/
│ ├── design-system-reference-llms.txt
│ ├── nixpacks-llms.txt
│ ├── uv-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md
要点だけ押さえます。何を読ませ、何を読ませず、何を触らせないかを、フォルダ構造で制御しています。
-
AGENTS.mdは目次に徹する — 詳細は別ファイルに分けてリンクだけ置く。最初に全文を読ませないことで、エージェントの作業メモリを軽く保つ。 -
core-beliefs.mdで判断基準を一元化 — 「迷ったらこのファイルを見る」と決めておく。判断のものさしをチームと環境で1つ（Single Source of Truth）に揃える。 -
exec-plans/の active → completed — 進行中の計画をactive/に置き、完了したらcompleted/に移して残す。過去の判断を再利用できるようにする。(*exec-plans/は、エージェントが実行する計画書をまとめておくフォルダです。) -
references/*-llms.txtで知識を事前配置 — 必要な外部ドキュメントをLLMが読みやすい平文テキストであらかじめリポジトリ内に置く。Web検索に行かなくても、その場で参照できる。 -
tech-debt-tracker.md定期実行エージェントで負債を継続回収 — 「あとで直す」課題を専用ファイルに記録。バックグラウンドで動く別エージェントが定期的にスキャンし、自動で修正PRを出し続ける。継続的なガベージコレクションとして運用する。
こうした構造は、最初から完成形を狙うものではありません。同じ失敗が繰り返されたタイミングで、ハーネスに1行だけ手を入れて構造的な防止策を仕込む ── これを1つずつ積み重ねていくことで、同じ失敗は機械的に起こせなくなっていきます。
展望
モデル性能の向上はプロバイダー側の領域ですが、ハーネスエンジニアリングはユーザー側で主体的に取り組める領域です。ハーネスをうまく組むことで、モデルのバージョンアップ以上の性能向上が実現できることも実証されています。
ハーネスエンジニアリングは、人間の関与そのものをボトルネックと捉え、レビュー・判断・承認といった工程を構造で削減することで、プロセス改善など時間面での効率も高めています。
ハーネスエンジニアリングは、たとえ将来「○○○エンジニアリング」と呼び名が変わったとしても、この方向性自体は発展を続け、多くの業種・産業でさまざまな形で採用されていくと予想されます。ハーネスエンジニアリングがもたらす便益とコスト効率は明確であり、人々はこれからもエージェントが「望み通りに動く」ことを求め続けるからです。
個人と企業それぞれに、求められる備えがあります。
- エンジニア — コードがタダになる(code is free)流れの中で、環境・制約・構造を設計する人へシフトしていく必要があります。
- 企業 — 10倍以上の生産性向上が検証された手法です。競争力としてどう取り入れるか、検討が求められます。
参考文献
- Mitchell Hashimoto, My AI Adoption Journey — この用語が初めて登場した記事
- Ryan Lopopolo / OpenAI, Harness engineering: leveraging Codex in an agent-first world — 100万LOC での実験レポート / YouTube: Harness Engineering: How to Build Software When Humans Steer, Agents Execute
- Anthropic, Effective Harnesses for Long-Running Agents — 2エージェントパターンの原典
- Anthropic, Harness Design for Long-Running Application Development — 3エージェント版の続編
- Vivek Trivedy / LangChain, The Anatomy of an Agent Harness — 「Agent = Model + Harness」の定式化
- Birgitta Böckeler (martinfowler.com), Harness Engineering — ガイド・センサー・自己修正のフレームワーク