ハーネスエンジニアリングとは？定義と設計の型を解説

ハーネスエンジニアリングは、AI エージェントの「モデル以外の部分」を設計する仕事です。指示ファイル、ツール、リンター、テスト、レビュー、進捗の記録方法といった、モデルを包んで働かせる仕組み全体をハーネスと呼び、それを意図して組み立てることを指します。この記事では、OpenAI・Thoughtworks・Anthropic がそれぞれ公開した一次情報をもとに定義の違いを整理し、ハーネスを構成する要素の分け方、長時間タスク向けの設計例、そして自分のチームで始めるときの順番を解説します。

ハーネスエンジニアリングとは何か：3 つの一次情報の定義

ハーネス（harness）は馬具や安全帯を指す語で、ソフトウェアの分野では以前から「テストハーネス」のように、対象を包んで動かす枠組みの意味で使われてきました。AI エージェントの文脈でこの語を扱った記事のうち、現在の議論で最も多く引用されているのは、OpenAI が 2026 年 2 月 11 日に公開したエンジニアリングブログです。同じ月に Thoughtworks の Birgitta Böckeler 氏が martinfowler.com でコーディングエージェント利用者向けのハーネスエンジニアリングを公開し（初出 2026 年 2 月 17 日、4 月 2 日に改訂）、Anthropic も 2025 年 11 月から「ハーネス」を主題にした記事を続けて出しています。3 者の定義は重なりますが、力点が違います。

Agent = Model + Harness という整理

Böckeler 氏の記事は、ハーネスを「AI エージェントからモデルを除いた残りすべて」と定義します。モデル単体は入力に対して出力を返すだけで、ファイルを読む、コマンドを実行する、結果を確かめる、といった動作はモデルの外側にある仕組みが担います。エージェントの振る舞いのうち、モデルの重みに由来しない部分はすべてハーネスが決めている、という見方です。

Anthropic の説明も同じ構図で、claude.com のブログはエージェントハーネスを「ループ、ツール、コンテキスト管理、ガードレールからなる、モデルの周りのソフトウェアの足場」と表現しています。Claude Code の内部で動くこの足場は、2025 年 9 月に Claude Agent SDK として切り出されました。

内側のハーネスと外側のハーネス

コーディングエージェントを使う立場では、ハーネスは 2 層に分かれます。Böckeler 氏は、システムプロンプトやコード検索の仕組みのように製品に組み込まれた部分と、利用者が自分のシステム向けに構築する「外側のハーネス」を区別しています。

ハーネスエンジニアリングの記事や議論で対象になるのは、ほとんどが利用者側の外側のハーネスです。以降もこの層を中心に扱います。内側のハーネスを含めた製品側の考え方は、コーディングエージェントに模範的な開発フローを強制する OSS「Superpowers」の記事で「ビルダーハーネス」「アウターハーネス」として整理しています。

OpenAI の実験が示したこと：エンジニアの仕事は環境設計に移る

OpenAI の記事は、手書きコードを 1 行も書かずに社内向け製品を作る 5 か月間の実験報告です。数字が具体的なので、ハーネスエンジニアリングが何を変えるのかを読み取る材料になります。

記事が繰り返し述べているのは、初期の進みが遅かった原因は Codex の能力ではなく環境の定義不足だった、という点です。人間のエンジニアの仕事は「どの機能が不足しているのか、それをエージェントにとって理解可能かつ実行可能にするにはどうすればよいのか」を問い続けることになった、と書かれています。

AGENTS.md を目次にして知識は docs/ に置く

同じ記事で失敗例として挙がるのが、1 つの大きな AGENTS.md にすべてを書く方法です。コンテキストが圧迫されて重要な制約が落ちる、すべてが「重要」だと何も重要でなくなる、マニュアルはすぐ腐る、機械的に検証できない、という 4 つの理由で失敗したと記されています。

