ハーネスエンジニアリングとは、AIエージェントに渡す指示文だけでなく、モデルの外側の指示・権限・記録・確認を設計することです。Claude Codeの公式ドキュメントは、モデルの周りで道具を用意し、モデルが見る情報を管理する層を「エージェントのハーネス」と呼んでいます。

1回で終わる相談なら、プロンプトを工夫すれば足ります。ハーネスが効いてくるのは、同じ作業を毎月繰り返す、作業が1回の会話に収まらない、チームの誰が頼んでも同じ手順で進めてほしい、といった場面です。

たとえば20人規模の会社で総務と経理を兼ねている方が、毎月の経費精算の一次チェックをClaude Codeに任せたいとします。「規程に沿って確認して」と毎回書くだけでは、先月の判断が引き継がれず、確認漏れにも気づけません。この記事では、言葉の出どころを公式資料で確かめたうえで、経費チェックを題材に4つの要素を小さく組む方法と、失敗したときにどの要素を直せばよいかを整理します。

ハーネスとは何か：モデルの外側にある仕組み

ハーネス（harness）はもともと馬具を指す英語で、AIの文脈ではモデルそのもの以外の部分を指します。Claude Codeでいえば、ファイルを読む・編集する・コマンドを動かすといった道具、起動時に読み込まれる指示ファイル、操作の許可設定、自動チェックなどがハーネスにあたります。

Claude Codeの公式ドキュメントは、Claudeの作業を「情報を集める→作業する→結果を確かめる」の繰り返し（エージェントループ）として説明しています。ハーネスエンジニアリングは、この繰り返しの各段階に、何を読ませ、何を許し、何を記録し、何で確かめるかを決める作業だと考えると分かりやすくなります。

言葉の出どころと、各社の資料が言っていること

考え方を確かめる一次資料として、次の3つがあります。この記事では用語の発明者を特定せず、それぞれの設計上の教訓を使います。

資料 公開日 書かれていること
Anthropic「長時間動くエージェントのための効果的なハーネス」 2025年11月26日 複数の会話にまたがる開発で、最初の会話が作業環境と進捗ファイルを用意し、以降の会話は1機能ずつ進めて記録を残す構成
OpenAI「Harness engineering」 2026年2月11日 人が手でコードを書かずにCodexで製品を作った社内実験の振り返り。失敗したら「何の能力が足りないか」を問い、仕組みとして足す
LangChain「The Anatomy of an Agent Harness」 2026年3月10日 「Agent = Model + Harness」という式と、モデル以外のコード・設定・実行の仕組みをすべてハーネスと呼ぶ定義

OpenAIの記事では、作業が遅かった原因はモデルの能力不足ではなく環境の準備不足だったと書かれています。巨大な指示ファイルは失敗し、約100行の短い目次役のファイルから詳しい資料へ案内する形に切り替えた、という教訓もあります。

ただし、いずれもAIエージェントの開発側が書いた実験や設計の解説です。OpenAIの記事にある開発期間や処理件数は、その社内環境での数字です。あなたの業務で同じ効果が出ることを示すものではありません。

ハーネスを作る4つの要素

業務で考えるときは、ハーネスを編集部の整理として次の4つに分けます。公式の統一分類ではありません。右の列は、Claude Codeで実際にそれを置く場所です。

要素 決めること Claude Codeでの置き場所
指示 毎回守ってほしい事実と決まりごと CLAUDE.md（毎回起動時に読まれる指示ファイル）
道具と権限 使ってよい道具、触ってよいファイル、確認を挟む操作 権限設定（拒否・確認・許可のルール）
作業の記録 どこまで終わったか、何が分かったか 進捗ファイル、作業フォルダの履歴
確認 終わったと判断する条件と、その確かめ方 チェック表、Hooks（設定したイベントに応じて動く処理）

それぞれの要素には、公式ドキュメントから読み取れる注意点があります。

  • 指示：CLAUDE.mdは1ファイル200行未満が公式の目安で、強制力はありません
  • 道具と権限：通常の権限ルールは拒否→確認→許可の順に評価されます。対象ツールや実行方法まで確認します
  • 作業の記録：次の会話は前の会話を覚えていない前提で書きます
  • 確認：自動チェックを足しても、最後の判断は人が持ちます

