ハーネスとコンテキストの違い：ハーネスエンジニアリングとプロンプト・コンテキストエンジニアリングの比較

要するに：一つのタスクの三つの層

プロンプトエンジニアリングは「どう頼むか」に答え、コンテキストエンジニアリングは「モデルが今何を知っている必要があるか」に答え、ハーネスエンジニアリングは「エージェントはどんな環境で働き、間違えたことをどう知るか」に答えます。これらは競合する手法ではなく、入れ子になった層です。良いプロンプトは良いコンテキストの一部であり、よく設計されたコンテキストはハーネスの一つのサブシステムです。

三つが混同されやすいのは、どれもモデルの振る舞いを変えるからです。ただし、操作できるレバーが違います。エージェントがテストを実行できないなら、どんなに言い回しを工夫したプロンプトも解決になりません。エージェントが昨日の決定を忘れているなら、問題はリクエストの文言ではなく、状態をどこに保存しているかにあります。harness vs context engineering の違いを理解すると、数週間の無駄な作業を省けます。環境を直すべきときに、指示文を書き直さなくて済むからです。

プロンプトエンジニアリング：一回のリクエストの表現

プロンプトエンジニアリングは、リクエストの文章を扱います。役割、タスク、出力形式、例（few-shot）、制約、手順の順序などです。作業単位は一回のモデル呼び出しです。結果は回答によって評価されます。正しいか、形式に合っているか、モデルが脱線していないか。

よく使われる手法は次のとおりです。

• 出力形式を明示する（JSONスキーマ、表、箇条書き）。
• 「入力 → 正しい出力」の例を二〜三個示す。
• 回答の前に段階的に推論させる。
• 指示とデータを、はっきりした区切り記号で分ける。
• してはいけないことを列挙する。

プロンプトエンジニアリングは、「一つの入力に一つの出力」というタスク、例えば分類、情報抽出、翻訳、テンプレートに沿った文章生成によく合います。その限界は、モデルが行動し始めたときに見えてきます。ツールを呼び出し、ファイルを変更し、何十ものステップを続けて実行するようになると、品質は一つの文言ではなく、モデルを取り巻く環境全体で決まります。

コンテキストエンジニアリング：モデルのウィンドウに何が入るか

コンテキストエンジニアリングは、各ステップでコンテキストウィンドウの中身を管理することです。ウィンドウには限りがあり、長いセッションのエージェントはコマンドの出力、ファイルの内容、会話履歴を蓄積していきます。目標は、その時点で必要なものがウィンドウにあり、余計なものがないことです。

これには次のものが含まれます。

• 選別：タスクに応じて、どのファイル、文書、コード断片を読み込むか（検索、RAG、必要時の読み取り）。
• 圧縮：長い履歴の要約、コマンド出力の切り詰め、セッションの圧縮。
• 構造化：入口の指示ファイルを目次として使い、詳細は必要なときに開く独立したドキュメントに置く。
• 分離：副次的な作業を、独立したクリーンなコンテキストを持つサブエージェントに任せ、メインのスレッドを汚さない。

コンテキストエンジニアリングの指標は、エージェントが必要な瞬間に正しいルールや事実を見つけられたか、そしてノイズに埋もれていないかです。典型的な症状は、ルールがCLAUDE.mdに書いてあるのにエージェントが破ってしまうことです。ファイルが五ページあり、ルールがトーンの指定やチームリーダーの好みに埋もれてしまっているからです。

ハーネスエンジニアリング：モデルを取り巻くすべて

ハーネス（harness、「馬具」）は、エージェントが働く環境です。モデルはその中の一つの部品で、回路に一度だけ組み込まれます。残りのすべて、つまり指示、ツール、環境、状態、フィードバックは、エンジニアが設計します。ハーネスエンジニアリングは、エージェントがコードを書くだけでなく、それを実行し、検証し、エラーに気づき、次のセッションで同じ場所から作業を続けられるようにすることを担います。

ハーネスは五つのサブシステムに分解できます。

コンテキストエンジニアリングは、この表の最初の二つのサブシステムの中に存在します。指示やツールの出力がウィンドウにどう入るかを決めるからです。一方ハーネスは、コンテキストに入れられないものを加えます。動く検証コマンド、再現可能な環境、再起動後も残る状態ファイルです。

比較表

プロンプトとコンテキストだけでは足りない理由

よくある例です。チームはエージェントがよくミスをすることに気づき、一週間かけて五ページのAGENTS.mdを書きます。それでもエージェントは、コミット前にリンターを実行しません。原因は文章にはありません。エージェントは適切な権限を持つshellにアクセスできず、リンターもイメージに入っていないのです。これはツールと環境の問題なのに、指示で解決しようとしていました。

二つ目の例です。エージェントは三回連続のセッションで同じバグを修正しようとしています。再起動のたびに、何を試したか覚えていないからです。セッション内のコンテキストエンジニアリングは役に立ちません。ウィンドウはリセットされています。必要なのは状態のサブシステムです。試行と決定を記録するファイルと、作業開始時にそれを読むことを義務付けるルールです。

