ハーネスエンジニアリングとは — AI エージェントの動作環境を設計する技術

はじめに

AI エージェントが期待通りに動かないとき、問題はモデルではなく ハーネス にあることが多いです。

ハーネスエンジニアリングは、AI エージェント全体のインフラストラクチャ ── ガイド、ツール、メモリ、エラーハンドリング ── を設計・構築する技術です。

Martin Fowler はこの概念を以下のように定義しています。

Agent = Model + Harness
ハーネスとは、エージェントにおけるモデル以外のすべて。

プロンプト・コンテキスト・ハーネスの関係

3つの概念は入れ子の関係にあります。

┌─────────────────────────────────────────┐
│  ハーネスエンジニアリング                   │
│  （エージェント全体の設計・制御）             │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │  コンテキストエンジニアリング          │  │
│  │  （コンテキストウィンドウの設計）       │  │
│  │                                   │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │  プロンプトエンジニアリング     │  │  │
│  │  │  （指示文の設計）             │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

概念	対象	一言で
プロンプト	指示文	LLM に「何をさせるか」を指示する
コンテキスト	コンテキストウィンドウ全体	LLM に「何を見せるか」を設計する
ハーネス	エージェント全体のインフラ	LLM を「どう制御するか」を構築する

ハーネスの構成要素

ハーネスは以下の5つの要素で構成されます。

1. ガイド（指示・ルール）

エージェントの振る舞いを定義するルールや指示です。

プロジェクトディレクトリ/
├── CLAUDE.md              # プロジェクト固有のルール
├── .claude/
│   └── skills/            # カスタムコマンドの定義
│       └── deploy/
│           └── SKILL.md

CLAUDE.md の例:

## コーディング規約
- TypeScript で記述する
- テストは vitest を使用する
- コミットメッセージは日本語で書く

## 禁止事項
- main ブランチへの直接 push
- .env ファイルのコミット

ガイドは「エージェントが最初から正しく動作する確率を上げる」ための仕組みです。

2. センサー（情報収集）

エージェントが環境から情報を収集する手段です。

センサー	用途
ファイルシステム読み取り	コードベースの理解
Git 履歴	変更の経緯の把握
テスト実行	コードの正当性の検証
Lint / 型チェック	コード品質の確認
Web 検索	最新情報の取得

センサーが充実しているほど、エージェントは的確な判断ができます。

3. ツールチェーン管理

エージェントが利用できるツールと、その使用条件を制御します。

// .claude/settings.local.json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npx qiita:*)",
      "WebSearch"
    ]
  }
}

スキル定義により、特定のタスク向けのツールセットを用意できます。

---
name: deploy
description: 本番環境へのデプロイを実行する
allowed-tools: Bash, Read, Edit
---

## 手順
1. テストがすべて通ることを確認
2. ビルドを実行
3. デプロイコマンドを実行
4. ヘルスチェックを確認

4. メモリシステム

セッション間で保持される知識です。

.claude/memory/
├── MEMORY.md                  # メモリのインデックス
├── user_preferences.md        # ユーザーの好み
├── project_architecture.md    # プロジェクトの構造
└── feedback_testing.md        # テストに関するフィードバック

メモリにより、エージェントは以下が可能になります。

• 過去の会話で学んだ好みやルールを次回以降も適用する
• プロジェクト固有の知識（アーキテクチャ、命名規則、避けるべきパターンなど）を蓄積する
• フィードバックから学習し、同じ間違いを繰り返さない

5. ライフサイクル管理

エージェントの動作全体を制御する仕組みです。

要素	説明
タスク分割	大きなタスクを小さなサブタスクに分解
並行実行	独立したサブタスクを複数のエージェントで並行処理
エラーハンドリング	失敗時のリトライやフォールバック
人間へのエスカレーション	判断が困難な場合にユーザーに確認
フィードバックループ	テスト・Lint の結果を基に自己修正

具体例: Claude Code のハーネス

Claude Code は代表的なハーネスの実装例です。

