Harness Engineering：壊れない AI エージェントを構築するための完全ガイド

ほとんどの人は、AI エージェントの改善を間違ったレイヤーで行っています。

エージェントが失敗すると、プロンプトを書き直します。

また失敗すると、さらに指示を追加します。

始める前に：

私の Substack をフォローして、X で公開される前に、最新の AI アルファ情報、エージェントワークフロー、ステップバイステップガイドを入手してください： [https://substack.com/@lunarresearcher

そして、モデルを切り替え、ツールを追加し、コンテキストウィンドウを拡大し、次回の実行が異なる動作をすることを期待します。

しかし、多くのエージェントの失敗は、推論の失敗ではありません。

それらは環境の失敗です。

エージェントは、どのファイルが重要かを知りませんでした。

正しいツールを間違った場所で使用しました。

前のセッションで下した決定を失いました。

チェックを実行せずに成功を主張しました。

部分的な失敗の後でアクションを繰り返しました。

承認が必要なことを実行する権限を持っていました。

モデルが必ずしも問題だったわけではありません。モデルを囲むシステムが不完全だったのです。

そのシステムこそがハーネスです。

そして、それを設計することは、独自のエンジニアリング分野になりつつあります。

ハーネスエンジニアリングとは、モデルの知能を信頼性の高い作業に変える環境を構築する実践です。

プロンプトは、1 回の試行を変えます。

ハーネスは、すべての試行を変えます。

このガイドでは、その構築方法を説明します。

1. モデルはエージェントではない

モデルは、推論、生成、比較、選択ができます。

しかし、エージェントは実際の環境と対話する必要もあります。

エージェントは以下を行う必要があります：

• タスクを理解する
• 関連するコンテキストを見つける
• ツールを選択して使用する
• 状態を保持する
• 権限を尊重する
• 結果を検査する
• 失敗から回復する
• 作業が完了したことを証明する

モデルは、そのシステム内の推論エンジンです。

ハーネスは、推論を運用可能にするすべてのものです。

1user request
2     |
3     v
4+-----------------------------+
5|           HARNESS           |
6| contract | context | policy |
7| tools    | state   | checks |
8| traces   | recovery          |
9+-----------------------------+
10     |
11     v
12    model
13     |
14     v
15real environment

弱いハーネス内の強力なモデルは、依然として弱いエージェントです。

印象的な個別の応答を生成するかもしれませんが、長期的なタスク、変化する環境、部分的な失敗に対して一貫性のない動作をします。

ハーネスエンジニアリングの目標は、モデルから不確実性を取り除くことではありません。

その不確実性を、観察、検証、回復できるシステム内に閉じ込めることです。

2. タスク契約から始める

ほとんどのエージェントタスクは、曖昧な意図から始まります：

オンボーディングフローを改善する。

その一文は、会話には十分かもしれません。

自律的な実行には不十分です。

エージェントが行動する前に、ハーネスはリクエストをタスク契約に変換する必要があります。

有用な契約は、5 つの質問に答えます：

1. どのような成果が存在しなければならないか？
2. スコープ内にあるものは何か？
3. 変更してはならないものは何か？
4. 完了を証明する証拠は何か？
5. どのアクションに人間の承認が必要か？

1objective: reduce onboarding drop-off
2
3scope:
4  - signup flow
5  - onboarding analytics
6
7constraints:
8  - do not change authentication
9  - preserve existing mobile behavior
10
11acceptance:
12  - tests pass
13  - analytics event is emitted
14  - screenshots cover desktop and mobile
15
16approval_required:
17  - production deployment
18  - database migration

これにより、エージェントの質問が次のように変わります：

次に何をすべきか？

から、次のようになります：

環境を契約された成果に向けて動かすアクションは何か？

契約がなければ、エージェントはもっともらしい活動のために最適化します。

契約があれば、検証された完了のために最適化できます。

3. エージェントにマニュアルではなく、地図を与える

リポジトリ全体、ドキュメントセット、会話履歴をコンテキストにダンプすることは、優れたコンテキストエンジニアリングではありません。

それはコンテキストの氾濫です。

ハーネスは、最初に小さな地図を提供し、関連性が生じたときにエージェントが詳細を取得できるようにする必要があります。

1PROJECT MAP
2
3product rules     -> docs/product/
4architecture      -> docs/architecture.md
5frontend          -> apps/web/
6backend           -> services/api/
7tests             -> tests/
8commands          -> docs/commands.md
9release rules     -> docs/release.md

これは段階的な開示です：

1task
2  -> project map
3      -> relevant subsystem
4          -> exact files
5              -> local instructions

コンテキストは、情報が存在するからではなく、タスクが必要とするために拡張されるべきです。

優れたコンテキストコンパイラは、以下を決定します：

• 常に必要なもの
• 後で取得できるもの
• 古くなったもの
• 要約できるもの
• 逐語的に残さなければならないもの

目標は最大のコンテキストではありません。

トークンあたりの最大のシグナルです。

4. ツールの山ではなく、ツールゲートウェイを構築する

エージェントに 20 個のツールを与えても、能力が向上するわけではありません。

エージェントにミスをする 20 の方法を与えるだけです。

すべてのツールには、明確な契約が必要です：

1TOOL: edit_file
2
3inputs:
4  path
5  patch
6
7preconditions:
8  path exists
9  path is inside allowed workspace
10
11success evidence:
12  patch applied
13  resulting diff returned
14
15failure behavior:
16  no partial overwrite
17  structured error returned
18
19risk class:
20  reversible

ハーネスは、ツールがどのように公開され、使用されるかを制御する必要があります。

ハーネスは以下を行うことができます：

• 無関係なツールを非表示にする
• 引数を検証する
• パスとドメインを制限する
• タイムアウトをアタッチする
• リトライをべき等にする
• 出力を正規化する
• リスクの高いアクションに確認を要求する
• 「成功」だけでなく、証拠を返す

これにより、重要な分離が生まれます：

1model decides intent
2gateway validates action
3tool changes environment
4sensor observes result

モデルはアクションを提案できます。

ツールゲートウェイは、そのアクションが実行するのに十分有効かどうかを決定します。

5. 頭脳、手、履歴を分離する

多くの脆弱なエージェントは、すべてを 1 つの成長するトランスクリプトに混ぜ合わせます。

推論、ツール呼び出し、ファイル、決定、エラー、古い観測結果がすべて、同じコンテキストウィンドウを奪い合います。

より強力なシステムは、3 つの責任を分離します：

1BRAIN
2plans, reasons, chooses
3
4HANDS
5execute tools inside a controlled environment
6
7HISTORY
8stores durable facts, decisions, and run state

モデルは、アクティブなコンテキスト内ですべての生のイベントを必要とするわけではありません。

正しい現在の状態が必要です。

サンドボックスは、目的全体を理解する必要はありません。

制限されたアクションを安全に実行する必要があります。

セッションログは、推論する必要はありません。

現在のコンテキストが消えた後に何が起こったかを保存する必要があります。

この分離により、長時間実行されるエージェントの再開、検査、修復が容易になります。

また、システム全体を再構築することなく、1 つの部分を交換することもできます。

6. メモリは永続的な状態になる必要がある

会話履歴は、信頼できるメモリではありません。

それはイベントストリームです。

有用なメモリは、明示的な状態に変換される必要があります。

最低でも、4 つのカテゴリを保存します：

1FACTS
2stable information discovered about the environment
3
4DECISIONS
5choices made and the reason behind them
6
7PROGRESS
8completed, active, blocked, and remaining work
9
10LESSONS
11failures that should change future behavior

例えば：

1facts:
2  - checkout validation lives in services/orders
3
4decisions:
5  - reuse the existing validation pipeline
6  - reason: avoids a second source of truth
7
8progress:
9  completed:
10    - added server-side rule
11  remaining:
12    - update integration test
13
14lessons:
15  - local test command requires TEST_DB_URL

これは、50 ページのトランスクリプトを再生して、モデルが重要な行に気付くことを期待するよりもはるかに有用です。

監査可能性のために生の履歴を保存します。

実行のために永続的な状態をコンパイルします。

7. 完了には証拠が必要

エージェントが「完了した」と言うことは、タスクが完了したという証拠ではありません。

それは、単なる別のモデル出力です。

完了は、環境内の観察可能な変更によって決定されなければなりません。

1claim                         evidence
2--------------------------------------------------
3"the bug is fixed"            failing test now passes
4"the page works"              browser flow completed
5"the migration is safe"       dry run and rollback pass
6"the report is correct"       values match source data
7"the task is complete"        every acceptance check passes

ハーネスは、最も安価な決定論的チェックを最初に実行する必要があります。

1syntax
2  -> types
3      -> focused tests
4          -> integration tests
5              -> visual or semantic review
6                  -> human approval

コンパイラ、スキーマ、チェックサム、クエリ、テストで質問に答えられる場合は、別のモデルを使用しないでください。

曖昧さにはモデルを使用します。

配管にはコードを使用します。

モデルはタスクが完了したことを提案できます。

それを証明できるのは環境だけです。

8. 検証は結果を攻撃するべき

ワーカーと評価者は、同じ目的を共有すべきではありません。

ワーカーは、最強のソリューションを作成しようとします。

評価者は、それが拒否されるべき理由を見つけようとします。

1worker
2  -> produces candidate
3
4verifier
5  -> checks contract
6  -> searches for missing cases
7  -> tests unsupported claims
8  -> attempts to break result
9
10survives
11  -> accept
12
13fails
14  -> return targeted evidence

この非対称性は重要です。

同じエージェントに、同じコンテキストで「自分の作業を再確認する」ように依頼すると、多くの場合、間違いを生み出した前提を保持します。

有用な検証段階には、以下が必要です：

• 明示的な拒否ルーブリック
• 生成されたアーティファクトへのアクセス
• 受け入れ契約へのアクセス
• 必要な場合の独立したツールまたは新しいコンテキスト
• 修復せずに拒否する権限

検証は、セカンドオピニオンではありません。

それは、反証の試みです。

9. モデルが提案し、ポリシーが承認する

モデルが覚えているかどうかに依存してはならないルールもあります。

1never publish without approval
2never expose a secret
3never write outside the workspace
4never exceed the spend cap
5never mark tests passed unless they ran

これらはプロンプトの提案ではありません。

それらはポリシーです。

最も安全な設計は、ポリシーを推論ループの外側に保つことです。

1LOW RISK
2read files, search, inspect
3-> automatic
4
5REVERSIBLE CHANGE
6edit workspace, run tests
7-> automatic with trace
8
9EXTERNAL EFFECT
10send message, deploy, purchase
11-> explicit approval
12
13IRREVERSIBLE OR SENSITIVE
14delete data, rotate credentials, publish globally
15-> hard gate or prohibited

結果が強力であればあるほど、ゲートは強固になります。

自律性とは、制御の欠如ではありません。

明確に強制された境界内で自由に動作する能力です。

10. 回復は失敗クラスをターゲットにするべき

最も一般的な回復戦略は次のとおりです：

何かが失敗した。もう一度試す。

それは回復ではありません。

それは繰り返しです。

ハーネスは、次のアクションを選択する前に、失敗を分類する必要があります。

1tool timeout
2-> retry with backoff
3
4invalid arguments
5-> repair the tool call
6
7missing context
8-> retrieve specific source
9
10failed test
11-> inspect failing behavior
12
13permission denied
14-> request approval or choose safe path
15
16contradictory requirements
17-> escalate to human
18
19repeated unchanged failure
20-> stop the loop

リトライは、少なくとも 1 つの関連する条件を変更する必要があります。

そうしないと、システムは同じ失敗を再現するためにお金を払っていることになります。

制限されたエージェントループは次のようになります：

1observe
2  -> decide
3      -> act
4          -> measure
5              -> accept
6              -> repair
7              -> escalate
8              -> stop

すべてのループには予算が必要です：

• 最大試行回数
• 最大時間
• 最大支出
• 最大破壊範囲
• エスカレーション条件

信頼性の高いエージェントは、継続する方法を知っています。

また、継続することがもはや合理的でない場合も知っています。

11. 指示はインフラストラクチャになるべき

エージェントの指示は、ローカルの現実を説明する場合に有用です。

しかし、指示だけでは弱い強制力です。

ルールが繰り返し重要になる場合は、スタックの下位に移動します。

1"use the formatter"
2-> run formatter automatically
3
4"do not import across layers"
5-> add architecture test
6
7"include a migration rollback"
8-> require rollback file in CI
9
10"do not modify generated files"
11-> block writes to generated paths
12
13"cite every external claim"
14-> validate citation coverage

これにより、指示のはしごが作成されます：

1explanation
2  -> checklist
3      -> template
4          -> automated check
5              -> enforced policy

重要な知識を、そのはしごを可能な限り下の方に移動します。

プロンプトは判断を説明する必要があります。

ハーネスは不変条件を強制する必要があります。

12. 最終的な答えだけでなく、実行を観察する

きれいな最終アーティファクトは、ひどいプロセスを隠す可能性があります。

エージェントは以下を行った可能性があります：

• 間違ったデータにアクセスした
• 失敗したコマンドを無視した
• 外部アクションを 2 回リトライした
• 期待される予算の 10 倍を消費した
• 間違った理由で正しい答えに到達した

実行を再構築可能にするトレースが必要です。

109:14  contract created
209:15  context source loaded: architecture.md
309:17  file edited: checkout.ts
409:18  focused test failed: duplicate coupon
509:21  implementation repaired
609:22  focused test passed
709:24  integration test passed
809:25  external deployment blocked: approval required

有用なトレースは以下を記録します：

• 状態遷移
• コンテキストソース
• ツールの入力と出力
• 環境の変更
• 検証結果
• リトライ理由
• 承認決定
• コストとレイテンシ

目標は監視ではありません。

目標はローカルな修復です。

実行がステップ 18 で失敗した場合、タスク全体を再生する代わりに、信頼できるチェックポイントから再開できる必要があります。

13. すべての実行には変更レシートが必要

長いエージェントのトランスクリプトはレビューが困難です。

実行の終わりに、ハーネスは小さな変更レシートをコンパイルする必要があります。

1OBJECTIVE
2Fix duplicate coupon application during checkout.
3
4CHANGED
5- checkout validation logic
6- focused regression test
7
8VERIFIED
9- lint passed
10- unit tests passed
11- checkout integration test passed
12
13NOT VERIFIED
14- production payment provider
15
16DECISIONS
17- preserved existing coupon priority order
18
19RISKS
20- legacy mobile client was not available locally
21
22APPROVAL NEEDED
23- deploy to staging

レシートは、モデルが言ったことの要約ではありません。

それは、システムが証明できることの要約です。

これにより、人間はコンパクトなレビューサーフェスを得られ、次のエージェントセッションは信頼できる開始点を得られます。

最良の引き継ぎは、「これが会話です」ではありません。

「これが状態、証拠、および未解決のリスクです」です。

14. すべての失敗はハーネスをアップグレードするべき

最も弱いチームは、失敗した出力を修正します。

最も強いチームは、それを許容したシステムも修正します。

失敗の後、以下を自問します：

1Was the task contract ambiguous?
2Was important context invisible?
3Was the wrong tool exposed?
4Was a precondition missing?
5Was the result unverifiable?
6Was policy left inside the prompt?
7Was recovery too broad?
8Was the trace insufficient?

そして、教訓を再利用可能な改善に変換します。

1failure
2  -> diagnosis
3      -> new sensor, rule, map, test, or tool contract
4          -> future runs improve automatically

これがハーネスのフライホイールです。

失敗がインフラストラクチャを残すため、システムはより信頼性が高くなります。

修正された答えは、1 回の実行に役立ちます。

修正されたハーネスは、将来のすべての実行に役立ちます。

15. ハーネスも劣化する

より多くのハーネスが常に良いとは限りません。

モデルは改善されます。ツールは改善されます。タスクは変わります。古いセーフガードは、不要な摩擦になる可能性があります。

昨日のモデルのために作成された回避策は、今日のモデルがより良い戦略を使用するのを妨げる可能性があります。

これにより、ハーネスの劣化が発生します：

1old model limitation
2  -> harness workaround
3      -> model improves
4          -> workaround remains
5              -> system becomes slower or less capable

ハーネスコンポーネントをプロダクションコードのように扱います。

それらがまだ価値を提供しているかどうかを測定します。

すべてのルーター、評価者、メモリレイヤー、リトライルールについて、以下を自問します：

• これはどの失敗を防ぐのか？
• その失敗はどのくらいの頻度で発生するのか？
• これによりどのようなレイテンシと複雑さが追加されるのか？
• 同じ結果をより簡単に達成できるようになったか？
• これを削除するとどうなるか？

最良のハーネスは、最大のものではありません。

意図と証拠の間のギャップを確実に埋める最小のシステムです。

削除するために構築します。

16. 最小実行可能ハーネス

開始するためにオーケストレーションプラットフォームは必要ありません。

ハーネスをレイヤーで構築します。

レベル 1: 制限されたタスク

• 目的
• スコープ
• 制約
• 受け入れチェック

レベル 2: 読みやすい環境

• プロジェクトマップ
• コマンド
• ローカル指示
• 既知の依存関係

レベル 3: 制御されたアクション

• 型付けされたツール
• 引数の検証
• パスと権限の境界
• 構造化された結果

レベル 4: 永続的な実行

• 明示的な実行状態
• チェックポイント
• 決定
• 教訓

レベル 5: 証拠

• 決定論的チェック
• 敵対的検証
• 変更レシート

レベル 6: 回復と学習

• 失敗の分類
• 制限されたリトライ
• エスカレーション
• 繰り返し発生する失敗からのハーネス更新

実際に発生している失敗を排除する最小のレイヤーを構築します。

単一のプロンプトが時折明確化を必要とするからといって、マルチエージェントアーキテクチャから始めないでください。

複雑さは、観察された失敗によって獲得されるべきです。

17. 再利用可能なハーネス仕様

エージェントに意味のある自律性を与える前に、以下を定義します：

1AGENT HARNESS SPEC
2
31. CONTRACT
4   objective:
5   scope:
6   constraints:
7   acceptance evidence:
8
92. CONTEXT
10   always-loaded map:
11   retrieval sources:
12   local instructions:
13   freshness rules:
14
153. TOOLS
16   allowed tools:
17   preconditions:
18   side effects:
19   success evidence:
20   timeout and retry policy:
21
224. STATE
23   facts:
24   decisions:
25   progress:
26   lessons:
27   checkpoint format:
28
295. POLICY
30   automatic actions:
31   approval-required actions:
32   prohibited actions:
33   budget limits:
34
356. VERIFICATION
36   deterministic checks:
37   adversarial checks:
38   acceptance rule:
39
407. RECOVERY
41   failure classes:
42   retry limits:
43   escalation conditions:
44   safe rollback:
45
468. OBSERVABILITY
47   trace events:
48   metrics:
49   final change receipt:

これらのフィールドが未定義の場合、エージェントは自律的ではありません。

それは即興です。

18. 適切なレベルでシステムを測定する

トークン数は最終的な指標ではありません。

試行されたタスクの数でもありません。

有用な単位は、受け入れられた作業です。

実用的な指標は次のとおりです：

1accepted outputs
2------------------------------
3human review minutes + run cost

また、以下も追跡します：

• 初回合格率
• ツール失敗後の回復率
• 繰り返し失敗率
• タスクあたりの人間の介入回数
• サポートされていない完了の主張
• リクエストから検証済み結果までの時間
• コンポーネント別のハーネスオーバーヘッド

これにより、一般的な幻想を防ぎます：

エージェントは、高額なレビュー作業を生み出しながら、非常に生産的に見える可能性があります。

目標は、より多くのエージェント活動ではありません。

それは、人間の注意の単位あたりの、より信頼性の高い成果です。

19. 重いハーネスが不要な場合

すべてのモデル呼び出しにオペレーティングシステムが必要なわけではありません。

以下の場合は、シンプルなプロンプトを使用します：

• タスクが短い
• 出力が検査しやすい
• 失敗が安価
• 外部への副作用がない
• ユーザーがループ内にいる

以下の場合は、ハーネスを追加します：

• 作業が複数のツールまたはセッションにまたがる
• 環境が変更される可能性がある
• アクションに実際の結果が伴う
• 完了を手動で判断するのが難しい
• 同じ失敗が繰り返し発生する
• 人間によるレビューがボトルネックになる

ハーネスの目的は、デモを洗練されたものに見せることではありません。

実際の作業を信頼性の高いものにすることです。

本当の変化

AI 製品の第一世代は、プロンプトを中心に構築されました。

次の世代は、環境を中心に構築されています。

もはや質問は次のものだけではありません：

モデルの回答をより良くするにはどうすればよいか？

それは次のとおりです：

良いアクションは簡単に、危険なアクションは制御され、失敗は可視化され、完了は証明可能なシステムをどのように構築するか？

それが、プロンプトエンジニアリングからハーネスエンジニアリングへの移行です。

モデルは知能を提供します。

ハーネスは構造を提供します。

それらが一緒になって、信頼性の高い実行を生み出します。

エージェントが何度も壊れる場合は、プロンプトに形容詞を追加するのをやめてください。

成功するために必要な環境を構築してください。

ここまで読んだ方へ

このガイドをブックマークしてください。

X で @LunarResearcher をフォロー

私の Substack を購読する

この記事を、まだすべてのエージェントの失敗をより長いプロンプトで修正しようとしている人に送ってください。