ハーネスエンジニアリング入門 — LLMを「賢く動かす」ための周辺装置を設計する

ハーネスエンジニアリングとは何か

「良いプロンプトを書いたのに、Agentが期待通りに動かない」——AI Agentを本番投入したことがある人なら、 一度は経験があるはずです。2026年の現在、LLMそのものの性能は十分に高く、ボトルネックはもはや モデルではなく、その周辺装置（harness）の設計にあります。

ハーネスエンジニアリング（Harness Engineering）とは、 LLMを実用的なAgentに仕立てるための「足場」を設計する実践分野です。 馬具（harness）が馬の力を引き出すように、ハーネスはLLMという生の能力を タスク遂行力へと変換する装置群を指します。

graph TB
    subgraph "Harness（周辺装置）"
        A["System Prompt<br/>役割・制約"]
        B["Tools<br/>実行可能な操作"]
        C["Context Management<br/>何を入れ、何を捨てるか"]
        D["Memory<br/>セッション間の永続化"]
        E["Hooks<br/>自動実行される処理"]
        F["Permissions<br/>安全境界"]
        G["Feedback Loop<br/>エラーの戻し方"]
    end
    subgraph "LLM"
        M["Claude / GPT / Gemini"]
    end
    A --> M
    B --> M
    C --> M
    D --> M
    E --> M
    F --> M
    M --> G
    G --> M

なぜ今、ハーネスが重要なのか

2023〜2024年頃までは、タスク性能の差は主にモデルの差で決まっていました。 しかし2026年の現在、フロンティアモデル同士の性能差は狭まり、 同じモデルでもハーネスの設計次第で実用性能が数倍変わる状況が生まれています。

Anthropicが公開したClaude Codeの設計資料やSWE-benchのリーダーボードを見ると、 上位勢は軒並み「独自ハーネス」を武器にしています。モデルを変えずに ハーネスだけを改良することで、解決率が20ポイント以上改善した事例も珍しくありません。

ハーネスの構成要素

良いハーネスは7つの要素で構成されます。それぞれ独立に設計できますが、 相互作用を意識しないと片方の改善が他方を台無しにすることもあります。

1. ツール設計 — 最重要要素

ハーネスエンジニアリングの中で最も投資対効果が高いのはツール設計です。 ツールとは、Agentが外界に働きかけるための関数群のこと。 ファイル読み書き、シェル実行、DB検索、API呼び出しなどが該当します。

良いツールの条件は3つです：

• 小さく直交している: 1つのツールは1つのことだけをする。run_everything()のような万能ツールは避ける
• 失敗が自己説明的: エラーメッセージが次の行動を示唆する。「ファイルが見つかりません」ではなく「src/foo.tsが見つかりません。類似パス: src/foo.tsx」のように
• 副作用が可視: 何を変更したかが戻り値から分かる。サイレントな副作用は Agentを混乱させる

// ❌ 悪いツール設計
async function manageFile(action: string, path: string, content?: string) {
  // read, write, delete を1つにまとめている → 誤用しやすい
}

// ✅ 良いツール設計
async function readFile(path: string): Promise<{ content: string; lines: number }> { ... }
async function writeFile(path: string, content: string): Promise<{ bytes: number }> { ... }
async function deleteFile(path: string): Promise<{ deleted: true }> { ... }

// エラーも自己説明的に
async function readFile(path: string) {
  if (!exists(path)) {
    const similar = findSimilarPaths(path);
    throw new Error(
      `File not found: ${path}. Did you mean: ${similar.join(', ')}?`
    );
  }
  // ...
}

2. コンテキスト管理 — 入れるより捨てる

コンテキストウィンドウは1M tokenに拡大しましたが、 全部詰め込むのは最悪の選択です。 「lost in the middle」問題により、中盤の情報はモデルが無視する傾向があります。

実践的な指針：

• 直近が重要: 最新のツール結果・直近のユーザー発言は文末近くに配置
• 要約で圧縮: 長い会話履歴は古い部分から要約に置き換える
• 遅延ロード: ドキュメントは必要になった時点でツール経由で取得。最初から全部入れない
• セクション区切り: <system-reminder>などのタグで情報の出所を明示

3. フック — 決定論的な強制力

