Tech

Harness Engineering とは？ AIエージェントの出力品質を安定させる設計手法入門

nidoneko · · 14 min read
Claude CodeAI開発効率化Harness Engineering
🎯

「AIエージェントを入れたのに品質が安定しない」問題

AIコーディングエージェントを導入したエンジニアの多くが、同じ壁にぶつかります。最初は感動する。コードを書かせれば動くものが出てくる。しかし1週間もすると、こんな不満が出てきます。

  • 毎回プロジェクトの規約を説明し直さないといけない
  • 勝手に不要なリファクタリングを始める
  • テストを書かずにコミットしようとする
  • 使ってほしくないパッケージを導入する

これらは AI の性能の問題ではありません。ハーネス（harness）の設計不足が原因です。

Harness Engineering とは何か

Harness Engineering は、AIコーディングエージェントの動作を制御・最適化するための設計手法です。馬具（harness）が馬の力を御者の意図通りに方向づけるように、エージェントの能力を開発者の目的に沿って制御する仕組みを設計します。

この用語は2026年2月、HashiCorp共同創業者の Mitchell Hashimoto が自身のブログで命名したのが始まりです。彼の定義は明快で、「エージェントがミスをするたびに、そのミスを二度と起こさないよう解決策をエンジニアリングすること」。その数日後、OpenAI が公式ブログで取り上げたことで一気に広まりました。2026年4月には東京でミートアップイベントも開催されるなど、一つの技術領域として確立しつつあります。

この概念は、AI活用スキルの進化の第3段階と位置づけられます。

  • Prompt Engineering — 1回の対話で最適な出力を引き出す技術
  • Context Engineering — 適切なコンテキスト（文書、コード、履歴）をモデルに与える技術
  • Harness Engineering — プロジェクト全体を通じてエージェントの行動を一貫して制御する仕組みの設計

プロンプトやコンテキストが「モデルへの入力」を最適化するのに対し、ハーネスはモデルの外側——ツール、テスト、権限、ライフサイクルフック——を設計対象とします。

ハーネスの4層構造

私は実務で Harness Engineering を以下の4層で捉えています。

Layer名称役割
Layer 4Skills / Plugins再利用可能なワークフロー
Layer 3Hooksイベント駆動の自動制御
Layer 2Permissions権限によるガードレール
Layer 1CLAUDE.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サブエージェントで検証複数ファイルを横断した整合性チェック
httpHTTP エンドポイントに 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. CLAUDE.md を書く（30分） — プロジェクト概要、コマンド、アーキテクチャ、規約
  2. Permissions を設定する（15分） — 使用可能なコマンドの明示的な許可/拒否
  3. PostToolUse Hook を1つ追加する（15分） — 自動フォーマットが最も効果が高い
  4. 運用しながら育てる — 問題が起きたら 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 EngineeringContext EngineeringHarness Engineering
スコープ1回の対話セッション単位プロジェクト全体
対象モデルへの指示モデルへの入力データモデルの外側の仕組み
制御方法自然言語RAG、ドキュメント注入設定ファイル + Hook + テスト
得意領域タスクの具体的な指示知識の補完品質の一貫性の担保

優れたプロンプトで1回の出力品質を上げ、適切なコンテキストで知識を補い、ハーネスでプロジェクト全体の品質を底上げする。この3層の組み合わせが現時点での最適解です。

まとめ

Harness Engineering は、AIコーディングエージェントを実務で運用するための必須スキルになりつつあります。

覚えておくべきポイントは3つです。

  1. CLAUDE.md は「必要十分」に書く — 長すぎるとコンテキストを圧迫する
  2. 破ったら事故になるルールは Hooks / Permissions で強制する — 「やるな」という指示だけでは不十分
  3. 段階的に導入する — 最初から完璧を目指さず、問題が起きたら設定を追加していく

エージェントの性能は日々向上しています。しかし「優秀だが指示なしでは勝手に動く同僚」を制御する仕組みは、性能が上がるほど重要になります。今のうちにハーネス設計のスキルを身につけておくことを強くおすすめします。

WRITTEN BY nidoneko

Full-stack engineer with 8+ years of experience in TypeScript, React, Node.js, and cloud-native development across healthcare, finance, HR, and IoT domains.

View Profile →
// Related articles View All
🧠
Claude Code

Claude Code サブエージェント運用ガイド — 並列委譲・コンテキスト分離・レビュー役分担の実践

·14 min read

Claude Code のサブエージェント運用を実務目線で解説します。main 会話との使い分け、並列委譲、レビュー役分担、権限とツール制限、worktree 分離まで、実際に事故りやすい論点に絞って整理しました。

Read More →
📋
AIコーディング

AIコーディングツールの社内ガイドライン — 安全運用テンプレと判断基準

·10 min read

AIコーディングツールを社内導入したいが、何を禁止し何を許可すべきか曖昧な方向けに、最小構成の社内ガイドラインをテンプレ付きで整理します。入力データ、実行権限、レビュー境界、監査、MCP の扱いまで実務向けにまとめました。

Read More →
🧩
AIエージェント

マルチエージェントオーケストレーション 4パターン解説 — 逐次・並列・階層・フィードバックループの使い分け

·9 min read

マルチエージェントオーケストレーションを実務に入れたい方向けに、逐次・並列・階層・フィードバックループの4パターンを整理します。どの業務に向くか、壊れやすい点、監視項目まで実装目線で解説します。

Read More →