その代わりに採られたのが、約 100 行の短い AGENTS.md を目次として置き、知識の本体は構造化された docs/ ディレクトリに置く構成です。設計ドキュメント、実行計画、生成物、製品仕様、参照資料を分け、専用のリンターと CI で相互参照と鮮度を検証し、定期実行のエージェントが古くなったドキュメントを直すプルリクエストを開きます。ドキュメントも「書けば守られる」のではなく、機械的に検証される対象として扱われているのが特徴です。

制約はドキュメントよりリンターで守る

アーキテクチャの一貫性については、ドキュメントだけでは保てない、と記事は断言しています。各ドメインを固定されたレイヤーに分け、依存の方向をカスタムリンターと構造テストで機械的に検証します。カスタムリンターのエラーメッセージには修復手順を書き込み、エージェントのコンテキストに直接注入します。人間中心のワークフローでは細かすぎると感じられるルールが、エージェント相手では一度書けばあらゆる場所に同時に適用される「増幅器」として働く、という指摘です。

もう 1 つ印象的なのが「ガベージコレクション」の節です。当初、チームは毎週金曜日（週の 20%）を AI が生み出した粗いコードの後始末に費やしていました。それをやめ、「黄金の原則」をリポジトリに書き込み、逸脱の検出とリファクタリングのプルリクエスト作成を定期実行のバックグラウンドタスクに任せています。技術的負債を高金利のローンにたとえ、まとめて返済するより毎日少しずつ返す方が賢明だ、と述べています。

なお記事は末尾で、単一のプロンプトから設計・修正・検証・マージまで通す動作は「このリポジトリの特定の構造とツールに大きく依存しており、同様の準備なしに一般化できると考えるべきではない」と注意を添えています。数字だけを切り取って自社に当てはめるのは避けたほうがよさそうです。

ハーネスエンジニアリングの構成要素：ガイドとセンサー、計算と推論

Böckeler 氏の記事は、ハーネスを構成する制御を 2 つの軸で分類しています。自分のチームがすでに持っている仕組みを棚卸しするときに、この 2 軸の表が使えます。

1 つ目の軸は「いつ働くか」です。

• ガイド（フィードフォワード）: エージェントが動く前に振る舞いを方向づける。指示ファイル、ルール、テンプレート、スキル、スクリプト。最初の試行で良い結果が出る確率を上げる
• センサー（フィードバック）: エージェントが動いた後に結果を観測し、自己修正させる。テスト、リンター、型検査、AI レビュー。LLM が読みやすい形で信号を返すほど自己修正が進む

2 つ目の軸は「誰が実行するか」です。

• 計算的（computational）: 決定的で速い。CPU で動くテスト、リンター、型検査、構造解析
• 推論的（inferential）: 意味を扱う。LLM によるコードレビュー、LLM-as-a-Judge。遅く確率的だが、計算では拾えない観点を返せる

この 2 軸を組み合わせると、次の 4 象限になります。

Böckeler 氏はさらに、ハーネスが何を制御するかを 3 つに分けています。コード品質や複雑さを扱う保守性のハーネスがいちばん作りやすく、性能や可観測性を扱うアーキテクチャ適合性のハーネスがその次、機能が正しく動くかを扱う振る舞いのハーネスが最も難しい、という順序です。振る舞いのハーネスは現状、エージェントが生成したテストの品質に頼りすぎており未解決だ、と率直に書かれています。

記事の結びに近い一文が、ハーネスの目的をよく表しています。

A good harness should not necessarily aim to fully eliminate human input, but to direct it to where our input is most important.

（良いハーネスは、人間の入力を完全になくすことを目指すのではなく、人間の入力が最も重要なところへそれを向けるべきである。出典: Birgitta Böckeler, martinfowler.com）

長時間タスクのハーネス：Anthropic の設計例と失敗パターン

Anthropic の 2 本の記事は、数時間にわたるタスクをエージェントに完走させるためのハーネスを扱っています。対象が「エージェントがコンテキストウィンドウをまたいで進捗を維持する仕組み」に絞られているので、OpenAI の記事とは別の角度からハーネスの中身が見えます。

進捗ファイルと機能リストで、コンテキストをまたぐ