三つ目の例は最もコストが高いものです。エージェントが「完了」と報告し、単体テストはすべて緑なのに、機能は動きません。「よく確認して」というプロンプトも、文書を増やしたコンテキストも、独立した検証を与えてはくれません。それができるのは、機械からのフィードバックだけです。E2Eテスト、検証スクリプト、あるいは実行者の推論を見ない独立した評価者です。

まとめると、プロンプトとコンテキストが影響するのは、モデルが何を考えるかです。ハーネスが影響するのは、モデルが何をできるか、そして行動した後で何を知るかです。

モデルを替えても解決しない理由

不安定なエージェントへの典型的な反応は、より強力なモデルに替えることです。たいてい解決しません。同じモデルでも、よく整備されたリポジトリでは自信に満ちたベテランのように働き、検証コマンドや技術スタックの説明がないリポジトリでは迷ってしまいます。より強いモデルでも、チームの規約は推測できず、アクセス権のないデータベースにはアクセスできず、壊れたマイグレーションに誰も実行していなければ気づけません。

ハーネスは新しいモデルの登場で古くなるものではありません。指示、再現可能な環境、検査は、どのモデルにも必要です。変わるのは、手取り足取りの指示をどれだけ減らせるかだけです。強いモデルには、手順ではなく不変条件（「データは境界で検証する」）を与えれば十分です。

どの層を直すべきかの見分け方

症状から診断すれば、どんな実験より速く判断できます。

ハーネスを作り始める順序

ゼロから作るなら、現実的な順序は、フィードバック → 指示 → 状態 → 環境 → ツールです。フィードバックが最初なのは、それがないと他の変更の効果を測れないからです。「使えるかどうか」を誠実に答えてくれるコマンドがなければ、指示をどれだけ改善しても、その評価は感覚に頼るしかありません。

最小限の出発点は次のとおりです。

# AGENTS.md（抜粋）
## 検証の方法
- make check   # リンター、型、単体テスト
- make e2e     # エンドツーエンドのシナリオ
両方のコマンドが終了コード0で終わったときだけ、機能は完了です。

## ルール
- MUST：すべてのSQLクエリはパラメータ化する
- MUST：コミット前に make check を実行する
- 決済の詳細：docs/payments.md（決済に関わるタスクのときだけ読む）

最後の行に注目してください。これはハーネスの内部でのコンテキストエンジニアリングそのものです。入口のファイルは教科書ではなく地図です。詳細は「いつ」という条件に応じて読み込まれます。

各部分の貢献を測る方法

ハーネスには、プロンプトにはない指標があります。エージェントが完了を宣言したのに、独立した検査が確認できなかったタスクの割合です。これは verification gap（検証のギャップ）と呼ばれます。直近の10タスクを順に取り、それぞれについてエージェントが「完了」と言ったかどうか、検証が通ったかどうかを記録すれば、変更を比べるための数字が得られます。

どのサブシステムが実際に効いているかを知るには、アブレーションを使います。モデルとタスクの集合を固定し、ハーネスの部品を一つずつ外して、性能がどれだけ落ちるかを見ます。ここで注意すべきことが二つあります。第一に、アブレーションを最初にやるのではなく、まず失敗ログでボトルネックを見つけ、アブレーションは確認のために使います。第二に、部品を外しても性能が落ちなければ、その部品が不要だとは限りません。今回のタスク群がそれを使わなかっただけかもしれません。

よくある間違い

• プロンプトのファイルをハーネスと同一視する。指示は五つのサブシステムの一つにすぎません。レシピの棚があっても、それは厨房ではありません。
• ツールがないことを文章で補おうとする。エージェントの環境でテストが実行できないなら、「必ずテストを実行せよ」と書いても無意味です。
• 指示をどんどん膨らませる。入口のファイルが長いほど、重要なルールが読まれない確率が上がります。重要なルールは、実行可能な検査に変えるべきです。
• エージェントの自己申告を信じる。自分の仕事を評価するモデルは、結果を過大評価しがちです。検査はスクリプトか、クリーンなコンテキストを持つ独立したエージェントが行うべきです。
• ハーネスを一度設定して終わりにする。コードと同じく古くなります。ルールが現実からずれ、コマンドが変わります。定期的な見直しが必要です。

まとめ

プロンプトエンジニアリングは表現を改善し、コンテキストエンジニアリングはモデルのウィンドウに入る情報を選び、ハーネスエンジニアリングは、ツール、環境、状態、検査を含むエージェントの環境全体を設計します。エージェントが長時間にわたって自分でコードを変更する場合、ハーネスが最も重要になります。「エージェントが完了と言った」を「システムが動くと確認した」に変えてくれるからです。したがって harness vs context engineering は二者択一ではありません。コンテキストはハーネスの一部であり、症状が指し示す層を直すべきなのです。このテーマは、ハーネスエンジニアリングの講座で決済バックエンドの実際のプロジェクトを通して解説しています。