ハーネスエンジニアリング入門：AIエージェントの品質を「環境設計」で高める新パラダイム

ZenChAIne·2026年4月10日

AIエージェントハーネスエンジニアリングClaude Code

はじめに

ハーネスエンジニアリングは、AI エージェントの出力品質と再現性を「構造」で高める環境設計手法です。プロンプトの工夫（プロンプトエンジニアリング）でも、文脈の最適化（コンテキストエンジニアリング）でもなく、エージェントが動く 環境そのもの ——ルール、スキル、フック、メモリ、フィードバックループ——を設計することで、より安定した高品質な出力を実現します。

この記事のポイント

プロンプト → コンテキスト → ハーネスという整理の一つとして、AI 活用の 3 段階を理解する
ハーネスの 5 構成要素（ルール・スキル・フック・メモリ・フィードバック）を把握する
OpenAI の「人間が書いたコード 0 行、100 万行生成」実験の舞台裏を知る
明日から始められる実践的な導入ステップを学ぶ

2025 年後半から 2026 年にかけて、OpenAI、Anthropic、そして数多くの開発チームが同じ結論に辿り着きました。エージェントの出力品質を左右するのは、モデルの性能よりもハーネスの設計である、と。SWE-bench に関する研究（Particula.tech 等）によると、同一モデルでもスキャフォールディング設計の違いだけでパス率が大幅に変動することが報告されています。

なぜプロンプトとコンテキストだけでは足りないのか？

AI との協働方法は、整理の一つとして 3 つの段階で捉えることができます。各段階は置き換えではなく積み重ねです。家を建てるように、基礎（プロンプト）→ 壁（コンテキスト）→ 屋根（ハーネス）と層を成します。

第 1 段階：プロンプトエンジニアリング（2022〜2024 年）

「どう聞くか」に焦点を当てた技術です。Few-shot プロンプティング、Chain-of-Thought、ロールプレイなど、LLM から良い回答を引き出すテクニックが発展しました。個人利用やシンプルなタスクでは今も有効ですが、大規模プロジェクトでは限界があります。

第 2 段階：コンテキストエンジニアリング（2025 年〜）

「何を見せるか」を重視するアプローチです。Andrej Karpathy 氏は 2025 年 6 月に次のように述べました。

コンテキストエンジニアリングとは、次のステップに必要な情報でコンテキストウィンドウを最適に満たす、繊細な技術と科学である。

タスク記述、Few-shot 例、RAG、ツール定義、状態管理——コンテキストウィンドウに「何を入れるか」の最適化です。CLAUDE.md や AGENTS.md はこの段階の代表的な成果物です。

第 3 段階：ハーネスエンジニアリング（2025 年後半〜）

「どんな環境で働かせるか」を設計するパラダイムです。馬具一式を意味する「ハーネス」の名前の通り、AI エージェント周囲のルール・制約・チェック体制・テスト・ツール・メモリ・安全装置の総体を指します。「ハーネスエンジニアリング」という用語は特定の企業や個人が提唱したものではなく、2025 年後半から業界の複数のコミュニティで自然発生的に広まった概念です。Martin Fowler 氏は「この用語が登場した（the term has emerged）」と記述し、Mitchell Hashimoto 氏も「広く使われている用語かは分からない」と述べています。

コンテキストエンジニアリングとの決定的な違いは 強制力 です。CLAUDE.md に「テストを書いてからコミットしてください」と書いても、それは「お願い」にすぎません。ハーネスエンジニアリングでは、フックがコミット前にテストを自動実行し、失敗すればコミットをブロックします。

ハーネスの 5 構成要素とは？

Martin Fowler 氏は、ハーネスの制御を フィードフォワード （行動前に誘導するガイド）と フィードバック （行動後に検証するセンサー）に分類しています。この 2 軸を踏まえたうえで、ハーネスは以下の 5 要素で構成されます。

