ハーネスエンジニアリング入門：AIコーディングエージェントを「確実に動かす」設計思想

AIコーディングエージェントを日常的に使っていると、あるジレンマに気づきます。Claude CodeやCursorを動かすと、単純なタスクは驚くほどうまくいきます。だが、複雑なマルチステップのタスクや長時間にわたる作業になると、エージェントは途中で方向を見失ったり、同じミスを繰り返したりします。

「もっと良いモデルを使えば解決するのか？」——多くの人がそう考えます。だが、2026年初頭に広まりつつある洞察は、そうではないということです。 問題はエージェント自体ではなく、エージェントが動く「環境」にあります。

この環境を設計・構築する技術が、「 ハーネスエンジニアリング（Harness Engineering） 」です。プロンプトエンジニアリング、コンテキストエンジニアリングに続く第3の進化として、AI研究者とソフトウェアエンジニアの双方から注目を集めています。

プロンプト→コンテキスト→ハーネス：AIとの協業の進化

AIとの協業の方法論は、この数年で段階的に進化してきました。それぞれの世代は前の世代の限界を乗り越える形で登場しています。

プロンプトエンジニアリング（第1世代）

プロンプトエンジニアリングは「 何を言うか 」を最適化する技術です。GPT-3やChatGPTの登場とともに一般化し、2022〜2023年に全盛期を迎えました。

「あなたはシニアエンジニアです。以下のコードをリファクタリングしてください」といった指示の書き方を工夫することで、モデルの出力を制御しようとするアプローチです。単発タスクや簡単なQ&Aには強力ですが、長期的なタスクや複雑なワークフローへの対応には限界があります¹。

コンテキストエンジニアリング（第2世代）

2025年中頃、LangChainのHarrison Chaseらが「コンテキストエンジニアリング」という概念を広めました。これは「 何を知るべきか 」を最適化する技術で、モデルが「見る」情報環境全体を設計することに焦点を当てます²。

プロンプトエンジニアリングはコンテキストエンジニアリングのサブセットです。「プロンプトエンジニアリングが最初の良い出力を得るための技術なら、コンテキストエンジニアリングは1000番目の出力でも良い品質を維持するための技術」³と言われます。ツール定義、RAG、メモリ管理などがその構成要素になります。

しかし、コンテキストエンジニアリングにも盲点がありました。エージェントが「どう実行されるか」——ツールを呼び出すタイミング、失敗した時のリトライ、複数のコンテキストウィンドウにまたがる状態管理——これらは扱われていませんでした。

ハーネスエンジニアリング（第3世代）

2025年末から2026年にかけて、より広い概念として「ハーネスエンジニアリング」が台頭してきました。「 どう動かすか 」を最適化する技術で、エージェントが確実・長期・自律的に動作するための「環境」そのものを設計・構築することを指します。

ハーネスとは何か

「ハーネス（Harness）」という言葉は、馬具の「馬のたずな・締め具」から来ています。AIの文脈では、 エージェント（＝モデル）を包むソフトウェアシステム全体 のことを指します。

ハーネスはエージェント自体ではありません。エージェントが信頼性高く、効率的に、制御可能な形で動作するための「器」です⁴。具体的には以下の機能をカバーします。

• ツールディスパッチ：エージェントがどのツールを呼び出し、結果をどう処理するか
• コンテキスト管理：関連情報の注入・不要情報の削減・古い情報の圧縮
• 安全性の強制：破壊的操作の防止、サンドボックス管理
• 状態管理：複数のコンテキストウィンドウにまたがるセッション継続性
• リトライ・検証ループ：失敗した時の自律的な回復

ML Engineer のPhilipp Schmidは、次のように表現しています⁵。

競争優位の源泉はもはやプロンプトではない。ハーネスが捕捉するトラジェクトリ（成功・失敗の軌跡）こそがデータセットであり、次世代モデルのトレーニングに直結する。

アナロジーとして、ハーネスのないエージェントは、手綱のない馬です。どれだけ優秀な馬でも、操ることができなければ目的地には着きません。