プロンプトは「お願い」であり、モデルは破ることができます。 絶対に守らせたいルールはフック（決定論的処理）で強制します。 Claude CodeのPreToolUse/PostToolUseフックはこの典型例で、 exit 2を返せばツール実行を完全にブロックできます。

4. 権限境界 — 失敗の爆発半径を制限

Agentは必ず間違えます。問題は「間違えた時にどこまで被害が広がるか」です。 rm -rf /を許可しない、本番DBへの直接接続を禁止する、といった deny-listベースのガードレールを先に敷きます。

5. メモリ — セッションを超えた学習

1セッション内で完結するAgentは作業の度に同じ間違いを繰り返します。 メモリは「今回学んだこと」を次回に引き継ぐ装置です。 ただし「何を保存するか」の設計が難しく、安易に全てを保存すると ノイズだらけになり、むしろ性能が劣化します。

6. フィードバックループ — エラーの戻し方が全て

Agentが失敗した時、どのような情報を返すかで次の行動の質が決まります。 スタックトレースをそのまま返すのは最悪で、 「何が失敗したか」「なぜ失敗したか」「次に試すべきこと」を構造化して返すべきです。

7. システムプロンプト — 最後の調整弁

意外なことに、システムプロンプトの重要度は最下位です。 ツール設計・権限・フックがきちんとしていれば、プロンプトは短く済みます。 逆に、プロンプトで無理やり補おうとしている時点で、ハーネスのどこかに欠陥があります。

良いハーネスの設計原則

これまでの要素を踏まえ、ハーネス設計で守るべき原則を5つにまとめます。

実例: Claude Codeのハーネス設計

Claude Codeは、ハーネスエンジニアリングの参考実装として非常に良くできています。 主要な設計上の決断を見てみましょう。

• Read/Edit/Write/Bash/Globなど小さなツール群: 各ツールは単機能で、組み合わせで複雑な作業を実現
• Skillsによる動的ロード: 全機能を常にコンテキストに載せず、トリガーワードで必要なスキルだけ読み込む
• Hooksで決定論的に自動化: フォーマッタ実行や危険コマンドのブロックはフックで強制
• MEMORY.mdによる200行制限付きメモリ: 肥大化を防ぎつつセッション間の学習を可能にする
• エラーメッセージが行動指示: 「Read before Edit」のように、次にやるべきことを明示
• Sub-agentで並列探索: メインコンテキストを汚さずに広範囲の調査ができる

よくある落とし穴

ハーネス設計で多くのチームが同じ失敗をします。代表的な3つを挙げます。

落とし穴1: プロンプトで全てを解決しようとする

「ツールを慎重に使え」「ファイルを壊すな」といった指示をシステムプロンプトに 書き足し続けると、プロンプトが肥大化し、逆に遵守率が下がります。 守らせたいことはコードで強制するのが鉄則です。

落とし穴2: 万能ツールを作る

「1つのツールで何でもできる」ツールは魅力的ですが、 Agentはパラメータ選択で迷って間違えるようになります。 5つの小さなツールに分けた方が、結果的にAgentの判断精度は上がります。

落とし穴3: 成功パスしかテストしない

ハーネスの品質は「エラー時にどう立て直せるか」で決まります。 ツールが失敗した時、タイムアウトした時、想定外の出力が返ってきた時に Agentが正しく回復できるかを、本番投入前に必ず確認してください。

まとめ — ハーネスこそがAgentの本質

2026年、AI Agentの性能差はもはやモデルではなく、ハーネスの設計で決まっています。 ポイントを振り返ります：

• ハーネスとはLLMの周辺装置全体: ツール、コンテキスト、メモリ、権限、フック、フィードバック、プロンプトの7要素
• ツール設計が最も重要: 小さく・直交・自己説明的な失敗を満たす
• コンテキストは「入れる」より「捨てる」: 1M tokenでも全部詰め込まない
• 守らせたいルールはコードで強制: プロンプトは「お願い」、フックは「法律」
• エラーの戻し方が Agentの賢さを決める: 次の行動を示唆する構造化エラーを返す
• システムプロンプトは最後の調整弁: 長大化していたら、それはハーネスの欠陥のサイン

良いモデルは出発点に過ぎません。Agentを実用的にする本当の工学は、 モデルの外側——ハーネスにあります。次にAgentを設計する時は、 「どのプロンプトを書くか」より先に「どんなツールを持たせるか」から考えてみてください。