ハーネスの基礎

ハーネスとは何か

Codex CLI でエージェントタスクを走らせるとき、モデル(GPT 本体)は全体の一部にすぎません。 ハーネス(harness) とは、モデルを「うまく動かす枠組み全体」を指す言葉で、 以下のすべてを含みます。

• 指示(システムプロンプト・タスク記述)
• コンテキスト(会話履歴・読み込むファイル・プロジェクト構成)
• ツール(コード編集・コマンド実行・検索・ブラウザ操作・MCP)
• フィードバックループ(テスト結果・Lint エラー・ユーザーからの修正)
• 永続化(メモリファイル・進捗管理・Git 状態)

これは「ハーネスエンジニアリング(harness engineering)」とも呼ばれ、 コーディングエージェントの成功率を上げる設計・構築・改善の工学分野として位置づけられています。

4 層の構成要素

ハーネスを設計するときは、以下の 4 層を意識すると整理しやすくなります。

1. 指示層

システムプロンプトとタスク記述で「何をしてよくて、何をしてはいけないか」を定義します。 Codex CLI では AGENTS.md(または同等の設定ファイル)をプロジェクトルートに置くことで、 プロジェクト固有の慣習・禁止操作・命名規則をエージェントに常時参照させられます。

2. コンテキスト層

モデルが判断に使える情報の範囲を制御します。 ファイル全体を渡すか、関連部分だけを抽出して渡すか。 コンテキストウィンドウは有限なので、必要な情報だけを精度高く渡す設計が重要です。

3. ツール層

エージェントが使えるアクション(ツール)の集合です。 ファイル読み書き・コマンド実行・Web 検索・MCP 経由の外部サービス接続などが該当します。 ツールが多いほど柔軟ですが、誤用リスクも高まるため必要最小限のツールセットに絞る設計が基本です。 Codex CLI では Function Calling・MCP サーバー・シェル実行などを組み合わせます。

4. 永続化層

長時間タスクでは「前回どこまで進んだか」を保持する仕組みが不可欠です。 進捗ファイル・Git コミット・メモリファイルなどを活用して、 セッションをまたいでもタスクを継続できるようにします。 状態管理を外部化(イベントログ・チェックポイント)しておくと、 プロセスが落ちてもタスクを再開しやすくなります。

フィードバックループの重要性

ハーネス設計で最も効果が高い要素の一つがフィードバックループです。 テスト結果・Lint エラー・型チェックの出力をエージェントに返すことで、 「書く → 実行 → エラーを確認 → 修正する」というサイクルを自律的に回せます。

フィードバックが弱いハーネスでは、エージェントは同じ誤りを繰り返したり、 実行せずに「完成した」と誤判断することがあります。 テストを書くこと・CI を整備することは、エージェント活用においても有効な投資です。

AGENTS.md による設計の実践

ハーネス設計の第一歩として、AGENTS.md に以下を記載することを推奨します。

• プロジェクトの概要とディレクトリ構造の説明
• コーディング規約・命名ルール
• 絶対に変更してはいけないファイルや操作
• テストの実行コマンドとチェック方法
• MCP サーバー・利用可能なツールのリスト

詳細記事

ハーネスエンジニアリングの全体像、Codex CLI 向け推奨パターン、Managed Agents の設計思想については、 「Codex / OpenAI 関連記事一覧」 で順次解説していきます。