AIに「次は気をつけて」と言い続けない。ハーネスエンジニアリングの基本と実践
AIが同じミスを繰り返すなら、注意書きより先に作業環境を見直して整備した方がいい。ハーネスエンジニアリングの基本を、Codexで実践した事例と2026年7月時点の資料から徹底解説します。
AIエージェントに「次は気をつけてね」が効かない理由
Claude CodeやCodexを使っていると、同じ注意を何度も書きたくなる場面があります。
「テストを実行してから報告してほしい」
「そのファイルは触らないでほしい」
「前回と同じ方法は失敗したので、もう試さないで別の案を出してほしい」
僕も、こうした一文をプロンプトへ足してきました。ですが、注意書きを増やしても、同じセッション、別のセッションではまた同じ失敗が起きます。
コンテキストウィンドウは、その場の作業机であって、プロジェクトの記憶ではないからです。
ここで直すべきなのは、AIモデルへの指示ではありません。テストを通さなければ完了にできない仕組み、変更してよいリポジトリ範囲の明示、過去の失敗ログを残す場所、危険な操作の前で止める権限設計が足りていないということです。
このAIモデルの外側で、AIモデルが仕事を進めやすい環境を作る技術がハーネスエンジニアリングです。
ハーネスはモデルの外側にある作業環境
AIエージェントへ仕事を任せるには、モデルとプロンプトだけでは足りません。
どの情報を読み、どのツールを使い、どこまで変更し、何をもって完了とするかを決める仕組みが必要です。
この記事で扱うハーネスエンジニアリングは、次の意味があります
AIエージェントが仕事を安全かつ再現可能に進められるよう、目的、知識、ツール、権限、状態、評価、復旧、観測をモデルの外側に設計すること。
ハーネスエンジニアリングへ言及している、オブジェクト指向設計などのソフトウェアアーキテクチャで知られるMartin Fowlerの記事では、エージェントを広く「モデル + ハーネス」と捉えています。
thinkingmachines.aiのリリアンウェンの整理も、実行、計画、ツール利用、コンテキスト、成果物の保存、評価を制御するモデル周辺のシステムをハーネスと呼んでいます。
ハーネスは、AIに長い説明書を読ませる工夫だけを指す言葉ではなく、モデルが仕事を始め、途中の状態を残し、結果を確かめ、失敗から戻るまでの作業環境全体を扱います。
OpenAIが紹介したハーネスエンジニアリング開発事例でも、人間の仕事は、コードを一つひとつ書くことから、エージェントが作業できる足場や制約、検証環境を用意することへ移っています。
エージェントが詰まったとき、指示を言い換えるだけでは足りず、AIからは何が見えていて、どのツールが足りなかったのか、なぜ誤りを検出できなかったのかを調べられるよう、見つけた不足している要素をリポジトリへ反映し、次の実行から使えるようにする考え方です。
プロンプト、コンテキスト、ループとの違い
ハーネスエンジニアリングは、プロンプトエンジニアリングを言い換えたものではありません。
それぞれが扱う対象を分けると、違いが見えます。
| 領域 | 扱う対象 | 中心となる問い | 成果物 |
|---|---|---|---|
| プロンプトエンジニアリング | 依頼文 | どう頼むか | 目的に合う応答 |
| コンテキストエンジニアリング | 作業中に見せる情報 | 何を読ませ、何を省くか | 仕様に沿った応答 |
| ハーネスエンジニアリング | モデル外部の作業環境 | 何を使わせ、どう検証し、どこで止めるか | 検証済みの実行結果 |
| ループエンジニアリング | 継続実行の仕組み | どう再実行し、いつ止めるか | 継続して積み上がる成果 |
プロンプトとコンテキストは、ハーネスの中で使う部品で、ループは、整えたハーネスの上で実行を繰り返す仕組みにあたります。
ハーネスが弱いままループだけを回すと、誤った変更や重複した成果物が速いペースで増え続けてしまい、人間からすると、望んでいない成果物が目視で確認すること自体に嫌気がさしてきます。
ハーネスエンジニアリングは、まず一回の仕事を安全に終えられるようにする。そのあとでループエンジニアリングで継続実行を設計する、という順番です。
プロンプトエンジニアリング、コンテキストエンジニアリング、ループエンジニアリングは、それぞれ別の記事で詳しく扱っています。
ハーネスエンジニアリング実践前の「エラーをなくして」が効果をもたらさないことを痛感
僕がCodex用のハーネスを組んだ実例として、公開プロフィール情報を収集し、SQLiteデータベースへ保存するプロジェクトがあります。ある店舗の公式サイトから公開情報を取得し、決められた項目へそろえて保存する数百万件のデータを管理するプロジェクトです。
対象データの構造は統一されておらず、詳細なデータを持つ場合もあれば、存在していない場合もあり、一つ一つの店舗データを人の目で確認して毎回AIへ指示を出すのは骨が折れる作業です。
当初プロジェクト開始時点の問題は、データを取得できているのにSQLiteへ格納するデータを1件も抽出できないパターンがあることでした。
ここで「エラーを0件に抑えながら、全部正確にSQLiteへ格納して」とだけAIへ指示をすると、AIエージェントは数値を下げること自体を目標にしてしまいかねません。
これは一見するとエラー数値を下げることはゴールへ近づくようにも思えます。なぜなら、店舗名、キャンペーン名、料金、ナビゲーションまで拾えば、見かけ上の0件は減るからです。ですが、これはゴールから遠ざかっているプロンプトで、1日経っても進捗は改善せず、格納できないデータ抽出パターンは改善されないままでした。
必要だったのは抽出件数を増やす指示よりも、AIが解釈しやすい抽出の正しい条件と、データベースへ格納したいデータの基準でした。
そこで、人間が頭の中で行っていた判断を、リポジトリ内の文書とスクリプトへ分ける対応をしました。
メインで使っていたのがCodexだったためAGENTS.mdを用いています。
| 置き場所 | 担う役割 |
|---|---|
AGENTS.md | 短い依頼を正式なタスクへ変え、変更範囲、禁止事項、完了条件を示す |
SKILL.md | 監査から再監査までの作業順を固定する |
CONTRACT.md | 正しいデータ構造、誤抽出、0件にしたい理由を定義する |
| 監査スクリプト | 0件の原因を分類する |
| fixtureテスト | 保存した入力例を使い、HTML構造ごとの抽出結果を固定する |
| 品質ゲート | SQLite再構築後の件数と悪化の有無を判定する |
一回の実行で直すのは、一種類のHTML構造だけです。
店舗ごとの例外は増やすことではなく、JSON内のデータといった構造単位で、再利用できる抽出処理を追加していきます。
修正には、その構造を再現した保存用の入力例（fixture）を使うテストを付けます。
保存済みHTMLを使えば、パーサーだけを直したときも、同じ入力条件で結果を再現できます。
Codexの作業手順は、次のようになりました。
- SQLiteを監査し、0件の理由を分類する。
- 修正可能で影響の大きいHTML構造を一種類選ぶ。
- 保存済みHTMLからfixtureを作る。
- 再利用できる抽出処理を実装し、テストする。
- 取得済みページから正規化テーブルを再構築する。
- 監査をやり直し、変更前後の数値を比べる。
- 品質ゲートを通った場合だけ完了として報告する。
停止条件は、キューが空になったことではありません。
抽出したいデータがあるのに抽出できない店舗がなくなったとき、または残る0件を「取得失敗」「公式URLなし」「人間の確認が必要」など、パーサー以外の理由に分類できたときに止めます。
2026年6月にハーネスエンジニアリングを導入して実行した結果、品質ゲートでは、修正可能な0件が1件から0件になり、プロフィール総数は107,008件から107,019件へ増え判定はpassです。
これは現在値ではなく、僕のプロジェクト内に残した一回の実行結果です。
最終的な成果としては、ハーネスエンジニアリング導入前のデータ抽出から格納までの成功率は32%だったのが、ハーネスを導入したことで89%にまで成功確率を上げ、プロジェクトを完了させられたことです。残りのパーセントはそもそもデータ抽出が不可能だったので切り捨てました。
このハーネス導入の結果、僕の指示はほとんど不要になり、AIエージェントが自律的に動作する環境を整えることで、AIが理解してくれないというよくある勘違いを脱することができました。
これは判断をCodexへ丸投げしたわけではなく、正しいデータ定義は契約へ、作業順はSkillへ、現状把握は監査へ、合否は品質ゲートへ移したからこそ、ハーネスエンジニアリングの効果を実感できました。
仕事の境界と知識の入口を作る
実践で最初に効いたのは、タスクの境界と判断基準をAIモデルの外へ移したことでした。
成果物、完了条件、停止条件が書かれていれば、エージェントは「どこまで進めれば終わりか」を推測せずに済みます。
先にタスク契約を置く
エージェントへ「何をするか」だけを渡すと、完了の解釈がモデル任せになります。
そこで、実装方法より先に、仕事の境界をタスク契約として置きます。
## Goal
何を達成するか
## Scope
どこまで変更してよいか
## Non-goals
今回は何をしないか
## Required artifacts
どの成果物を残すか
## Definition of done
何を満たせば完了か
## Stop conditions
どの状態で停止するか
## Escalation
何を人間へ戻すか
## Limits
最大試行回数、時間、コスト
実装手順まで細かく決めすぎる必要はありません。最初に決めた手順が間違っていれば、そのまま後工程まで引きずるからです。成果物と制約、合否条件は明確に定めつつ、AIの実現方法には選択の余地を残します。
長時間タスクでも、一度に扱う対象を一機能、一種類の修正、一つの成果物まで絞ると、失敗の原因と変更の効果を追いやすくなります。
Anthropicの長時間タスク向けハーネスも、一度に小さな進捗を残し、次のセッションへ引き継ぐ構成を採っています。
AGENTS.mdはなんでも詰め込めばいいわけではなかった
プロジェクトのルールを毎回プロンプトへ書く代わりに、CodexならAGENTS.md、Claude CodeならCLAUDE.mdを入口にできます。
ただし、そこへすべての知識を詰め込むと、AIエージェントがすべてを認識することは難しくなります。
OpenAIの事例では、AGENTS.mdを短い目次として使い、設計、セキュリティ、品質基準、進行中の計画を別の文書へ分けています。
エージェントは入口だけを読み、タスク進行に必要な資料は、必要になったときにコンテキストへ格納してくれます。
AGENTS.md
docs/
├── PRODUCT.md
├── ARCHITECTURE.md
├── RULES.md
├── DEFINITION_OF_DONE.md
├── SECURITY.md
└── plans/
└── current-plan.md
skills/
└── task-name/
└── SKILL.md
必要なときだけ読み込む作業手順書がSkillです。
会話で繰り返していた判断基準を、リポジトリに置いた契約と手順へ移せば、短い指示でも同じ作業順を再現できます。
ドキュメントは置くだけでは古くなります。リンク切れや必須項目の欠落、実装との不一致をCIや定期チェックで検出し、実行コードと同じように保守する必要があります。
実行を選びやすくし、結果を検証する
知識を渡しただけでは、AIエージェントは仕事を完了できません。次に必要なのは、迷わず使えるツールと、飛ばせない品質ゲートです。
ツールは数より選びやすさ
AIエージェントへ渡すツールを増やしても、使える能力が同じ割合で増えるわけではありません。
役割が似たツールが並ぶと、どれを選ぶか迷いやすくなります。引数や結果の読み取りにも失敗しやすく、ツールの説明だけでコンテキストを消費します。
よいツールは、よく使う価値の高い操作を、一つの明確な役割として担います。全件を返すlist_all_recordsより、条件とページ番号を受け取るsearch_recordsの方が、必要な情報へ早く到達できるからです。
エラーメッセージも、Invalid requestだけでは復旧に使えません。
status は draft、approved、archived のいずれかです。
現在値: active
許可される値と現在なにが起こっているのか分かれば、エージェントは同じ失敗を繰り返さずに修正ができます。
Anthropicのツール設計ガイドが勧めているのも、実際のタスクを使った評価でツールを改善することです。
機械で正否が決まるものは、AI推論を使わずにコード側で止める
JSONの形式、型、テスト結果、ファイルの有無には、機械的に決まる正解があります。
これらを「必ず確認して」とプロンプトへ書くだけでは、確認を飛ばす余地が残ってしまうため、機械的に判定できる品質は、コードで強制します。
| 確認対象 | 適した方法 |
|---|---|
| JSON形式 | スキーマ検証 |
| コードの動作 | テスト |
| 型 | 型チェック |
| 依存方向 | 構造テスト |
| 禁止API | リンター |
| 重複 | DB制約 |
| 必須ファイル | プログラムによる検査 |
| 金額上限 | コード上のルール |
| 必須ツールの使用 | 実行履歴の検査 |
文章の分かりやすさやUIの自然さ、調査の十分さには、数式のような一つの正解がありません。
こうした項目は、基準を定めたモデル評価や人間評価で扱います。
Martin Fowlerの記事では、機械で答えが決まる検査を計算処理型のComputational Controls、推論が必要な評価を推論型のInferential Controlsと呼び分けています。
まず機械的な検査を通し、意味評価が必要な範囲だけAI推論を使う設計です。
成果物に加えて、環境の最終状態も確認します。
フロントエンドならページを開き、ボタンを押し、送信後の画面やAPIの状態まで見る必要があります。
業務エージェントが「予約した」と報告したら、採点すべきなのは、自信ありげな報告文ではなく、予約データベースに期待したレコードがあるかどうかです。
操作範囲と人間へ戻す境界を分ける
エージェントがシステム上で操作できる範囲を決める仕組みがサンドボックスです。
その範囲内でも、実行前に人間の判断を求める操作は承認ゲートで止めます。
両者へ最小権限と安全な認証情報管理を組み合わせます。
| 操作 | 扱い |
|---|---|
| 読み取り、検索、テスト | 原則として自動 |
| 下書き、作業領域内の変更 | 制限付きで自動 |
| PRやチケットの作成 | 条件付き |
| 公開、送信、削除 | 人間の承認 |
| 本番DB、課金、広告予算 | 強い承認 |
| 認証と権限の変更 | 原則として人間が判断 |
OpenAIの安全設計も、通常作業を境界内で進め、サンドボックス外の操作や高リスク操作で承認を求める構成です。
2026年7月17日時点のMCPの認可仕様（draft）でも、最初から広い権限を渡さず、必要になった時点で追加する段階的な認可が推奨されています。
操作を、元に戻せるかどうかと影響範囲で分類すると、承認条件を決めやすくなります。
状態ログを残し、次の改善へつなげる
一回の仕事を正しく終えるだけなら、ここまでの仕組みでも動きます。
ですが、長時間タスクや定期実行では、次のセッションが迷わず再開できる状態ログと、失敗の原因を追える履歴が必要です。
チャットはプロジェクトの記憶にならない
チャット履歴だけに状態を置くと、コンテキストの圧縮やセッションの切り替えで、失敗した方法と次の一手が抜け落ちます。
そこで、次の情報をMarkdown、JSON、SQLite、Git、Issue管理などへ保存します。
- 現在の目標と未完了の仕事
- 完了した仕事と成果物へのリンク
- 試した方法と失敗理由
- 次に行う操作
- 検証結果
次の実行が引き継げる形で、上記のようなログを残すことが目的です。
よい終了条件には、成果物の保存、状態ファイルの更新、検証結果の記録、作業環境に問題がないことの確認まで含まれます。
ログより一連の仕事を残す
一般的なシステムログからは、エラーの発生時刻を追えても、AIエージェントが何を読み、なぜその操作を選んだのかまでは分かりません。
そこで、依頼から最終状態までの一連の実行履歴を、一つの**トレース(形跡)**として残します。
トレースには、参照した資料、呼び出したツールと引数、結果、承認と拒否、変更したファイル、評価結果、実行時間を含めます。必要なら使用トークンやリトライ回数も記録します。
初回成功率、リトライ回数、ツールエラー、人間の介入、過去の失敗の再発率まで追えば、ハーネスが仕事を軽くしたのか、裏で修正を増やしただけなのかを判断でき、改善を自律的に行えるようになります。
ここで見落としがちなのは、最大ターン数とリトライ回数、実行時間、コスト上限で、上限なしで同じ操作を繰り返せば、自立実行環境を整えたつもりがAIが暴走してしまい、いつのまにか利用量がなくなってしまうか、API利用が爆発してしまいますので注意です。
先に合否を決めてからハーネスを変える
ハーネスを変更したあと、感覚だけで良し悪しを決めても、改善と改悪を区別できません。
先に評価タスクを用意し、その結果を見ながらハーネスを変える手法を**評価駆動開発（eval-driven development）**と呼びます。
評価セットには、正常ケースに加えて、過去に失敗したケース、権限不足、ツール障害、重複実行、中断からの再開を入れます。
形式や最終状態はコードで、意味や自然さはモデルで、専門判断や高リスク領域は人間が評価します。
Anthropicのエージェント評価ガイドでは、証拠が足りないときにUnknownを返せる評価基準も勧めています。もっともらしい推測を合格にしてしまう誤判定を減らすためです。
作るエージェントと評価役を分ける方法は、主観的な品質や長時間タスクで役立つことがあります。
ただし、最初からすべての仕事へ独立した評価役を置く必要はありません。
まずは単一エージェントの成果を、機械的な品質ゲートで評価します。
それだけでは足りないと確認できた場面に限って、独立した評価役を追加します。
複数エージェントも、仕事を独立して分けられ、並列化の効果が結果をまとめる手間を上回るときだけ使います。
ハーネスエンジニアリングを最小構成から始める
2026年7月時点の資料を読み比べて、僕が最初に押さえたいと感じたのは「大きく始めない」ことでした。
Anthropicも、単純な構成で不足を確認してから徐々に複雑さを足すことを勧めています。
次の順番で作りはじめるのが現時点では最適解だと思います。
AGENTS.mdへ目的、変更範囲、完了条件、停止条件を書く。- 現状を同じ方法で測れる監査を作る。
- 機械で決まる合否を、一つの品質ゲートへまとめる。
- 繰り返す作業をSkillへ移す。
- 過去の失敗を回帰評価へ入れる。
- 状態と実行履歴を外部ファイルとして状態を保存する。
- 外部へ影響する操作に、サンドボックスと承認条件を付ける。
- 評価で必要性を確認してから、独立した評価役や複数エージェントを足す。
これは、複雑さを一段足すたびに、「その複雑さでしか解けない問題があるか」を確かめるための順番です。
まずはAGENTS.mdと監査を追加するだけでも、人間の毎回する説明と手作業は減ります。
いきなりMCPや複数エージェントから始めると、できる操作は増えても、正しさの基準は定まらないので注意です。
ハーネスは足すだけでなく削る
ハーネスのツールには、「モデルはこの作業を自力ではできない」という仮定が埋め込まれています。
モデルが変われば、その仮定も変わってしまうからです。
以前のモデルには必要だった細かな計画や過度な自己確認、コンテキストのリセット、サブエージェントも、新しいモデルでは動作を遅くすることがあります。
Anthropicも、以前は有効だったコンテキストリセットが、モデルの更新後には不要な負荷になった事例を報告しています。
失敗のたびに部品を足していけば、ハーネスは重くなる一方です。
同じ評価セットを定期的に実行し、外しても品質が落ちない仕組みは削ります。
「過去に必要だった」は、残し続ける根拠にはならないため、中長期プロジェクトではモデル更新があればハーネスの品質面をテストする必要があり、そのためにも最小構成でハーネスを構築するのがよいと思います。
同じ失敗を仕組みへ戻す
ハーネスエンジニアリングは、AIへ仕事を丸投げする技術ではありません。
人間が持っている判断基準、禁止事項、検証条件、停止条件を、エージェントが参照でき、システムが強制できる形へ移す技術です。
エージェントが失敗したら、次のプロンプトへ注意書きを足す前に、原因を分けて考えていくとよいです。
- AIが見えていなかった情報は何か
- 曖昧だった契約はどれか
- 使いにくかったツールは何か
- 足りなかった検査はどれか
- 広すぎた権限はどこか
- 残らなかった状態は何か
- どこから復旧できなかったか
答えが見つかったら、短い入口文書、ツール、テスト、権限、状態、実行履歴のいずれかへ戻ってまたテスト。正直、地味な作業の繰り返しです。
AIが正しい行動を取りやすく、危険な行動は取りにくくする。そして、失敗と成功の両方を確かめられる作業環境を作る。
それが、ハーネスエンジニアリングを実践してわかったポイントです。
ぜひハーネスエンジニアリングへ取り組んで、そのインパクトを体感してみてください。
それではまた！
情報元
- Harness engineering: leveraging Codex in an agent-first world | OpenAI
- Running Codex safely at OpenAI | OpenAI
- Building effective agents | Anthropic
- Effective harnesses for long-running agents | Anthropic
- Harness design for long-running application development | Anthropic
- Writing effective tools for AI agents | Anthropic
- Demystifying evals for AI agents | Anthropic
- Scaling Managed Agents | Anthropic
- Harness engineering for coding agent users | Martin Fowler
- Authorization | Model Context Protocol
- Harness Engineering for Self-Improvement | Lil'Log