Claude CodeやCopilot Agent Modeにコードを書かせてみたら、途中でコンテキストが切れて最初からやり直し——心当たり、ありませんか？プロンプトを工夫しても、CLAUDE.mdを書いても、長時間の自律作業になると品質がガタ落ちする。この「エージェントに任せたいのに任せきれない」モヤモヤに正面から答えるのが、ハーネスエンジニアリングという設計思想です。
この記事を読み終わる頃には、「自分のプロジェクトで何をすればいいか」が具体的にイメージできる状態になっているはずです。
ハーネスエンジニアリングとは何か
ハーネスとは何か
一言で言います。ハーネスエンジニアリングとは、AIエージェントが長時間・安定して成果を出し続けるための「環境と制御構造」を設計する手法です。
「ハーネス（harness）」は馬の手綱の意味。エージェントを完全に放し飼いにするのではなく、走れる範囲を構造的に定義してあげるイメージです。エージェントに自由を与えつつ、暴走させない仕組みを作ること——それがハーネス設計の本質です。
具体的には、リポジトリ内のドキュメント整備、アーキテクチャ制約の機械的適用、CI/CDによるフィードバックループの3つを軸に、エージェントが「迷わず・壊さず・引き継げる」状態を作ります。
ハーネスエンジニアリングの概要をまとめたQiita記事のブックマークコメントでも、「セッション間の引き継ぎ、進捗追跡、品質維持の仕組みがハーネスエンジニアリング」と端的に説明されています。
3つの概念の違い
正直、ここを混同している人がめちゃくちゃ多い。プロンプトエンジニアリング・コンテキストエンジニアリング・ハーネスエンジニアリングは、レイヤーがまるで違います。
| 概念 | 時期 | 問いの中心 | 限界 |
|---|---|---|---|
| プロンプトエンジニアリング | 2023〜2024年 | 命令をどう書くか | スケールすると挙動が不安定 |
| コンテキストエンジニアリング | 2025年〜 | 何を渡すか | セッションを跨ぐと文脈が消える |
| ハーネスエンジニアリング | 2026年〜（概念定着・普及段階） | どう制御・接続・回復させるか | 現在進行形で壁と格闘中 |
プロンプトエンジニアからハーネスエンジニアリングへの変遷を整理したQiita記事でも述べられている通り、プロンプトは「文の問題」、コンテキストは「情報設計の問題」、ハーネスは「インフラ設計の問題」です。つまり、プロンプトをいくら磨いても解決できない問題領域がある。それがハーネスの守備範囲です。
なぜ今この概念が重要なのか
ハーネスエンジニアリングの目的は、モデル性能の底上げではありません。環境設計によってエージェントを安定稼働させることが本質です。モデルを変えなくても、環境設計だけで成果は劇的に変わります。
役割が変わった理由
結論から言います。エージェントの性能が上がれば上がるほど、ハーネスの重要性は増します。
HashiCorpの共同創設者Mitchell Hashimoto氏が2026年2月5日にブログで「ハーネスエンジニアリング」という言葉を使い、続いてOpenAIが2026年2月11日に「Harness engineering: leveraging Codex in an agent-first world」を公開。さらにThoughtWorksのBirgitta BöckelerがMartin Fowlerのサイトで分析記事を出し、わずか数週間でこの概念はAIエンジニアリングの中核語彙として定着しました（OpenAI公式ブログ・Martin Fowler記事参照）。
そして、これは単なるバズワードではありません。Qiita記事で紹介されているLangChainの実験報告によると（一次ソースは未確認）、ハーネスの改善だけでベンチマークが大幅に向上したという事例があります。モデル自体を変えなくても、環境設計だけでここまで成果が変わる。エンジニアの役割が「コードを書く人」から「エージェントが正しく動ける環境を設計する人」へとシフトしている証拠です。
制約は少ないほどいい？
ここ、地味に大事です。「ハーネスは充実させるほど良い」と思いがちですが、現実は逆のケースもあります。
Martin Fowlerのサイトに掲載された分析記事によると、包括的なツールライブラリを揃えた結果、エージェントはツール間で混乱し冗長な呼び出しを繰り返した。ツールの80%を削除したら、速く正確になったとのこと。同記事ではClaude Codeの開発チームについても触れられており、「ハーネスは最小限。仕事のほとんどはモデルの力を最大限に引き出すこと」という方針が紹介されています。
つまり、制約は「足りないより多すぎるほうが危険」な場面がある。このトレードオフを意識できるかどうかが、ハーネス設計の腕の見せどころです。
ハーネス設計の3つのコア要素
迷わせない構造設計
エージェントが「今自分は何をすべきか」を常に把握できる状態を作ること。これが最初にして最重要の要素です。人間のためだけでなく、エージェントのためにもドキュメントを書くというマインドシフトが求められます。
具体的にはAGENTS.mdやARCHITECTURE.mdといったドキュメントをリポジトリに配置し、エージェントが必要な情報を必要な時に参照できるようにします。ハーネスエンジニアリングの構成要素を整理したブログ記事では、「人間が理解しやすいコードではなく、エージェントが理解・修正しやすい構造へとソフトウェア設計が最適化される」という方向性が指摘されています。
ARCHITECTURE.mdに最低限書くべき内容
- プロジェクトのディレクトリ構造と各フォルダの役割
- 採用している技術スタックとその選定理由
- 依存関係のルール（例：UIレイヤーはDBに直接アクセスしない）
- 命名規則・コーディング規約
- 避けるべきパターン（アンチパターンの明示）
知識基盤の整備
エージェントがアクセスできない情報は、存在しないものと同じです。
なぜここまで断言するかというと、AIはリポジトリ内の既存パターンを良いものも悪いものも区別なく複製するからです。設計判断が頭の中やSlackの奥底にしかない状態でエージェントを走らせると、古いアンチパターンや技術的負債がそのまま再生産されます。
すべての設計判断をテキスト化してリポジトリに含める——いわゆるSingle Source of Truth（信頼できる唯一の情報源）の徹底が必須です。ただし、静的なドキュメントは更新されないと「死んだルール」になり、エージェントを誤誘導します。知識基盤の鮮度管理は、一度やって終わりではなく継続的な作業です。バックグラウンドエージェントでコードとドキュメントの乖離を常時監視する仕組みを導入することを推奨します。
実行環境の制約設計
エージェントに「何でもやっていい」と言わない。これが制約設計の核心です。制約設計は以下の3つのコンポーネントがセットで機能することで、エージェントの「手綱のある自由」が実現します。
制約設計の3コンポーネント
- アクション定義：Claude Codeなら
.claude/commands/にMarkdownファイルを置き、エージェントが呼び出せるコマンドを限定する - 構造テスト：リンターや型チェックでアーキテクチャ制約を機械的に適用し、エージェントの迷走を防止する
- フィードバックループ：CI/CDやバックグラウンドのGCエージェントによる自動修正サイクルを回す
現場で使えるハーネス設計の実践
陥りやすいアンチパターンと対策
正直に言います。入門記事の「CLAUDE.mdを書いてHook設定するだけ、半日でOK」を鵜呑みにすると痛い目を見ます。Martin Fowlerの批評記事でも指摘されている通り、本気のハーネスはそれ自体が一つのソフトウェアプロダクトになります。
| アンチパターン | 何が起きるか | 対策 |
|---|---|---|
| ドキュメントを書いて放置 | ルールが腐敗し、エージェントが誤誘導される | バックグラウンドエージェントでコードとドキュメントの乖離を常時監視 |
| ツール・制約の詰め込みすぎ | エージェントが混乱し冗長な呼び出しを繰り返す（Vercelの事例） | 最小限の制約から始めて、問題が起きたら足す |
| 既存コードがカオスなまま導入 | 悪いパターンが再生産されるだけ | 先にリファクタリング。ハーネスは魔法の杖ではない |
ハーネスは「構造の門番」であって「意味の番人」ではありません。振る舞いや機能性の検証は別途必要です。
今日から始める最初のステップ
構えすぎなくて大丈夫です。以下の順番で少しずつ始めましょう。
プロジェクトの構造、技術選定の理由、依存関係のルールを箇条書きでOK。「エージェントが読む」前提で、曖昧な表現を避けて明示的に書くことがポイントです。
曖昧な指示ではなく、機械的に「正しいコード」を定義する。ESLint・Ruff・Biomeなど、プロジェクトの言語に合ったツールを1つ選んでルールを確定させましょう。
特定の機能開発で「プロンプト→実行→自動テスト→修正」のサイクルを自動化してみる。これだけで、エージェントの出力品質は体感で変わります。あとは問題が起きるたびに制約を足していけばいい。
業務を完遂し続けるためのハーネスエンジニアリングでも、段階的な導入の重要性が強調されています。
もっと深く学ぶためのリソース
まずは今日、自分のリポジトリにARCHITECTURE.mdを1枚置くところから。それがハーネスエンジニアリングの最初の一歩です。プロンプトをいくら磨いても越えられない壁は、環境設計で越える——この発想の転換が、エージェント時代のエンジニアに求められるスキルです。
もっと深掘りしたい方は、以下の記事が参考になります。
- ハーネスエンジニアリングとは何か——コンテキストエンジニアリングの次のパラダイム（Qiita）
- ハーネスエンジニアリング——Martin Fowlerの批評から再考する（Qiita）
- プロンプトエンジニアからハーネスエンジニアリングへ（Qiita）
- 業務を完遂し続けるためのハーネスエンジニアリング（note）
あわせて読みたい