OpenAIの実験：0行の手書きコードで100万行のプロダクト

ハーネスエンジニアリングが単なる理論ではないことを示す、最も説得力ある実例があります。2026年2月11日、OpenAIのエンジニアRyan Lopopoが公式ブログで公開した実験です⁶。

実験の概要

OpenAIのチームは2025年8月から約5ヶ月間、ある「実験」を行いました：

「私たちのチームは、手動で書かれたコードが0行のソフトウェアプロダクトを構築・出荷するという実験を行ってきた」

プロダクトは内部の日常ユーザーと外部アルファテスターが存在し、デプロイ・破損・修正というサイクルを実際に回しています。すべてのコード——アプリケーションロジック、テスト、CI設定、ドキュメント、オブザーバビリティ、社内ツール——がCodexによって書かれました。その規模は約100万行です。そして推定所要時間は「手書きの1/10」です。

チームの哲学はシンプルでした：「 Humans steer. Agents execute.（人間が方向を決め、エージェントが実行する。） 」

コアコンセプト：4つの「可読性」設計

OpenAIのチームが発見したのは、エージェントを大規模に機能させるために、4種類の「可読性（Legibility）」を設計する必要があるということです。ここでの「可読性」とは、人間が読みやすいという意味ではなく、「エージェントがシステムの状態を定量的に把握できる度合い」を指しています。

1. Agent Legibility（エージェント可読性）

リポジトリをCodexが読めるように最適化します。人間の新入り社員ではなく、エージェントのために読みやすく設計するという発想の転換です。

「エージェントが実行中にコンテキストでアクセスできないものは、存在しないも同然だ。Google Docs、チャットスレッド、人々の頭の中にある知識はシステムにアクセスできない。リポジトリに存在するバージョン管理されたアーティファクト（コード、マークダウン、スキーマ、実行可能なプラン）のみが、エージェントが見られるものだ。」

2. Repository-Resident Knowledge（リポジトリ常駐ナレッジ）

ドキュメントとアーキテクチャ知識をリポジトリに集約します。 AGENTS.md、ARCHITECTURE.md、設計ドキュメント、製品仕様がすべてgitで管理されます。そして重要なのは、それらが最新状態を保つよう、専用のリンターとCIが整合性を強制していることです。

docs/
├── design-docs/
│   ├── index.md
│   └── core-beliefs.md
├── exec-plans/
│   ├── active/
│   └── completed/
├── product-specs/
│   └── index.md
└── DESIGN.md, FRONTEND.md, SECURITY.md ...

3. Application Legibility（アプリ可読性）

実装スループットが上がると、次のボトルネックはヒューマンQAになりました。エージェントがアプリケーション自体を「見られない」からです。

解決策は、アプリをエージェントに直接見せることです。Chrome DevTools MCPをCodexに接続してUIを確認させ、ワークツリーごとにアプリをブート可能にして並列実行できるようにしました。

4. Architecture Enforcement（アーキテクチャ強制）

「ゴールデンプリンシプル」と呼ぶ機械的なルールをリポジトリに埋め込み、リンターとCIで強制します。バックグラウンドのCodexタスクが定期的にコードベースをスキャンし、逸脱を検出してリファクタリングのプルリクエストを自動で開きます。これが「AIスラップ（AI slop）」——コードが徐々に品質低下していく問題——を防ぐ仕組みです。

エンジニアの役割はどう変わるのか

ハーネスエンジニアリングは単なる技術の話ではなく、エンジニアリングという職業の本質を問い直します。

2026年の時点で、開発組織の97%がAIをソフトウェア開発ライフサイクルに活用しています⁷。「エンジニアがコードを書く」から「エンジニアがエージェントを操る」への移行は、もはや仮説ではなく現実です。

この移行に伴い、稀少リソースが変わります。かつては計算量が制約でした。今は「人間の時間と注意」が制約です。この転換は、あらゆるエンジニアリングのトレードオフを変えます。「待つことが高くつき、修正は安い」——以前とは逆の世界です。