2025 年 11 月 26 日のEffective harnesses for long-running agentsでは、最初のセッションだけ別のプロンプトで動く「初期化エージェント」が、開発環境を起動するスクリプト、作業履歴を残す進捗ファイル、最初の git コミットを用意します。以降のセッションは進捗ファイルと git ログを読み、未完了の機能を 1 つ選んで実装し、テストし、コミットし、進捗を更新して終わります。

機能一覧は JSON で管理し、200 件を超える機能を最初はすべて「失敗」として並べておきます。テストを削除・編集してはいけない、という指示を強い言葉で書いているのは、そうしないと機能の欠落やバグを見逃すためです。記事が挙げる失敗パターンは、エージェントが一度にやりすぎてアプリを一発で作ろうとすることと、新しいコンテキストで作業の状態を素早く把握できないことでした。

生成と評価を分け、コンテキストをリセットする

2026 年 3 月 24 日のHarness design for long-running application developmentでは、役割が 3 つに分かれます。短い依頼を製品仕様に展開するプランナー、機能を少しずつ実装するジェネレーター、ブラウザ自動化でユーザーと同じように触って採点するエバリュエーターです。ジェネレーターとエバリュエーターは実装前に「何をもって完了とするか」を合意し（スプリント契約）、エージェント間の受け渡しはファイル経由で行います。

この記事で観測された失敗パターンは 2 つあります。1 つは、コンテキストの上限が近いと感じたモデルが作業を早めに切り上げてしまう「コンテキスト不安」で、要約ではなくコンテキストの完全なリセットと構造化された引き継ぎで対処しています。もう 1 つは、自分の成果を品質にかかわらず高く評価してしまう「自己評価バイアス」で、作る側と判定する側のエージェントを分けることが強い対策になったと述べています。

コストも公開されています。単独実行なら 20 分・9 ドルで終わるタスクが、ハーネスを組んだ最初の構成では 6 時間・200 ドルかかり、改良後は 3 時間 50 分・124.70 ドルになりました。ハーネスは品質を上げる代わりに時間と費用を増やすので、どこまで組むかはタスクの価値との釣り合いで決めることになります。

ハーネスは減らす方向にも設計する

同じ記事の次の一文は、ハーネスを組む前に読んでおきたいものです。

Every component in a harness encodes an assumption about what the model can't do on its own, and those assumptions are worth stress testing.

（ハーネスのすべての構成要素は「モデルが単独ではできないこと」についての仮定を埋め込んでおり、その仮定はストレステストする価値がある。出典: Anthropic Engineering）

モデルが更新されるたびに、ハーネスのどの部品がまだ必要かを確かめ、不要になったものを外す。claude.com のブログも、ハーネス設計とは「何を足場に入れるか、そしてモデルが進歩したときに何を取り除けるかを決めること」だと書いています。足せば足すほど良いものではない、という前提で設計します。

ハーネスエンジニアリングとコンテキストエンジニアリングの違い

「プロンプトエンジニアリング」「コンテキストエンジニアリング」「ハーネスエンジニアリング」は、どれもモデルの外側で品質を上げる営みです。対象と時間軸で分けると位置づけがはっきりします。

コンテキストエンジニアリングは、ハーネスの中でも「ガイド」側、つまりモデルに渡す情報の設計に相当します。ハーネスエンジニアリングはそれに加えて、動いた後の観測（センサー）と、観測結果を次の実行に戻す経路まで含みます。OpenAI の記事で docs/ ディレクトリをリンターと CI で検証しているのは、コンテキストの鮮度そのものをセンサーで守っている例です。コンテキストの設計そのものはコンテキストエンジニアリングの記事で扱っています。

Agent Skills や MCP との関係も同じ見方で整理できます。スキルは手順を必要なときだけ読み込ませるガイドの部品、MCP はツールとデータへの接続口で、どちらもハーネスの構成要素です。ハーネスエンジニアリングは、それらを組み合わせて 1 つの制御系にする仕事だと言えます。

gaipack のハーネスエンジニアリング：AGENTS.md・SKILL.md・評価ループ