公式ドキュメントでは、CLAUDE.mdは強制される設定ではなく、Claudeが読んで従おうとする文脈だと明記されています。指示と、操作を制御する仕組みを別に設計するというのが、4つの要素を分ける一番の理由です。

ハーネスの4要素と、失敗したときに直す場所を示した図
ハーネスの4要素と、失敗したときに直す場所を示した図
図解を大きく見る ↗

図の上段は4つの要素と置き場所、下段は「こういう失敗が出たら、この要素を直す」という対応です。下の表と同じ内容を図にしています。

プロンプト・Skills・Hooksとの違い

ハーネスは新しい機能の名前ではなく、既存の機能をどう組み合わせるかという設計の考え方です。よく混同される言葉との関係は次のとおりです。

言葉 何をするものか ハーネスとの関係
プロンプト その場の依頼文 ハーネスに渡す入力。再利用や次回への引継ぎ方法は別に決める
CLAUDE.md 毎回読まれる指示ファイル 「指示」の要素の土台
Skills 手順書をファイルにし、必要なときだけ読ませる機能 「指示」のうち、長い手順をCLAUDE.mdから切り出す場所
Hooks 設定したイベントと条件に応じて動く処理 点検や操作前の判定を実装する場所。設定・対象・失敗時の扱いを確認する
サブエージェント 別の作業枠で調べ物などを任せる機能 調べ物の途中経過で、本来の作業の文脈を埋めないための分担

公式ドキュメントでは、CLAUDE.mdが手順書のように長くなったらSkillsへ移すよう勧めています。Skillsの本文は使うときだけ読み込まれるため、普段の会話を圧迫しません。Skillsの作り方はSKILL.mdで週報を作る実践ガイドで確認できます。Hooksには実行条件やタイムアウトがあり、処理が設定どおり成功したかの確認も必要です。実行後のPostToolUseで点検しても、すでに行われた操作を取り消せるわけではありません。

経費精算の一次チェックで小さく試す

ここからは、4つの要素を1つずつ足していく手順です。以下はこの記事のために用意した提案例で、実際の経費データでの動作検証は行っていません。架空のデータで試し、あなたの会社の規程に置き換えて使ってください。

準備：架空の規程とデータを置く

作業フォルダに、次の2つのファイルを作ります。どちらも練習用に作った架空の内容です。

# 経費規程（練習用）
1. 会議費は1人あたり5,000円まで
2. タクシー代は理由欄に利用理由を書く
3. 電車・バスの交通費を除き、領収書のないものは精算しない
4. 電車・バスの交通費は理由欄に経路を書く

日付,申請者,区分,金額,人数,領収書,理由
9/2,A,会議費,8000,2,あり,取引先と打合せ
9/5,B,タクシー,2400,,あり,23時の帰宅
9/9,C,会議費,18000,3,あり,社内の打合せ
9/12,A,タクシー,1800,,あり,
9/15,D,電車・バス,620,,なし,新宿→品川
9/18,B,消耗品,3300,,なし,プリンター用紙
9/22,E,電車・バス,450,,なし,
9/29,D,書籍,12000,,あり,業務用の参考書

上の2つを、それぞれ「経費規程.md」「経費一覧.csv」という名前で保存します。

手順1：指示を5行だけ書く

作業フォルダにCLAUDE.mdを作り、毎回守ってほしい事実だけを書きます。手順や判断の細かい話はまだ入れません。

# 経費精算の一次チェック
- 規程の正本は「経費規程.md」。ここに書かれていない基準で判定しない
- 元データ（経費一覧.csv）は編集しない。結果は「チェック結果.md」に書く
- 判定は「問題なし」「要確認」の2つだけ。却下の判断は人がする
- 要確認には、規程のどの項目に当たるかを必ず添える
- 作業の最後に「進捗.md」を更新する

手順2：触ってよい範囲を決める

練習では架空のCSVを使い、作業開始前に原本のコピーを作業フォルダの外へ保管します。出力先は「チェック結果.md」と「進捗.md」に限定するよう依頼します。

実務の原本を保護する場合は、管理者と読取専用の保管場所やsandboxの書込み範囲を設定し、許可したツールからも変更できないか試します。Editの拒否ルールだけで、すべての書込みを防げるとは限りません。公式資料は、PythonやNodeなどのプログラム内部からのファイル操作には適用されない場合があると説明しています。指示文・ツール権限・OS側の制御を分けて確認してください。

手順3：進捗ファイルを用意する