ハーネスエンジニアを名乗るには、新しいスキルセットが必要になります：

• 環境設計：エージェントが動く文脈を整える能力
• 意図の仕様化：何を達成すべきかを曖昧さなく記述する能力
• フィードバックループ設計：エージェントが自己修正できる仕組みを作る能力
• 「テイスト」のコード化：アーキテクチャ上の美意識を機械的なルールとして表現する能力

gtcode.comはこれを、次のように表現しています⁸。

「エージェントはエンジニアリング判断力の代替ではなく、マシンスピードで動く判断力の乗数だ。判断力はどこかから来なければならない。ハーネスエンジニアリングとは、それがどこから来るかを決定し、正確にコード化し、リポジトリ以外には見えないシステムにとって可読にする実践だ。」

実践する上での注意点

ハーネスエンジニアリングは万能薬ではありません。始める前に知っておくべき落とし穴があります。

まず、 リポジトリレベルのコンテキストファイルの効果は一様ではありません。 研究によると、AI生成の CLAUDE.md や AGENTS.md はエージェントの成功率を下げる可能性があります。人間が書いたものでも改善幅はわずかで、コストは増加する傾向があります。

次に、 モデルが改善されるたびに設計の見直しが必要になります。 philschmid.deが言う「Build to Delete（削除するために作れ）」——アーキテクチャをモジュラーに保ち、新しいモデルが旧来のロジックを置き換えるための準備をする——という考え方が重要です⁵。

最後に、 小規模・単純なタスクには過剰設計になりえます。 「シンプルに始めろ。巨大なコントロールフローを作るな。ロバストなアトミックツールを提供し、モデルにプランを立てさせろ」という原則は、ハーネスエンジニアリングを始める上での現実的なガイドラインです。

筆者の実践：個人ブログを「ハーネス化」する

ここまでOpenAIの100万行という大規模な事例を見てきました。だが、ハーネスエンジニアリングは大企業だけのものではありません。筆者（ZeroZawa）は、この個人ブログの運用そのものを「ハーネス」として設計しています。規模はOpenAIの100万分の1でも、効いている原理は同じです。

OpenAIが挙げた4つの「可読性」を、個人レベルに翻訳するとこうなります。

Repository-Resident Knowledge を個人で実装する

このブログのリポジトリには、エージェント向けの知識が常駐しています。CLAUDE.md（プロジェクト規約）、docs/decisions/ に置いたADR（設計判断の記録）、tasks/todo.md（作業ボード）——これらはすべてgit管理下にあり、エージェントが「見られる」状態にあります。口頭やチャットで伝えた指示は、次のセッションで起動するエージェントにとっては存在しないも同然だからです。記事制作のワークフローも、7つの自作スキルとして実行可能な形でリポジトリに宿らせています。

Architecture Enforcement：「指摘」を「機械的ルール」に変える

筆者は、日本語の太字記法がMarkdownパーサを破綻させる地味なバグに何度か遭遇しました。太字の閉じ記号の直後に全角の鉤括弧が続くと、パーサが太字を認識できず記号がそのまま表示されてしまう、というものです。これを毎回手で直すのは無駄なので、その破綻パターンだけを検出するhook（ファイル保存時に自動で走るチェック）を書いて、リポジトリに埋め込みました。OpenAIの言う「ゴールデンプリンシプルをリンターとCIで強制する」仕組みの、ミニチュア版です。記事公開前の品質チェックや外部レビューも、同じ「逸脱を機械が捕まえる」発想で組んでいます。

hookが実際に機能するか検証する

ここまでの説明を伝聞のままにしないため、本番と同じロジックのhook（.claude/hooks/check-cjk-markdown.mjs）に対して、PostToolUseが実際に渡すstdin JSONの形式で3種類の入力を投入し、挙動を確認しました。