gaipack が受託開発の現場で運用している AI 駆動開発（AIDD）の環境も、上の分類で説明できます。gaipack のスキームでは、AI の作業ルールを AGENTS.md に集約し、タスク別の手順を .agents/skills/ 配下の SKILL.md に置きます。Claude Code は CLAUDE.md からこの AGENTS.md を参照し、GitHub Copilot も同じファイルを読む設定にして、エージェントを変えても同じ規範が適用される形にしています。これがガイド側の骨格です。

センサー側では、ルールを「書いて守らせる」のではなく機械で止める方針を取っています。CLAUDE.md にルールを書くだけでは守られなかった経験から、フックで禁止操作を検出して止める構成にした経緯は、AI エージェントに「ルールを破らせない」仕組みの記事に実装例つきで書かれています。同じ考え方を要件定義の段階に適用したのが、AI に気をつけてもらうのではなく、間違えられない構造をつくるの記事です。

スキルが自分で育つループ

gaipack の環境で特徴的なのは、ハーネスの部品であるスキルそのものを評価と改善の対象にしている点です。Claude Code のセッションをトレースとして記録し、LLM-as-a-Judge でスキルの使われ方と成果を採点します。スコアの低いスキルについては AI が改善案を GitHub Issue として起票し、人がレビューして承認したものだけを更新して各案件へ再配布します。現場の気づきは別の経路として Discussion に集め、方針の判断はリーダー層が行います。

この構成は、Böckeler 氏の分類でいえば推論的センサー（LLM-as-a-Judge）の出力を、ガイド（スキル）の改訂に戻す経路を持たせたものです。人間の判断が入るのは「改善案を承認する」という 1 点に絞られています。規範に無い操作を検出したらエージェントを止めて人に確認させる停止プロセスと合わせて、人の確認を要所だけに置く設計になっており、先に引用した「人間の入力を最も重要なところへ向ける」設計に対応します。基盤の作り方はClaude Code × LLM-as-a-Judge で作る、自己改善するプラットフォームエンジニアリング基盤、スキルで開発ワークフローを置き換えた実運用は開発ワークフローを 14 本のスキルに置き換えて 1 ヶ月運用してみたを参照してください。

テストハーネスとの用語の違い

「ハーネス」は、ソフトウェアテストでは以前から「テストハーネス」の意味で使われてきました。gaipack の AIDD モダナイズが定義している「現新同一性ハーネス」は、旧システムと新システムに同じ入力を与えて出力を全件比較する検証インフラで、こちらはテストハーネスの用法です。エージェントを包んで制御するハーネスとは対象も目的も異なるので、社内文書や提案書で両方が出てくるときは、どちらの意味かを最初に書いておくと混乱を避けられます。

ハーネスエンジニアリングを始める順番

3 者の一次情報と gaipack の運用に共通する順番を、着手しやすいものから並べます。

1. 指示ファイルを目次にする。 AGENTS.md や CLAUDE.md を 100 行前後に抑え、詳細は docs/ に分けて参照先だけ書く。長い指示ファイルは、OpenAI が失敗例として挙げた「すべてが重要だと何も重要でなくなる」状態を招きます
2. すでにあるセンサーを LLM 向けに整える。 テスト、リンター、型検査は多くのリポジトリに既にあります。エラーメッセージに修復手順を含める、失敗時の出力を短く構造化する、といった手入れで、エージェントの自己修正が進みやすくなります
3. 守らせたいルールを 1 つ選び、機械検査に落とす。 「〜すること」と文章で書いたルールのうち、破られて困るものから順にリンターやフックにします。ルールを足すときは検査も同時に足す、を習慣にします
4. 進捗をリポジトリに残す。 セッションをまたぐタスクでは、進捗ファイルと機能リストをリポジトリに置き、次のセッションが最初に読む場所を決めておきます。Slack やドキュメントツールにしかない合意事項は、エージェントからは存在しないのと同じです
5. 役目を終えた部品を外す。 モデルが更新されたら、ハーネスの各部品が何を補っているかを見直します。Anthropic の言う「仮定のストレステスト」を定期的に行います