┌─ Claude Code ハーネス ──────────────────┐
│                                         │
│  ガイド                                  │
│  ├── CLAUDE.md（プロジェクトルール）       │
│  ├── グローバル CLAUDE.md（全プロジェクト） │
│  └── スキル定義（カスタムコマンド）        │
│                                         │
│  センサー                                │
│  ├── ファイル読み取り（Read, Glob, Grep）  │
│  ├── Git 操作（git log, git diff）       │
│  └── テスト実行（Bash）                  │
│                                         │
│  ツールチェーン                            │
│  ├── 権限設定（settings.local.json）      │
│  ├── MCP サーバー                        │
│  └── フック（pre-commit 等）              │
│                                         │
│  メモリ                                  │
│  ├── .claude/memory/（ファイルベース）     │
│  └── タスク管理                          │
│                                         │
│  ライフサイクル                            │
│  ├── サブエージェント（Agent ツール）       │
│  ├── ワークツリー（並行開発）              │
│  └── 確認フロー（破壊的操作の前）          │
│                                         │
└─────────────────────────────────────────┘

同じ Claude モデルでも、ハーネスの設計によってエージェントの振る舞いは大きく変わります。適切な CLAUDE.md、スキル定義、権限設定があるプロジェクトでは、エージェントの出力品質が飛躍的に向上します。

ハーネス設計の2つの目標

Martin Fowler によると、良いハーネスには2つの目標があります。

目標1: エージェントが最初から正しく動作する確率を上げる

# CLAUDE.md で事前にルールを定義

## テスト
- 変更したファイルに対応するテストを必ず実行する
- テストが落ちたらコミットしない

## コーディング規約
- エラーハンドリングは境界（ユーザー入力、外部API）にだけ入れる
- 過度な抽象化・汎用化はしない

目標2: 問題が人間に到達する前に自己修正する

エージェントがコードを変更
  ↓
自動でテスト実行（センサー）
  ↓
テストが失敗
  ↓
エラーメッセージを読んで自動修正（フィードバックループ）
  ↓
再度テスト実行
  ↓
成功 → コミット

この自己修正のフィードバックループがハーネスの核心です。

スキャフォールディング（足場）の考え方

ハーネスエンジニアリングには、重要な哲学があります。

建物が完成すれば足場は撤去される。モデルが進化すれば、ハーネスの複雑さは減るべきである。

Anthropic も同様の見解を示しています。

モデルの能力が向上すれば、かつて必要だったツールがモデルを制約するようになることがある。

つまり、ハーネスは 永続的なインフラ ではなく、モデルの能力に応じて進化させるべき足場 です。モデルがより賢くなれば、かつて必要だったガードレールや詳細な指示は不要になっていきます。

ハーネス設計のアンチパターン

過剰な制約

# 悪い例: 制約が多すぎてエージェントの能力を活かせない
- 1つのファイルにつき10行以上の変更を禁止
- 必ず3回確認してから実行すること
- すべての変更についてユーザーに承認を求めること

ガイド不足

# 悪い例: 何も指示がない
（CLAUDE.md が空、またはプロジェクトに存在しない）

エージェントはデフォルトの振る舞いで動作するため、プロジェクト固有の規約やパターンに従えません。

フィードバックループの欠如

テストや Lint を実行する仕組みがないと、エージェントは自分のミスに気づけません。センサーとフィードバックループはハーネスの生命線です。

まとめ

構成要素	役割	例
ガイド	エージェントの振る舞いを定義	CLAUDE.md, スキル定義
センサー	環境から情報を収集	ファイル読み取り, Git, テスト実行
ツールチェーン	利用可能なツールと権限を制御	settings.json, MCP
メモリ	セッション間の知識を保持	.claude/memory/
ライフサイクル	タスク分割, エラー処理, 自己修正	サブエージェント, フック

ハーネスエンジニアリングは「モデルをどう制御するか」の技術です。モデルの性能が同じでも、ハーネスの設計でエージェントの実用性は大きく変わります。

エージェントが思い通りに動かないとき、まずプロンプトではなくハーネスを見直してみてください。

参考記事・データ

• Harness engineering for coding agent users - Martin Fowler
• Prompt vs Context vs Harness Engineering: Key Differences - Atlan
• The Anatomy of an Agent Harness - Daily Dose of Data Science
• Agentic Harness Engineering: LLMs as the New OS - Decoding AI
• The Rise of AI Harness Engineering - Cobus Greyling
• Beyond Prompts and Context: Harness Engineering for AI Agents