1. 太字の開き側が壊れるケース——CJK文字の直後に **、その直後に全角の開き鉤括弧が続く行——を投入すると、L5:13 (opener) の位置を指摘してexit code 2で終了しました。
2. 太字の閉じ側が壊れるケース——全角の閉じ鉤括弧の直後に **、その直後にCJK文字が続く行——を投入すると、L5:7 (closer) の位置を指摘してexit code 2で終了しました。
3. 破綻パターンを含まないクリーンな入力を投入すると、何も出力せずexit code 0で終了しました。

あわせて、文体チェックのhook（check-writing-style.mjs）を改稿前のこの記事本文に対して実行し、38件の警告（うち です・ます調 の言い切り違反が30件）を検出したことも確認しました。この記事は、その指摘を反映して全文をです・ます調に統一しています。

「セッション開始hook」ではなく、CLAUDE.mdの自動読み込みと人間の一手間

ここは訂正が必要な箇所です。当初の原稿では、「セッション開始時にhookが自動でtodo.mdやADRをエージェントへ注入する仕組み」が最も効いた、と書いていました。ですが、リポジトリを実際に確認すると、そのようなSessionStart hookは存在しません。.claude/settings.json に定義されているhookは、PostToolUse（WriteまたはEdit実行後）に限られる2つ——CJK太字の破綻を検出するチェックと、文体をチェックするチェック——だけです。存在しない仕組みを「最も効いた」と書いていたのは単純な事実誤認で、正直に書き直します。

実際に効いているのは、もっと地味な2つの仕組みです。1つは、Claude Code自体がセッション開始時に CLAUDE.md をプロジェクトコンテキストとして自動で読み込む標準機能——これはhookではなく、ハーネス（Claude Code本体）の既定動作です。もう1つは、todo.md やADRをgit管理下のリポジトリに常駐させておき、筆者自身が新しいセッションの冒頭で「まずtodo.mdを読んで」と一声かける、という人間側の一手間です。自動注入ではなく、リポジトリに知識を置いておくことで「毎回説明し直す」コストを引き下げている、というのが実態です。

そして、前節で検証した2つのPostToolUseフックこそが、最も確実に効いている仕組みだと言えます。壊れたMarkdownや文体の逸脱を、人間の見落としに頼らず機械的に捕まえてくれるからです。コンテキストエンジニアリングで言う「何を知るべきか」を、存在しない自動化ではなく、リポジトリと人間の運用習慣に宿らせている、というのが実態に近い言い方です。

一方で、すべてが効いたわけではありません。スキルやルールを増やしすぎると、前章で触れた「小規模・単純なタスクには過剰設計になる」落とし穴にそのままはまります。筆者の場合も、確実に効いたのは「知識をリポジトリに常駐させる」系と「機械的チェック」系であって、凝った制御フローを足すほどむしろ邪魔になることが多かったです。Build to Delete の精神で、効かない仕掛けは削る前提で組むのが現実的です。

「Humans steer. Agents execute.」を個人で体験する

OpenAIのこの標語を、筆者は記事制作で日々体験しています。自作のスキル群を整えてから、記事の品質は標準化され、及第点を外さなくなりました。だが及第点を超える部分——切り口の鋭さ、一次体験の厚み、独自の見解——は、最後に人間が仕上げます。エージェントが土台を確実に作るからこそ、人間は判断と「テイスト」のコード化に集中できます。これは規模を問わず成り立つ、ハーネスエンジニアリングの核心だと考えています。

まとめ

ハーネスエンジニアリングを3行でまとめると、次のようになります。

1. エージェントではなく環境を設計する：どれだけ優秀なモデルも、動く環境が適切でなければ力を発揮できません
2. 知識をリポジトリに宿らせる：エージェントが見られるものだけが存在します。口頭・Docs・Slack上の知識は、エージェントにとって存在しません
3. 人間の役割は判断とアーキテクチャ：コードを書くことではなく、エージェントが信頼できる判断基準を埋め込むことが仕事になります

エンジニアリングの本質は変わりません——「どこに判断力を宿らせるか」を決めることです。その「どこ」が、かつてはコード自体だったものが、今はハーネスという環境になりつつあります。

「馬は速い。ハーネスがすべてだ。」

参考文献