「AIエージェントを入れたのに品質が安定しない」問題
Harness Engineering とは何か、AIハーネスとはどういう意味かを最初に一言でいえば、AIエージェントを雑に賢くするのではなく、プロジェクトの制約に合わせて動きを制御する設計です。ai harness とは、AIハーネス とは、ハーネスエンジニアリング ai で調べている人も、最終的に知りたいのはこの一点だと思います。
AIコーディングエージェントを導入したエンジニアの多くが、同じ壁にぶつかります。最初は感動する。コードを書かせれば動くものが出てくる。しかし1週間もすると、こんな不満が出てきます。
- 毎回プロジェクトの規約を説明し直さないといけない
- 勝手に不要なリファクタリングを始める
- テストを書かずにコミットしようとする
- 使ってほしくないパッケージを導入する
これらは AI の性能の問題ではありません。ハーネス（harness）の設計不足が原因です。
Claude Code のルール設計を深掘りしたいなら CLAUDE.md の書き方 設計パターン集、Codex を含めた使い分けの前提を先に見たいなら Claude Code vs Codex CLI 比較、再利用できるワークフロー部品まで含めて設計したいなら Codex Skills 設計入門、定期実行まで束ねて「仕組みとして回す」視点を足したいなら Codex Automations 実践ガイド や 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 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 は「作業の進め方」を定義します。
実務での設計指針
段階的に導入する
すべてを一度に設定しようとすると、設定の保守コストが跳ね上がります。私が推奨する導入順は以下です。
- 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 で強制すべきです。
3つの Engineering の使い分け
Harness Engineering は他の手法を置き換えるものではありません。3つの層は補完関係にあります。
| 観点 | Prompt Engineering | Context Engineering | Harness Engineering |
|---|---|---|---|
| スコープ | 1回の対話 | セッション単位 | プロジェクト全体 |
| 対象 | モデルへの指示 | モデルへの入力データ | モデルの外側の仕組み |
| 制御方法 | 自然言語 | RAG、ドキュメント注入 | 設定ファイル + Hook + テスト |
| 得意領域 | タスクの具体的な指示 | 知識の補完 | 品質の一貫性の担保 |
優れたプロンプトで1回の出力品質を上げ、適切なコンテキストで知識を補い、ハーネスでプロジェクト全体の品質を底上げする。この3層の組み合わせが現時点での最適解です。
まとめ
Harness Engineering は、AIコーディングエージェントを実務で運用するための必須スキルになりつつあります。
覚えておくべきポイントは3つです。
- CLAUDE.md は「必要十分」に書く — 長すぎるとコンテキストを圧迫する
- 破ったら事故になるルールは Hooks / Permissions で強制する — 「やるな」という指示だけでは不十分
- 段階的に導入する — 最初から完璧を目指さず、問題が起きたら設定を追加していく
エージェントの性能は日々向上しています。しかし「優秀だが指示なしでは勝手に動く同僚」を制御する仕組みは、性能が上がるほど重要になります。今のうちにハーネス設計のスキルを身につけておくことを強くおすすめします。