ハーネスエンジニアリングとは、AI コーディングエージェントの外側に指示ファイル・権限・hooks・テスト・CI などの仕組みを作り、同じ失敗を繰り返させない考え方です。ガイドとセンサーで整理した全体像と設計の原則、AGENTS.md・check.sh・Stop フック・CI の最小構成をリポジトリに置く手順を、Claude Code で実際に動かした結果つきで紹介します。
SNSでシェアして、他のエンジニアにも教えてあげましょう
ハーネスエンジニアリングとは、AI コーディングエージェントを「モデルの外側の仕組み」で使いこなす考え方です。仕組み（ハーネス）には、指示ファイル・ツール・権限・hooks・テスト・CI・評価などがあります。エージェントが失敗したら、プロンプトを書き直すのではなく、二度と同じ失敗をしないように仕組みを足します。この言葉は 2026 年 2 月に OpenAI の Codex チームのブログで広まり、Martin Fowler のサイトや GitHub の公式ブログでも使われるようになりました123。この記事では、ハーネスの全体像を「ガイド」と「センサー」で整理し、設計の原則を 6 つにまとめます。そのうえで、AGENTS.md・チェック用スクリプト・Stop フック・CI という最小構成をリポジトリに置く手順を、Claude Code で実際に動かした結果つきで紹介します。製品の仕様は 2026 年 10 月時点のものです。
ハーネス（harness）は、もともと馬具のことです。力の強い馬に馬具を付けて、狙った方向に引かせます。AI エージェントでは、モデルが馬、ハーネスがそれを操る道具一式にあたります。
Thoughtworks の Birgitta Böckeler は、Martin Fowler のサイトでこの言葉を次のように整理しています2。
つまり「ハーネス」には 2 つの層があります。1 つは Claude Code・Codex CLI・GitHub Copilot などの製品そのものです。ツールの実行やコンテキストの管理、サブエージェントへの委任を受け持ちます。もう 1 つは、チームがリポジトリに置く指示ファイル・テスト・hooks・CI です。ハーネスエンジニアリングは、主に後者を設計して育てる仕事です。
「ハーネスエンジニアリング」という言葉は、2026 年 2 月に相次いで使われ始めました。
| 時期 | 発信元 | 内容 |
|---|---|---|
| 2025 年 11 月 | Anthropic | 長時間動くエージェントのためのハーネスを公開4 |
| 2026 年 2 月 5 日 | Mitchell Hashimoto | AI 活用の段階の 1 つに「Engineer the Harness」を挙げる5 |
| 2026 年 2 月 11 日 | OpenAI | 「Harness engineering」で Codex だけで製品を作った実験を報告1 |
| 2026 年 4 月 2 日 | Martin Fowler のサイト | ガイドとセンサーによる整理を公開2 |
| 2026 年 6〜8 月 | GitHub | Copilot の「agentic harness」の評価と一般提供67 |
Terraform の作者である Hashimoto は、エージェントが間違えるたびに、二度と間違えないよう手を打つことを「harness engineering」と呼びました5。手段は 2 つです。AGENTS.md に注意書きを足すことと、スクリーンショットや絞り込んだテストを実行するスクリプトを用意することです。
OpenAI の記事では、少人数のチームが 5 か月かけて社内向けのベータ製品を作りました。手で書いたソースコードは無く、約 100 万行を Codex が書いています18。人は環境を設計し、意図を伝え、フィードバックの仕組みを作る側に回りました。
3 つは対象の広さが違います。
InfoQ の記事は、Fowler の言葉として、ハーネスにはコンテキストエンジニアリング・アーキテクチャの制約・ガベージコレクション（古くなった資料やコードの掃除）が含まれると紹介しています8。
AI エージェントへの関心が続くなかで、「ハーネス エンジニアリング」という検索が増えています。Google トレンド（日本・過去 90 日、2026-10-20 取得）では、「AI エージェント」の急上昇の関連キーワードに「ハーネス エンジニアリング」が +60% で入っていました9。直近 4 週の「AI エージェント」の検索量は、基準にした GitHub Copilot の約 2.1 倍です。
| 週 | AI エージェント | GitHub Copilot |
|---|---|---|
| 07/21 | 41 | 27 |
| 07/28 | 39 | 27 |
| 08/04 | 37 | 25 |
| 08/11 | 29 | 15 |
| 08/18 | 43 | 24 |
| 08/25 | 48 | 23 |
| 09/01 | 39 | 30 |
| 09/08 | 42 | 23 |
| 09/15 | 33 | 15 |
| 09/22 | 37 | 14 |
| 09/29 | 43 | 23 |
| 10/06 | 38 | 19 |
| 10/13 | 43 | 22 |
ほかの語の急上昇にも「harness」が並んでいます91011。
| 調べた語 | 急上昇の関連キーワード | 伸び |
|---|---|---|
| AI エージェント | ハーネス エンジニアリング | +60% |
| GitHub Copilot | github copilot harness | +110% |
| Cursor | deepseek harness | +4,850% |
| DeepSeek | deepseek harness 插件 | 急激増加 |
背景には、製品の側が自分の中核を「ハーネス」と呼び始めたことがあります。
dsh）です。「すべてがプラグイン」という設計で、MIT ライセンス、2026 年 10 月時点では developer preview です12もう 1 つの理由は、モデルの差よりハーネスの差が目立ってきたことです。GitHub は 2026 年 6 月、20 以上のモデルに対応する Copilot CLI のハーネスを、モデル提供元のハーネス（Claude Code・Codex CLI）と比べた結果を公開しました。タスクの解決率はほぼ同じで、多くの組み合わせで Copilot CLI のほうが使うトークンが少なかったと報告しています6。同じモデルでも、ハーネス次第で結果とコストが変わるということです。
ハーネスの部品は、ガイド（動く前に方向を示す）とセンサー（動いた後に結果を見て直させる）の 2 種類に分けると設計しやすくなります2。
Böckeler は、ガイドだけだとルールが効いたかどうか分からず、センサーだけだと同じ間違いを何度も繰り返す、と指摘しています2。両方をそろえるのが基本です。
センサーはさらに 2 つに分かれます。
部品ごとの詳しい作り方は、それぞれの記事にまとめています。
.github/。書き方は CLAUDE.md の書き方：AGENTS.md との違いと併用方法permissions、Codex の sandbox_mode と approval_policy。設定は AI エージェントの情報漏洩対策scripts/ のように、1 つの入口にまとめる部品がそろうと、次のようなループができます。ガイドで方向を示し、センサーで結果を確かめ、失敗をエージェントに返します。人は最後のレビューと、ハーネス自体の改善に時間を使います。
一次情報で繰り返し出てくる考え方を、6 つの原則にまとめます。
同じ失敗が 2 回起きたら、ガイドかセンサーを足します25。Claude Code の公式ドキュメントも、CLAUDE.md に書き足すタイミングとして「同じ間違いを 2 回したとき」「レビューで指摘されたとき」を挙げています13。チャットで同じ注意を繰り返しているなら、それはハーネスに入れるべき内容です。
指示ファイルを長くすると、かえって守られなくなります。Claude Code のドキュメントは、CLAUDE.md を 1 ファイル 200 行未満にするよう勧めています13。Codex は AGENTS.md の合計が project_doc_max_bytes（既定 32 KiB）に達すると、それ以上のファイルを読み込みません14。
OpenAI のチームは、構造化した docs ディレクトリ（設計資料や実行計画）をエージェントにとっての「信頼できる唯一の情報源」にしました8。AGENTS.md にはコマンドと守ることと「どこに何があるか」だけを書き、詳しい内容は docs に分けます。
指示ファイルは、エージェントにとって守るべき文脈であって、強制される設定ではありません。Claude Code のドキュメントも、CLAUDE.md は「強制される設定ではなく文脈」として扱われ、確実に止めたい操作は hooks で止めるよう書いています13。
後で紹介する実験では、ユーザーが「書いたらすぐ終えて」と頼むと、エージェントはテストを回さずに終えようとしました。それでも Stop フックがテストを回し、失敗を返したことで、エージェントは自分で直しました。必ず守らせたいことは、hooks・権限・CI に入れます。
テストや lint のような計算型センサーは、変更のたびに回します。AI レビューのような推論型センサーは、意味を判断する必要があるところに絞ります2。速いチェックはコミット前に、時間のかかるチェックは CI に置く、という分け方です。センサーの出力は、エージェントが読んで直せる短さにします。
Anthropic は、エージェントに自分の成果を評価させると、質が低くても褒めてしまう傾向があると報告しています15。そこで、計画・実装・評価を別のエージェントに分けました。評価役は Playwright で動いているアプリを実際に操作し、基準に届かなければ理由をつけて差し戻します。小さなチームでは、テストと CI を「判定役」にし、AI レビューを別のモデルや別のエージェントに任せるところから始められます。
ハーネスの部品は、それぞれ「モデルが自分ではできないこと」を補う前提で作られています15。モデルが良くなればその前提は古くなるので、効かなくなった部品は外します。Anthropic は「できるだけ簡単な方法から始め、必要なときだけ複雑にする」という考え方を引いています15。
ここからは、どのエージェントでも使える最小のハーネスを、小さな Node.js のリポジトリに置く手順です。置くファイルは次の 6 つです。
my-app/
├── AGENTS.md # 地図（どのエージェントも読む）
├── CLAUDE.md # Claude Code 用（AGENTS.md を読み込む）
├── docs/rounding.md # 詳しいルール（例: 端数処理）
├── scripts/check.sh # 「完了」の定義。エージェントと CI が同じものを回す
├── .claude/
│ ├── settings.json # 権限と hooks
│ └── hooks/stop-check.sh # 終わる前に check.sh を通す
└── .github/workflows/check.yml # CI でも同じ check.sh を回す
前提: macOS か Linux、Node.js 22 以降、jq。動作は 2026 年 10 月 20 日に Claude Code 2.1.304・Node.js 24.6.0 で確かめました。
最初に、エージェントにとっての「完了」を 1 本のスクリプトにまとめます。人・エージェント・CI が同じ入口を使うので、「テストは通ったと言っていたのに CI で落ちた」というずれが減ります。
#!/usr/bin/env bash
# エージェントと CI が同じ入口で品質を確かめるスクリプト
set -uo pipefail
cd "$(dirname "$0")/.."
fail=0
run() {
local name=$1; shift
if out=$("$@" 2>&1); then
echo "ok $name"
else
echo "FAIL $name"
echo "$out" | tail -n 30
fail=1
fi
}
run "syntax" bash -c 'for f in src/*.js test/*.js; do node --check "$f" || exit 1; done'
run "test" node --test
exit $fail
ポイントは 2 つです。成功したチェックは 1 行だけ出し、失敗したチェックは末尾 30 行だけ出します。エージェントのコンテキストを無駄に使わず、直すのに必要な情報だけを返すためです。実際のプロジェクトでは、run の行を lint・型チェック・テストのコマンドに置き換えます。
chmod +x scripts/check.sh
bash scripts/check.sh
ok syntax
ok test
AGENTS.md には、コマンド・守ること・資料の場所だけを書きます。
# AGENTS.md
## このリポジトリ
- 税込み価格を計算する小さなライブラリ。コードは `src/`、テストは `test/`
- Node.js 22 以降。外部パッケージは使わない
## コマンド
- 確認: `bash scripts/check.sh`（構文チェックとテスト。CI も同じものを実行する）
## 守ること
- 作業の最後に `bash scripts/check.sh` を通す。失敗したまま終えない
- テストを消したり、期待値を書き換えて通したりしない。仕様が違うと思ったら理由を書いて相談する
- 金額は円の整数で扱う。端数の処理は `docs/rounding.md` に従う
## 詳しい資料
- `docs/rounding.md`: 端数処理のルール
Claude Code 用の CLAUDE.md は、@AGENTS.md で中身を読み込み、その下に Claude Code だけの指示を足します13。
@AGENTS.md
## Claude Code
- `src/` を大きく変えるときは、先に plan モードで方針を示す
Claude Code は v2.1.277 以降、CLAUDE.md が無ければ AGENTS.md をそのまま読みます。ただし CLAUDE.md（CLAUDE.local.md を含む）があると、既定では AGENTS.md を読みません13。CLAUDE.md も置くなら、上のように import しておくのが確実です。
.claude/ はリポジトリに入れてチームで共有する設定です16。チェック用スクリプトの実行は許可し、.env は読ませないようにします。
{
"permissions": {
"allow": [
"Bash(bash scripts/check.sh)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
}
}
Codex では、ユーザー設定の config.toml で sandbox_mode = "workspace-write" と approval_policy = "on-request" を組み合わせると、作業フォルダの中は自由に編集し、外に出るときだけ承認を求める動きになります17。秘密情報の扱いを含めた設定は AI エージェントの情報漏洩対策 にまとめています。
AGENTS.md の「作業の最後に check.sh を通す」は、あくまでお願いです。これを強制するのが Stop フックです。Stop フックは、エージェントが応答を終えようとしたときに動きます。終了コード 2 で終わると終了が止まり、標準エラーの内容が理由としてエージェントに渡されます18。
.claude/:
#!/usr/bin/env bash
# Stop フック: scripts/check.sh が通るまで作業を終えさせない
input=$(cat)
# すでに Stop フックで続行中なら止めない（無限ループを防ぐ）
if [ "$(printf '%s' "$input" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0
fi
cd "$(dirname "$0")/../.."
if ! out=$(bash scripts/check.sh 2>&1); then
{
echo "scripts/check.sh が失敗しています。原因を直してから終えてください。"
echo "$out"
} >&2
exit 2
fi
exit 0
stop_hook_active は、Stop フックによってすでに作業を続けているときに true になる項目です18。ここで止めないと、直せない失敗のときに同じやり取りが続いてしまいます。
手順 3 の .claude/ に hooks を足します。${CLAUDE_PROJECT_DIR} はセッションを始めたプロジェクトのルートです18。
{
"permissions": {
"allow": [
"Bash(bash scripts/check.sh)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
},
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/stop-check.sh"
}
]
}
]
}
}
chmod +x .claude/hooks/stop-check.sh
ファイルを編集するたびに lint をかける PostToolUse のような使い方は、Claude Code hooks 入門 で紹介しています。
hooks は手元の Claude Code でしか動きません。Codex や Copilot が作った変更、人が書いた変更も同じ基準で確かめるため、CI でも同じスクリプトを回します。
.github/:
name: check
on:
pull_request:
push:
branches: [main]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: bash scripts/check.sh
ブランチ保護でこのジョブを必須にすれば、どのエージェントが作った PR でも、チェックが通らない限りマージできなくなります。
このリポジトリに、軽減税率（8%）は 1 円未満を切り捨てる、というテストを先に置きました。withReducedTax(1007) は 1087 になるのが正解です。そのうえで Claude Code に関数の追加を頼み、2 つの条件で結果を比べました。
docs/ と AGENTS.md の案内がある）: エージェントは最初に docs を読み、切り捨てで実装しました。check.sh を自分で回して終えています1088 !== 1087 を返しました。エージェントはテストを読んで切り捨てに直し、check.sh が通ってから終えました
ガイドは 1 回目の正答率を上げ、センサーは間違いを確実に捕まえます。片方だけでは足りない、という Böckeler の指摘どおりの結果です2。
チームで複数のエージェントを使うなら、ハーネスの中心は AGENTS.md と check.sh と CI に置くのがおすすめです。どのエージェントも読める・回せるからです。
| ツール | 指示ファイル | 主な強制の手段 |
|---|---|---|
| Claude Code | CLAUDE.md か AGENTS.md | hooks・permissions |
| Codex | AGENTS.md | sandbox・承認ポリシー |
| GitHub Copilot | AGENTS.md など | CI・ブランチ保護 |
AGENTS.override.md があればそちら）を上から順につなげて読みます。作業フォルダに近いファイルほど後ろに入り、優先されます14.github/ に書きます19@AGENTS.md で読み込みます13ツールごとの違い（Claude Code の hooks、Codex のサンドボックス）は、それぞれの設定に足していきます。2 つの CLI の違いは Codex CLI と Claude Code の比較 で比べています。
失敗のたびに書き足すと、AGENTS.md はすぐ長くなります。一部のフォルダにしか関係しないルールはそのフォルダの AGENTS.md へ、手順はスキルへ、詳しい説明は docs へ移します13。Codex は合計 32 KiB を超えると読み込みをやめるので、長いファイルは後ろが読まれていないことがあります14。
筆者の環境（Claude Code 2.1.304）では、一度も信頼していないフォルダで claude -p を実行すると、.claude/ の permissions.allow が無視されました。「this workspace has not been trusted」という警告が出ます。一方、同じファイルの Stop フックは動きました。新しく clone したリポジトリでは、一度対話モードで Claude Code を開き、信頼の確認を済ませてください。
直せない失敗（ネットワークが必要なテストなど）があると、Stop フックは何度も終了を止めます。stop_hook_active を見て 2 回目は通すようにしてください。Claude Code にも、続けて 8 回止めると次は止めずに終える上限があります18。
センサーが厳しいと、エージェントがテストの期待値を変えて通すことがあります。AGENTS.md で禁止したうえで、テストファイルの変更は PR で人が必ず見るようにします。Anthropic は、機能の一覧を Markdown ではなく JSON で管理しました。モデルが JSON のほうを勝手に書き換えにくかったためです4。
.claude/ の hooks は、リポジトリを開いた人の権限でシェルコマンドを実行します。hooks のスクリプトの変更は、普通のコード以上に慎重にレビューしてください。
最初から評価エージェントや複雑なワークフローを作る必要はありません。check.sh・AGENTS.md・CI から始め、失敗が起きた場所に部品を足します。モデルを変えたときは、効かなくなった部品を外します15。
AGENTS.md・scripts/・Stop フック・CI の 4 つ。どのエージェントでも使い回せるscripts/ を作り、エージェントが次に失敗したとき、その原因をガイドかセンサーに 1 つ足すAI エージェントを使いこなすために、モデルの外側の仕組みを作ることです。指示ファイル、使えるツール、権限、hooks、テスト、CI、評価の仕組みなどがあります。エージェントが失敗したら、その都度プロンプトを直すのではなく、二度と同じ失敗が起きないように仕組みを足していきます。
GitHub Copilot のエージェント機能を動かしている共通の基盤のことです。GitHub は、Copilot CLI・Copilot アプリ・Copilot コードレビューが同じ「agentic harness」で動き、ツール・コンテキスト・作業の流れをまとめて受け持つと説明しています6。2026 年 8 月には JetBrains 版でも一般提供になりました7。この記事で作る「チームのハーネス」は、その外側に足す層です。
DeepSeek AI がオープンソースで公開しているエージェントハーネス（dsh）です。モデルではなく、モデルを動かす側の仕組みです。MIT ライセンスで、2026 年 10 月時点では互換性のない変更が入りうる developer preview です。npx @deepseek-ai/ で Web UI を起動できます12。
必要です。ただし大きく作る必要はありません。scripts/ と短い AGENTS.md だけでも、「テストを回さずに終える」「間違ったコマンドを使う」といった失敗の多くを防げます。CI と Stop フックは、エージェントに任せる作業が増えてから足しても間に合います。
AGENTS.md と scripts/ と CI です。3 つのツールはいずれも AGENTS.md を読めるので、ルールを 1 か所にまとめられます141319。チェックは CI で回せば、どのツールで作った変更も同じ基準で確かめられます。
Harness engineering: leveraging Codex in an agent-first world — OpenAI（Ryan Lopopolo）, 2026-02-11（2026-10-20 参照） ↩ ↩2 ↩3
Harness engineering for coding agent users — Birgitta Böckeler（martinfowler.com）, 2026-04-02（2026-10-20 参照） ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8
The harness is all you need (mostly) — GitHub Blog（Burke Holland）, 2026-07-27（2026-10-20 参照） ↩
Effective harnesses for long-running agents — Anthropic, 2025-11-26（2026-10-20 参照） ↩ ↩2
My AI Adoption Journey — Mitchell Hashimoto, 2026-02-05（2026-10-20 参照） ↩ ↩2 ↩3
Evaluating performance and efficiency of the GitHub Copilot agentic harness across models and tasks — GitHub Blog, 2026-06-25（2026-10-20 参照） ↩ ↩2 ↩3 ↩4
Copilot harness generally available in Copilot for JetBrains — GitHub Changelog, 2026-08-24（2026-10-20 参照） ↩ ↩2 ↩3
OpenAI Introduces Harness Engineering: Codex Agents Power Large-Scale Software Development — InfoQ, 2026-02-21（2026-10-20 参照） ↩ ↩2 ↩3
Google トレンド（日本・過去 90 日：AI エージェント、GitHub Copilot ほか） — Google, 2026-10-20 取得（2026-10-20 参照） ↩ ↩2
Google トレンド（日本・過去 90 日：Cursor、GitHub Copilot ほか） — Google, 2026-10-20 取得（2026-10-20 参照） ↩
Google トレンド（日本・過去 90 日：DeepSeek、GitHub Copilot ほか） — Google, 2026-10-20 取得（2026-10-20 参照） ↩
deepseek-ai/deepseek-harness — DeepSeek AI（GitHub）, 公開日不明（2026-10-20 参照） ↩ ↩2
How Claude remembers your project — Anthropic, 公開日不明（2026-10-20 参照） ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8
Custom instructions with AGENTS.md — OpenAI, 公開日不明（2026-10-20 参照） ↩ ↩2 ↩3 ↩4
Harness design for long-running application development — Anthropic（Prithvi Rajasekaran）, 2026-03-24（2026-10-20 参照） ↩ ↩2 ↩3 ↩4
Settings files and precedence — Anthropic, 公開日不明（2026-10-20 参照） ↩
Hooks reference — Anthropic, 公開日不明（2026-10-20 参照） ↩ ↩2 ↩3 ↩4
Adding repository custom instructions for GitHub Copilot — GitHub Docs, 公開日不明（2026-10-20 参照） ↩ ↩2