Anthropicの記事では、次の会話が状況をすぐ把握できるよう、進捗ファイルと作業履歴を残す構成を紹介しています。経費チェックなら、次のような短いファイルで十分です。

# 進捗
## 対象
- 2026年9月分 経費一覧.csv（全8件）
## 終わったこと
- （Claudeが記入）
## 判断に迷った点
- （Claudeが記入。規程に書かれていない論点はここに残す）
## 次にやること
- （Claudeが記入）

手順4：確認の条件を先に決めて依頼する

依頼文には、終わったと判断する条件を含めます。たとえば次のように頼みます。

経費一覧.csvの8件を、経費規程.mdに沿って一次チェックしてください。
終わったと判断する条件は次の3つです。
1. 8件すべてに「問題なし」か「要確認」が付いている
2. 要確認の全件に、根拠となる規程の項目が書かれている
3. 規程にない理由で要確認にしたものが0件である
最後に、条件を満たしたかを1件ずつ自分で点検し、進捗.mdを更新してください。

規程どおりに判定できていれば、要確認は4件です。9/9の会議費（1人6,000円で規程1）、9/12のタクシー（理由が空欄で規程2）、9/18の消耗品（領収書なしで規程3）、9/22の電車・バス（経路が空欄で規程4）が該当します。9/29の書籍は金額が大きく見えますが、規程に上限がないので問題なしが正解です。迷った点として進捗.mdに残っていれば、規程の空白に気づけます。

結果を人が確かめる点

  • 規程に書かれていない基準（「高すぎる気がする」など）で要確認にしていないか
  • 元のCSVが変更されていないか。作業前のコピーと内容を比較するか、前後のSHA256を照合します。更新日時だけでは同一内容かを判断できません
  • 規程の該当項目として、実在しない条文番号を書いていないか
  • 進捗.mdの「判断に迷った点」に、規程の空白が残されているか

この確認で見つかった問題は、次の章の表で直す場所を決めます。

失敗したときに、どの要素を直すか

OpenAIの記事では、うまくいかないときに「もっと頑張れ」と指示するのではなく、何の能力が足りないかを問い、それを仕組みとして足したと述べています。業務でも同じで、症状を4つの要素のどれかに振り分けると、直す場所がはっきりします。

症状 足りない要素 直し方の例
毎回同じ前提を説明し直している 指示 CLAUDE.mdに事実として1行足す
手順が長く、CLAUDE.mdが読みにくくなった 指示 手順部分をSkillsへ移す
触ってほしくないファイルが変更された 道具と権限 操作経路を確認し、読取専用化・sandbox・対象ツールの設定を見直す
前回どこまで進んだか分からない 作業の記録 進捗ファイルの更新を完了条件に入れる
「終わりました」と言うが漏れがある 確認 完了条件を数で書き、点検させる
決まった点検を忘れることがある 確認 Hooksの対象イベントを設定し、実行記録と失敗時の扱いを確かめる

足すときは1回に1つにし、効いたかどうかを次の月の作業で確かめます。指示を増やしすぎると、かえって重要な決まりが埋もれます。公式ドキュメントも、CLAUDE.mdは長くなるほど守られにくくなると説明しています。

始める前に知っておきたい注意点

ハーネスを整えても、出力の正しさや時間の削減が保証されるわけではありません。特に次の3点に注意してください。

  • CLAUDE.mdやSkillsは指示であり、必ず守られるとは限りません。操作前に止めるには権限やPreToolUseなどを適切に設定し、想定した経路で機能するか試します
  • コマンド型のHooksは、Claude Codeを動かしている環境でコマンドを実行します。他人が作った設定をそのまま入れる前に、中身を確認します
  • 経費・契約・人事など、間違えると影響が大きい判断の最終決定は人が行います

AIに渡せる社内情報の範囲はClaudeのデータ利用と設定の確認ガイドで確認できます。集計の検算も試す場合はClaude for Excelの実践例が参考になります。

まとめ

ハーネスエンジニアリングは、モデルの外側にある指示・道具と権限・作業の記録・確認を組み合わせて、繰り返しの仕事を安定させる設計の考え方です。最初から全部を作る必要はありません。CLAUDE.mdに5行書き、失敗が出たら表に沿って1つずつ足していくのが、業務で試すときの現実的な進め方です。

出典・参考資料

仕様の確認日：2026年10月9日。