ハーネスの基礎

ハーネスとは何か

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

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

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

4 層の構成要素

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

1. 指示層

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

2. コンテキスト層

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

3. ツール層

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

4. 永続化層

長時間タスクでは「前回どこまで進んだか」を保持する仕組みが不可欠です。 進捗ファイル・Git コミット・メモリファイルなどを活用して、 セッションをまたいでもタスクを継続できるようにします。 Anthropic の Managed Agents アーキテクチャでは、 セッション状態をイベントログとして外部化し、コンテナ障害時でも状態を失わない設計を実現しています (詳細記事)。

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

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

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

CLAUDE.md による設計の実践

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

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

詳細記事

ハーネスエンジニアリングの全体像は 「ハーネスエンジニアリング入門」で詳しく解説しています。 Managed Agents の設計思想については 「Managed Agents で脳と手を分離する」も参照してください。