Böckeler 氏の言葉を借りれば、保守性のハーネスから始めて、アーキテクチャ適合性、振る舞いへと広げていく順番です。最初から振る舞いの正しさを機械で保証しようとすると、エージェントが書いたテストの品質に依存する構造になり、行き詰まりやすくなります。

ハーネスエンジニアリングに関するよくある質問

導入を検討される方から実際に受ける質問に、一次情報の範囲で答えます。

ハーネスエンジニアリングの具体例は何ですか

OpenAI の記事に出てくる、約 100 行の AGENTS.md を目次にして知識の本体を docs/ に置く構成、依存方向をカスタムリンターと構造テストで検証する仕組み、修復手順を含むリンターのエラーメッセージ、逸脱を検出してリファクタリングのプルリクエストを作る定期タスクが代表例です。Anthropic の記事では、進捗ファイル、失敗状態から始まる機能リスト、生成側と評価側のエージェント分離、コンテキストのリセットが例として挙がっています。

ハーネスエンジニアリングに必要なスキルは何ですか

OpenAI の記事は、エンジニアの仕事が「大きな目標を設計・コード・レビュー・テストの小さな構成要素に分解し、エージェントに構築させる」ことに変わったと述べています。必要なのは、制約をリンターや構造テストに落とす力、フィードバックループを設計する力、そしてエージェントが詰まったときに「不足しているツール・ガードレール・ドキュメントは何か」を特定する観察力です。Böckeler 氏は、人間の開発者が経験や美的判断として暗黙に持っているハーネスを明示化する作業だと表現しています。

コンテキストエンジニアリングとハーネスエンジニアリングの違いは何ですか

コンテキストエンジニアリングは、推論時にモデルへ渡す情報の集合を設計することで、ハーネスの中では「動く前」のガイド側に当たります。ハーネスエンジニアリングは、動いた後の観測（テスト、リンター、AI レビュー）と、その結果を次の実行に戻す経路まで含めた仕組み全体を対象にします。詳しくは本文の比較表を参照してください。

ハーネスエンジニアリングの次に来るものは何ですか

一次情報が示している方向は「ハーネスを減らすこと」です。Anthropic は、ハーネスの各部品はモデルができないことについての仮定であり、モデルの進歩に合わせて取り除けるものを探すべきだと述べています。OpenAI も、完全にエージェントが生成したシステムでアーキテクチャの一貫性が何年にもわたってどう進化するかは未解明だとしています。次に来るのは新しい流行語というより、ハーネスを継続的に棚卸しする運用だと考えるのが実態に近いでしょう。

テストハーネスとは何が違いますか

テストハーネスは、テスト対象を包んで入力を与え出力を検証するためのインフラを指す従来の用語です。ハーネスエンジニアリングのハーネスは、AI エージェントを包んで制御する仕組みを指します。テストハーネスはエージェントのハーネスの中でセンサーとして使われることがある、という関係です。

まとめ

• ハーネスエンジニアリングは、AI エージェントのモデル以外の部分、つまり指示・ツール・検証・フィードバックループ・進捗管理を設計する営みです。OpenAI（2026 年 2 月）、Thoughtworks の Böckeler 氏（同月）、Anthropic（2025 年 11 月〜）が一次情報を公開しています
• 構成要素は、動く前に働くガイドと動いた後に働くセンサー、決定的な計算的処理と LLM による推論的処理の 2 軸で棚卸しできます
• 長時間タスクでは、進捗ファイルと機能リスト、生成と評価の分離、コンテキストのリセットが有効です。ハーネスは品質と引き換えに時間と費用を増やします
• ハーネスの各部品は「モデルにできないこと」の仮定です。モデルが更新されたら、外せる部品を探します

gaipack は、AGENTS.md と SKILL.md を骨格にしたハーネスと、LLM-as-a-Judge でスキルを評価して改善するループを実案件で運用しています。この環境を貴社のリポジトリに構築するAIDD 環境構築や、貴社チームに伴走して定着させる AIDD インハウスをご用意しています。AI 駆動開発の全体像は AI駆動開発の記事にまとめていますので、あわせてご覧ください。