要素	機能	制御タイプ	例
ルール	行動規範の宣言	フィードフォワード	`src/domain/` は外部ライブラリを import しない
スキル	再利用可能な手順	フィードフォワード	`/write-test` で標準化されたテスト生成
フック	イベント駆動トリガー	フィードバック	ファイル保存後の自動フォーマット・型チェック
メモリ	セッション間の持続性	フィードフォワード	progress.md で設計判断を記録・継承
フィードバック	多層的な自動検証	フィードバック	型チェック → lint → テスト → 構造テスト

ルール：行動規範を明文化する

CLAUDE.md や .claude/rules/ に記述する行動指針です。HumanLayer のブログでは、CLAUDE.md は 60 行未満 に抑えることが推奨されており、プロジェクト固有のルールに絞ることが重要です。汎用的なベストプラクティスはモデルがすでに知っているため、記述しても効果は薄いとされています。

スキル：手順を再利用可能にする

同じ指示を繰り返していることに気づいたら、それをスキル化するタイミングです。Claude Code では、.claude/commands/*.md にカスタムスラッシュコマンドを定義する方法と、.claude/skills/<name>/SKILL.md にスキルとして定義する方法があります。いずれも /command-name の形式で呼び出せ、テスト生成、コードレビュー、記事生成など、チーム内で標準化された手順を共有できます。

フック：イベント駆動で品質を強制する

フックはエージェントのライフサイクルイベントにトリガーされるスクリプトです。Claude Code の場合、PreToolUse（ツール実行前）、PostToolUse（ツール実行後）、Stop（応答完了時）などのイベントに対してフックを設定できます。「お願い」ではなく 強制力 を持つ点がルールとの決定的な違いです。

メモリ：セッション間の文脈を保持する

AI エージェントの最大の弱点の一つがセッション間の記憶喪失です。新しいセッションを開くと、エージェントが自動的に読むのは CLAUDE.md くらいです。前回どこまで進んだか、どんな設計判断をしたかは、何もしなければ消えてしまいます。

この問題に対して、現在主に 3 つのアプローチがあります。

1. CLAUDE.md に「まず progress.md を読め」と書く 最もシンプルな方法です。CLAUDE.md に「作業開始前に必ず progress.md を読み、作業完了後に更新せよ」と記述します。ただしこれは「お願い」であり、エージェントが従わないこともあります。

2. Auto Memory（Claude Code の場合） Claude Code には ~/.claude/projects/<project>/memory/ にメモリを自動保存する仕組みがあります。MEMORY.md（先頭 200 行）はセッション開始時に自動読み込みされるため、CLAUDE.md と同様に毎回確実に参照されます。ただし保存される内容は Claude の判断に委ねられます。

3. ハーネス側で強制する（Anthropic の研究パターン） Anthropic の研究では、ハーネス（外部スクリプト）がエージェントの起動時に claude-progress.txt や JSON 形式の機能要件リストを自動で読み込ませるパターンが紹介されています。JSON が推奨されるのは、Markdown に比べてエージェントが雑に書き換えにくいためです。これは Claude Code 単体ではなく、外部のオーケストレーションシステムを使うケースです。

コンテキスト圧縮（compact）への対策: Claude Code では会話が長くなるとコンテキストが自動圧縮されます。圧縮後にエージェントが文脈を見失うのを防ぐには、重要な判断や進捗を progress.md などの外部ファイルに都度書き出しておくのが有効です。ファイルは圧縮されないため、必要なときに読み直せます。

フィードバック：多層的な自動検証

フィードバックには 計算的制御 （リンター、テスト——決定論的で高速）と 推論的制御 （LLM-as-Judge——低速で非決定論的）の 2 種類があります。計算的制御を優先し、推論的制御は最終段階で使うのが効率的です。

OpenAI の「人間 0 行、100 万行生成」実験から何を学べるか？

2025 年 8 月から 2026 年 1 月にかけて、OpenAI は社内で画期的な実験を行いました。Ryan Lopopolo 氏が率いたチームの結果は衝撃的です。

人間が書いたコード: 0 行
生成されたコード: 約 100 万行
マージされた PR: 約 1,500 件
1 エンジニアあたり: 3.5 PR/日
トークン消費: 1 日 10 億トークン以上（Latent Space の推定では約 2,000〜3,000 ドル/日）

「人手で品質を直す」はスケールしない

OpenAI が最初に試みたのは「AI スロップ・フライデー」——毎週金曜にチームの 20% の時間を低品質コードの手動修正に充てる運用でした。しかしコードが増えるにつれて追いつかなくなり、すぐに破綻しました。

解決策は、品質基準を 自動チェックルール として組み込み、別の AI エージェントに修正を任せることでした。人間が品質を直すのではなく、仕組みが品質を保つ——これがハーネスエンジニアリングの根幹です。

OpenAI が実際にハーネスに組み込んだルールの例を、かみ砕いて紹介します。

同じ処理を何度も書かない: 共通の処理はチーム共有のライブラリにまとめ、AI がバラバラに再発明するのを防ぐ
データの入口で必ずチェックする: 外部から受け取るデータは入口で検証し、内部では「正しいデータだけが流れている」と信頼できる状態にする
コードの依存方向を一方通行にする: 「UI は Service を呼べるが、逆は不可」のように、コードの呼び出し方向を自動チェックで強制する

いずれも「AI に毎回お願いする」のではなく「仕組みとして強制する」パターンです。

指示書は短く、詳細は別ファイルに

もう一つの重要な発見は、AI への指示書（CLAUDE.md に相当するもの）を 約 100 行の目次 に留め、詳細は別ファイルに分けるという設計です。AI は読み込んでいない情報を使えないため、必要な情報にすぐアクセスできる構造が重要です。ただし、すべてを一つのファイルに詰め込むと情報過多で逆効果になります。

Anthropic のハーネス設計はどう異なるのか？

Anthropic は 2 つのエンジニアリングブログで、異なるアプローチのハーネス設計を公開しています。

パターン A：二体構成（2025 年 11 月）

チームで仕事を引き継ぐとき、前任者がメモや手順書を残しておけば後任がスムーズに作業できます。この発想を AI エージェントに応用した、2 つのエージェントによる分業パターンです。

初期化エージェント（プロジェクト開始時に 1 回だけ起動）:

開発サーバーの起動スクリプト（init.sh）を作成
作業ログ（claude-progress.txt）を作成
機能要件リスト（feature_list.json）を作成——「このアプリに必要な機能」を 200 項目以上洗い出し、各項目に確認手順と完了フラグをつけた JSON ファイル

コーディングエージェント（2 回目以降のセッションで毎回起動）:

claude-progress.txt を読んで前回までの進捗を把握
feature_list.json から未完了の最優先機能を選ぶ
実装 → 検証 → コミット → 進捗ファイルと機能リストを更新

ポイントは、2 つのエージェントが直接やりとりするわけではなく、ファイルを介して引き継ぐ という点です。初期化エージェントが残した「作業指示書」を、コーディングエージェントが毎回読み込んで作業を始めます。

このパターンの特徴は、詳細な設計書を作らないことです。機能リストの「説明 + 確認手順」が実質的な仕様になります。Anthropic の実験は Claude.ai のクローンを作るプロジェクトで行われたため、モデル自身が「チャット UI はこう動くべき」という知識を持っており、簡潔な仕様でも開発が進みました。ただし、モデルが既存知識を持たない業務ドメインでは、このアプローチだけでは品質が出にくいと考えられます。

実験の結果、もう一つ問題が見つかりました。コーディングエージェントが、アプリ全体を通して動作確認していないのに、機能リスト上で「完了」とマークしてしまうケースがあったのです。つまり 「作ったけど本当に動くかは確認していない」 状態です。「仕様が簡潔すぎる」「検証が自己申告」という 2 つの課題を解決するために生まれたのが、次の三体構成パターンです。

パターン B：三体構成——GAN 型（2026 年 3 月）

パターン A の課題——仕様の不足と検証の甘さ——を踏まえ、企画・開発・評価を 3 つの独立したエージェントに分離 した構成です。GAN（敵対的生成ネットワーク）のように「作る側」と「評価する側」を対立させることで、品質を担保します。

Planner（企画）: 簡潔な指示から、パターン A にはなかった詳細な仕様書を生成。何を作るべきかを明確にする
Generator（開発）: Planner が作った仕様に基づいて実装。自己評価も行うが、最終判断は Evaluator に委ねる
Evaluator（評価）: Playwright MCP を使い、実際のユーザーとしてブラウザ上でアプリを操作してテスト。Generator とは別のエージェントなので、自分の作ったコードに甘くなる問題を回避できる

この 3 つのエージェントを人間が手動でセッション切り替えするわけではありません。Claude Agent SDK を使ったオーケストレーター（外部のハーネスプログラム）が、Planner → Generator ⇄ Evaluator のループを自動で回します。人間は最初にプロンプトを渡すだけで、あとは数時間にわたる自律的なセッションとして動きます。

Claude Agent SDK とは、Claude Code CLI の内部エンジン（エージェントループ + ツール実行）を Python/TypeScript のライブラリとして使えるようにしたものです。普段 Claude Code を対話的に使うのとは異なり、自分で書いたプログラムの中から query() 関数で Claude エージェントを起動し、複数のエージェントを自動で連携させられます。なお、同様のマルチエージェント構成は SDK を使わなくても、Claude Code のスキル機構（オーケストレーター役のスキルがワーカースキルを呼び出す形）でも実現できます。

エージェント間の連携はパターン A と同じくファイルベースです。あるエージェントがファイルに書き、別のエージェントがそれを読んで応答します。特徴的なのは 「スプリント契約」 という仕組みで、Generator と Evaluator が各スプリントの前に「何をもって完了とするか」を合意してから開発に入ります。Generator が実装計画を提案し、Evaluator がレビューして合意するまで調整する——これにより「作った側と評価する側の基準がズレる」問題を防いでいます。

Anthropic の研究チームは重要な原則を指摘しています。「ハーネスのすべてのコンポーネントは、モデルにできないことについての仮定を符号化している」——つまり、モデルの能力が向上すれば、ハーネスの複雑性は減少すべきだということです。

具体的な成果として、Game Maker プロジェクトでは単純なハーネスだと 20 分/$9 で壊れた出力しか得られなかったのが、フルハーネスでは 6 時間/$200 で機能的かつ洗練されたアプリケーションが完成しました。

実践：明日から始めるハーネスエンジニアリング

Mitchell Hashimoto 氏（HashiCorp 創業者）のルールは明快です。「エージェントがミスをしたとき、そのミスが二度と起きないような仕組みを設計する時間を取ること」。ただし、失敗が起きる前にハーネスを最適化しようとするのは逆効果です。

段階的な導入フロー

Day 1: CLAUDE.md を 30 分で作成。プロジェクト固有のルールに絞り、簡潔に保つ。

Week 1〜2: 同じ指示を繰り返している作業をスキル化。/write-test、/review など。

Week 2〜4: フックで自動フォーマット・型チェック・テスト実行を設定。違反をブロックする強制力を導入。

Week 2〜4: CLAUDE.md に「作業前に progress.md を読み、作業後に更新せよ」と記述。Auto Memory も活用してセッション間の文脈を保持。

継続的: 同じ違反が 3 回発生したら、そのルールの強制度を 1 段階上げる（ルール記述 → フック化 → テスト化）。

ZenChAIne では、AI エージェントを活用した開発ワークフローの設計・最適化に取り組んでいます。ハーネスエンジニアリングの導入支援にご興味のある方は、ぜひお問い合わせください。

参考ソース

🇺🇸 Read in English