「AIエージェントを入れたのに品質が安定しない」問題
Harness Engineering とは何かを一言でいえば、AIエージェントを賢さ任せで使うのではなく、プロジェクトの制約に合わせて品質を再現可能にする設計です。ai harness とは、AIハーネス とは、ハーネスエンジニアリング ai で調べている人も、最終的に知りたいのはこの一点だと思います。
AIコーディングエージェントを導入したエンジニアの多くが、同じ壁にぶつかります。最初は感動する。コードを書かせれば動くものが出てくる。しかし1週間もすると、こんな不満が出てきます。
- 毎回プロジェクトの規約を説明し直さないといけない
- 勝手に不要なリファクタリングを始める
- テストを書かずにコミットしようとする
- 使ってほしくないパッケージを導入する
これらは AI の性能の問題ではありません。ハーネス（harness）の設計不足が原因です。
この記事では、Harness Engineering を CLAUDE.md、Hooks、権限、レビュー、UI検証、受け入れゲートをどうつなぐか という実務目線で整理します。Claude Code のルール設計を深掘りしたいなら CLAUDE.md の書き方 設計パターン集、Codex を含めた使い分けの前提を先に見たいなら Claude Code vs Codex CLI 比較、再利用できるワークフロー部品まで含めて設計したいなら Codex Skills 設計入門、定期実行まで束ねて「仕組みとして回す」視点を足したいなら Codex Automations 実践ガイド や Codex 複数エージェント運用ガイド が続きます。手元PC・常時起動ホスト・SSH 環境のどこで Codex を動かすべきかまで詰めたい場合は Codex Remote 設計ガイド を、差分の検証レーンを分けたい場合は AI review harness 設計ガイド、UI確認を review artifact にしたい場合は Codex browser use ガイド、最後の受け入れ条件を固定したい場合は Codex レビュー完了ゲート設計ガイド を合わせて読むと、Harness を広げすぎずに育てやすくなります。
Harness Engineering とは何か
Harness Engineering は、AIコーディングエージェントの動作を制御・最適化するための設計手法です。馬具（harness）が馬の力を御者の意図通りに方向づけるように、エージェントの能力を開発者の目的に沿って制御する仕組みを設計します。
この用語は2026年2月、HashiCorp共同創業者の Mitchell Hashimoto が自身のブログで命名したのが始まりです。彼の定義は明快で、「エージェントがミスをするたびに、そのミスを二度と起こさないよう解決策をエンジニアリングすること」。その数日後、OpenAI が公式ブログで取り上げたことで一気に広まりました。2026年4月には東京でミートアップイベントも開催されるなど、一つの技術領域として確立しつつあります。
この概念は、AI活用スキルの進化の第3段階と位置づけられます。
- Prompt Engineering — 1回の対話で最適な出力を引き出す技術
- Context Engineering — 適切なコンテキスト（文書、コード、履歴）をモデルに与える技術
- Harness Engineering — プロジェクト全体を通じてエージェントの行動を一貫して制御する仕組みの設計
プロンプトやコンテキストが「モデルへの入力」を最適化するのに対し、ハーネスはモデルの外側——ツール、テスト、権限、ライフサイクルフック——を設計対象とします。組織導入や安全運用まで視野に入れるなら、AIコーディングツールの社内ガイドライン や MCP エンタープライズ運用ガイド とセットで考えると、制御境界が整理しやすくなります。
ハーネスの4層構造
私は実務で Harness Engineering を以下の4層で捉えています。
| Layer | 名称 | 役割 |
|---|---|---|
| Layer 4 | Skills / Plugins | 再利用可能なワークフロー |
| Layer 3 | Hooks | イベント駆動の自動制御 |
| Layer 2 | Permissions | 権限によるガードレール |
| Layer 1 | CLAUDE.md | 静的な指示・文脈 |
下の層ほど基礎的で、上の層ほど高度な制御が可能になります。多くの記事が Layer 1 の CLAUDE.md しか扱っていませんが、実務で品質を安定させるには Layer 2〜3 が不可欠です。
一方で、最近の実務では Layer 4 の上にさらに「レビューをどう流すか」が必要になります。つまり Harness は設定を書いて終わりではなく、変更後の検証と受け入れをどこで止めるかまで含めて初めて安定します。この後で触れる review harness や review gate は、4層の外に後付けする別物ではなく、4層を現場で機能させる出口です。
Layer 1: CLAUDE.md — 静的な文脈と指示
CLAUDE.md はプロジェクトのルートに置く Markdown ファイルで、エージェントに対する静的な指示書です。エージェントはセッション開始時にこのファイルを読み込み、プロジェクトの文脈を理解します。
書くべき内容
# CLAUDE.md
## プロジェクト概要
<!-- エージェントに「何のプロジェクトか」を理解させる -->
ポートフォリオサイト兼ブログ。Astro 5 による静的サイト生成。
## コマンド
<!-- 「どう動かすか」を正確に伝える -->
pnpm run dev # 開発サーバー起動
pnpm run build # 本番ビルド
pnpm run format # Prettier で整形
## アーキテクチャ
<!-- 技術選定の「なぜ」まで書く -->
- Astro 5 — 静的出力、@astrojs/sitemap 統合
- TypeScript — strict モード
## 規約
<!-- 判断基準を明確にする -->
- パッケージマネージャは pnpm（npm/yarn 禁止）
- インデント: 2スペースCLAUDE.md 設計の3つの原則
1. 「何を」だけでなく「なぜ」を書く
「TypeScript strict を使う」だけでは不十分です。「型安全性を担保するため strict を使う。any の使用は原則禁止」と書くことで、エージェントが関連する判断（as any を使うかどうか等）も正しく行えるようになります。
2. 必要十分に抑える
ここが最も多くの人が見落としているポイントです。CLAUDE.md に書いた内容は毎セッションのコンテキストを消費します。100行の CLAUDE.md と500行の CLAUDE.md では、エージェントが実際の作業に使えるコンテキストが大きく変わります。
私は以下のルールを守っています。
- 200行以下に抑える
- コードサンプルは最小限（実際のファイルを読めばわかることは書かない）
- 更新頻度の低い情報（アーキテクチャ概要）と高い情報（現在の作業）を分離する
3. 階層を活用する
CLAUDE.md は3つのスコープで配置できます。
| ファイル | スコープ | 用途 |
|---|---|---|
~/.claude/CLAUDE.md | グローバル | 全プロジェクト共通の個人設定 |
プロジェクト/CLAUDE.md | プロジェクト | プロジェクト固有の指示（チームで共有） |
プロジェクト/src/CLAUDE.md | ディレクトリ | 特定ディレクトリ内の規約 |
グローバル設定には「応答は日本語で」「思考過程を開示する」のような個人の好みを、プロジェクト CLAUDE.md にはチーム全員に適用したいルールを書きます。
Layer 2: Permissions — 権限によるガードレール
Permissions は、エージェントが使えるツール（ファイル読み書き、コマンド実行など）の権限を制御する仕組みです。
// .claude/settings.json
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(pnpm run *)",
"Bash(git status)",
"Bash(git diff *)"
],
"deny": ["Bash(rm -rf *)", "Bash(git push --force *)"]
}
}実務で効いた設定パターン:
Bash(pnpm run *)を許可しBash(npm *)を拒否 → パッケージマネージャの混在を防止Bash(git push --force *)を拒否 → 事故防止の最後の砦- 破壊的操作は
denyに明示的に列挙 → CLAUDE.md に「やるな」と書くより確実
CLAUDE.md の「やらないで」という指示は、コンテキストが長くなると無視されることがあります。Permissions による制御はプログラム的に強制されるため、この問題が発生しません。
Layer 3: Hooks — イベント駆動の自動制御
Hooks は Harness Engineering の中核機能です。エージェントのライフサイクル上の特定ポイントで処理を自動実行できます。CLAUDE.md のルールが「助言」であるのに対し、Hooks は「強制ゲート」として機能する点が決定的に異なります。
Hook イベントの種類
Claude Code には20以上のイベントが定義されていますが、実務で特に重要なのは以下の4つです。
| イベント | タイミング | 用途 |
|---|---|---|
PreToolUse | ツール使用前 | 危険な操作のブロック（exit code 2 で停止） |
PostToolUse | ツール使用後 | 出力の検証、自動フォーマット |
SessionStart | セッション開始時 | 環境チェック、自動セットアップ |
Stop | 応答完了時 | 最終チェック、レポート生成 |
他にも UserPromptSubmit（プロンプト送信時）、SubagentStop（サブエージェント完了時）、PreCompact（コンテキスト圧縮前）など多数ありますが、まずはこの4つを押さえれば十分です。
ハンドラの4タイプ
Hooks の実行方法は command だけではありません。実は4種類から選べます。
| タイプ | 特徴 | 使い分け |
|---|---|---|
command | シェルコマンドを実行 | フォーマッタ実行、ファイル検証 |
prompt | 軽量LLMで判定 | 「この変更はテストが必要か？」等の意味的判断 |
agent | サブエージェントで検証 | 複数ファイルを横断した整合性チェック |
http | HTTP エンドポイントに POST | 外部サービス連携、監査ログ |
command 型はシンプルで高速ですが、意味的な判断はできません。「このコード変更にはテストの追加が必要か？」のような判断には prompt 型が適しています。ただし prompt 型と agent 型はLLMを呼び出すため、レイテンシとコストが発生します。
私の使い分けの原則: まず command 型で書けないか検討し、意味的な判断が必要な場合だけ prompt 型を使う。agent 型はコストが大きいため、本当に複雑な検証にのみ使います。
実践的な Hooks 設定例
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "pnpm run format --write $CLAUDE_FILE_PATH 2>/dev/null || true"
}
],
"PreToolUse": [
{
"matcher": "Bash",
"command": "echo $CLAUDE_TOOL_INPUT | grep -q 'npm install' && echo 'BLOCK: Use pnpm, not npm' && exit 1 || true"
}
]
}
}ポイントは PreToolUse の exit code です。exit 0 で許可、exit 2 でブロック（stderr の内容がエージェントにフィードバックされる）、それ以外は許可扱い。この仕組みにより、エージェントは「なぜブロックされたか」を理解して自動的に修正できます。
Hooks 設計の落とし穴
Hooks には注意点もあります。
ローカル依存の罠: Hooks は settings.json に定義されるため、そのマシンの環境に依存します。チームで共有する場合は .claude/settings.json をリポジトリにコミットしますが、Hooks が参照するスクリプトのパスやツールのインストール状況が各メンバーで異なるとエラーになります。
Web 版との非互換: Hooks はローカルの CLI 版でのみ動作します。Web 版（claude.ai）で同じプロジェクトを扱う場合、Hooks による制御は一切効きません。つまり CLAUDE.md だけで最低限の品質を担保できる状態にした上で、Hooks で追加の安全策を重ねるのが正しいアプローチです。
パフォーマンスへの影響: PostToolUse Hook でフォーマッタを毎回実行すると、ファイル編集のたびにオーバーヘッドが発生します。処理が重い場合は特定のファイルパターンだけに絞る、または Stop イベントで一括実行する方法を検討してください。
Layer 4: Skills — 再利用可能なワークフロー
Skills はエージェントに特定のワークフローやベストプラクティスをパッケージとして読み込ませる仕組みです。TDD、デバッグ手順、コードレビューチェックリストなどを Skill として定義し、必要に応じてエージェントに適用できます。
// Skills の活用イメージ
/test-driven-development → テストファースト開発の手順を強制
/systematic-debugging → デバッグの体系的アプローチを適用
/code-review → レビュー観点のチェックリストを適用Skills の特徴は手続き的な知識をカプセル化できる点です。CLAUDE.md が「プロジェクトの文脈」を伝えるのに対し、Skills は「作業の進め方」を定義します。
最初の1週間で作る最小ハーネス
Harness Engineering という言葉だけ先に知ると、大規模な仕組みを最初から作る話に見えがちです。実務では逆です。私は最初の1週間なら、次の5点しか入れません。
| 先に作るもの | 役割 | 深追いしないこと |
|---|---|---|
AGENTS.md / CLAUDE.md の最小セット | プロジェクト概要、禁止事項、検証コマンドを固定する | 仕様書の全文転載 |
| permissions / approvals | 破壊的操作や不要な package 導入を止める | 例外だらけの allowlist |
| 1つの deterministic check | format、build、test のどれかを毎回通す | 重すぎる全件検査 |
| review harness の最小テンプレート | self check と evidence の粒度を揃える | 高リスクでない差分への過剰レビュー |
| review gate の完了条件 | 何を見たら merge できるかを固定する | 「AI が完了と言ったら完了」運用 |
この5点があるだけで、AIエージェントの失敗はかなり減ります。特に Codex や Claude Code のようにツール実行まで含む環境では、「何を書くか」より「どこで止めるか」の方が効きます。
review / browser / gate をどう分けるか
Harness Engineering を調べる人は、最近だと review、browser、approval、remote 実行環境まで一度に知りたくなりがちです。ただし、ここを1記事で全部抱えると検索意図が崩れます。私の切り分けは次です。
| 論点 | 先に読む記事 | この Harness 記事で扱う範囲 |
|---|---|---|
| 自己レビュー、証拠化、deep review、人間ゲート | AI review harness 設計ガイド | なぜ review lane が必要かの上位概念 |
| localhost や公開ページのUI確認 | Codex browser use ガイド | browser を証拠化レーンとして使う理由 |
| 差分受け入れ前の確認条件 | Codex レビュー完了ゲート設計ガイド | merge 前に gate を持つべき理由 |
| 手元PC、常時起動ホスト、SSH の実行境界 | Codex Remote 設計ガイド | harness が実行環境にも依存するという論点 |
Harness Engineering の役割は、これらを全部説明することではありません。それぞれを別laneとして設計する理由を与えることです。
実務での設計指針
段階的に導入する
すべてを一度に設定しようとすると、設定の保守コストが跳ね上がります。私が推奨する導入順は以下です。
- CLAUDE.md を書く（30分） — プロジェクト概要、コマンド、アーキテクチャ、規約
- Permissions を設定する（15分） — 使用可能なコマンドの明示的な許可/拒否
- PostToolUse Hook を1つ追加する（15分） — 自動フォーマットが最も効果が高い
- 運用しながら育てる — 問題が起きたら Hook を追加、CLAUDE.md を更新
「設定しすぎ」の見極め
Harness Engineering にハマると、あらゆるケースをカバーしようとして設定が肥大化しがちです。以下の兆候が出たら設計を見直すべきです。
- CLAUDE.md が300行を超えた
- Hooks が10個以上ある
- エージェントの応答速度が体感で遅くなった
- 設定の意図を自分でも説明できない項目がある
エージェントの制御は「80/20の法則」が強く効きます。20%の設定で80%の品質問題を防げるのが理想です。
決定論的制約を優先する
Harness Engineering で私が最も重視している原則があります。CLAUDE.md（自然言語）の層は薄く保ち、リンター・テスト・Hooks（決定論的な仕組み）に投資を集中することです。
自然言語の指示は確率的です。コンテキストが長くなれば無視される可能性があります。一方、Hooks や Permissions はプログラム的に実行されるため、100% 遵守されます。「pnpm を使え」と CLAUDE.md に書くより、PreToolUse Hook で npm コマンドをブロックする方が確実です。
CLAUDE.md か Hooks か、の判断基準
上記を踏まえた判断基準はシンプルです。
- 「忘れても致命的でない」指示 → CLAUDE.md（ソフトな制約）
- 「破ったら事故になる」ルール → Hooks / Permissions（ハードな制約）
コーディングスタイルの指示は CLAUDE.md で十分です。一方、「本番ブランチへの force push 禁止」は Permissions で強制すべきです。
実務で追加すると効く補助レーン
最近の AI コーディング運用では、CLAUDE.md と Hooks だけでは詰まる箇所があります。私が後から足して効果が高かったのは次の3つです。
- review harness: 差分を self check、evidence check、deep review、人間ゲートへ流す順番を固定する
- browser evidence: UI変更時に「見たはず」をやめて、route、viewport、checked / not checked を artifact として残す
- review gate: diff、verification、risk、rollback を満たすまで merge しない
この3つは Harness の本体ではなく運用補助に見えるかもしれませんが、実際には 良い指示が守られたかを確認する出口 です。入口だけ整えても、出口が曖昧なら品質は安定しません。
4つの Engineering の使い分け
Harness Engineering は他の手法を置き換えるものではありません。4つの層は補完関係にあります。
| 観点 | Prompt Engineering | Context Engineering | Harness Engineering | Loop Engineering |
|---|---|---|---|---|
| スコープ | 1回の対話 | セッション単位 | プロジェクト全体 | 複数runの反復 |
| 対象 | モデルへの指示 | モデルへの入力データ | モデルの外側の仕組み | run間の状態遷移 |
| 制御方法 | 自然言語 | RAG、ドキュメント注入 | 設定ファイル + Hook + テスト | 検証 + retry + 停止条件 |
| 得意領域 | タスクの具体的な指示 | 知識の補完 | 品質の一貫性の担保 | 長時間taskの収束 |
優れたプロンプトで1回の出力品質を上げ、適切なコンテキストで知識を補い、ハーネスでプロジェクト全体の品質を底上げする。さらに複数の試行を検証・再試行・停止へつなぐ方法はLoop Engineering実践ガイドで整理しています。
まとめ
Harness Engineering は、AIコーディングエージェントを実務で運用するための必須スキルになりつつあります。
覚えておくべきポイントは3つです。
- CLAUDE.md は「必要十分」に書く — 長すぎるとコンテキストを圧迫する
- 破ったら事故になるルールは Hooks / Permissions で強制する — 「やるな」という指示だけでは不十分
- レビューと受け入れまで lane を分ける — review harness、browser evidence、review gate を後段に置く
エージェントの性能は日々向上しています。しかし「優秀だが指示なしでは勝手に動く同僚」を制御する仕組みは、性能が上がるほど重要になります。今のうちにハーネス設計のスキルを身につけておくことを強くおすすめします。