この記事でわかること:

  • ハーネスエンジニアリングとは、AIエージェントのうちモデル以外の部分(指示ファイル・ツールと権限・フック・テスト・レビュー役)を設計し、同じ失敗を仕組みで減らす営みです
  • プロンプトは指示文の書き方、コンテキストはモデルに見せる情報、ハーネスは行動の前後で導き・止め・測る仕組みを設計の対象にします
  • 部品は「事前に導く/事後に検知する」と「決定的/LLM判定」の2軸で4つに分けられます
  • 手元の35リポジトリを全数で数えると、指示ファイルは全部にある一方、Claude Codeの設定に足した拒否リストやPreToolUseフックは0本、テスト一式を持つのは12本でした
  • 同じモデルでハーネスだけ変えて点数が動いた実測と、優位性が確認されなかった反例を並べ、最初に足す部品の順番を提案します

なお、ここで扱うのは電線を束ねるワイヤーハーネスの設計ではなく、AIエージェントの話です。


1. ハーネスエンジニアリングとは

定義: ハーネスエンジニアリングとは、AIエージェントのうちモデル以外の部分を設計し、エージェントが同じ間違いを繰り返さないように導き・検知し・修正する仕組みを作ることです。

「モデル以外のすべて」という捉え方は、LangChainのVivek Trivedyが「Agent = Model + Harness」と書いた記事(LangChain 2026-03-10)や、ThoughtworksのBirgitta Böckelerの記事(martinfowler.com 2026-04-02)に共通しています。Claude Codeの公式ドキュメントも、モデルの周りでツールを与えコンテキストを管理する層を「agentic harness」と呼んでいます(Claude Code Docs『How Claude Code works』)。

「同じ間違いを繰り返さない」という目的は、Mitchell Hashimotoのブログの言い方に沿っています。エージェントが間違えるたびに、二度と同じ間違いをしない解決策を作るという考え方で、手段としてAGENTS.mdの更新と自作スクリプトを挙げています(mitchellh.com 2026-02-05)。

harnessはもともと馬具を指す語です(gihyo.jp 2026-10-02)。

「ハーネス」という語には2つの粒度があります。Böckelerは、ツール提供者が作る層を「builder harness」、利用者がその上に足す層を「user harness」と分けています(martinfowler.com 2026-04-02)。Claude CodeやCodexそのものは前者で、この記事で「自分のリポジトリに足す」と書くときは後者を指します。


2. プロンプト・コンテキストとの違い

観点プロンプトエンジニアリングコンテキストエンジニアリングハーネスエンジニアリング
設計の対象指示文(system promptを含む)の書き方と構成推論時にモデルへ渡すトークンの集合モデルの外側のツール・権限・フック・検証・記録
いつ効くかその指示を読む応答毎ターンの入力行動の前(導く)と後(止める・測る・直す)
失敗したとき出力がずれる必要な情報が欠けるか、ノイズで精度が落ちる間違った行動が止まらない、または検知されずに残る
代表例役割指定、出力形式の指定RAG、コンパクション、サブエージェントでの分離CLAUDE.md・AGENTS.md、PreToolUseフック、テストとlint、レビュー役のエージェント

表の整理は筆者によるものです。Anthropicはコンテキストエンジニアリングを「プロンプトエンジニアリングの自然な発展」と位置づけています(Anthropic Engineering 2025-09-29)。

ハーネスとコンテキストのどちらがどちらを含むかは、書き手と対象範囲で見方が分かれます。Böckelerはコーディングエージェントのuser harnessに絞って、それを作ることをコンテキストエンジニアリングの一形態と書き(martinfowler.com 2026-04-02)、HumanLayerも部分集合という立場です(HumanLayer 2026-03-12)。一方、InfoQの記事に載ったMartin Fowlerのコメントは、ハーネスがコンテキストエンジニアリング・アーキテクチャ上の制約・ガベージコレクションを含むという逆向きです(InfoQ 2026-02-21)。論じている範囲が違うため単純な対立とは言えず、どちらかを正しいと決める一次資料もありません。

実務で違いが一番はっきり出るのは「お願い」か「強制」かです。Claude Codeの公式ドキュメントは、CLAUDE.mdに書いた「.envを編集するな」は保証ではなくお願いで、編集を止めるPreToolUseフックが強制だと説明し、毎回守らせたい規則はフックにするよう勧めています(Claude Code Docs『Extend Claude Code』)。


3. 言葉が広まった経緯

誰が言い出したかは1人に決められません。公開日と著者が確認できた順に並べます。

公開日著者・媒体内容
2025-09-29Anthropic(claude.com)Claude Code SDKをClaude Agent SDKに改名し、Claude Codeを動かすエージェントハーネスを他用途に開放(記事)
2025-11-26Justin Young(Anthropic Engineering)「Effective harnesses for long-running agents」。セッションをまたぐ引き継ぎの設計(記事)
2026-02-05Mitchell Hashimoto「My AI Adoption Journey」のStep 5「Engineer the Harness」で、この取り組みをharness engineeringと呼ぶようになったと記述(記事)
2026年2月(2026-02-11とされるが原本は取得できず未確認)OpenAI Codexチーム「Harness engineering: leveraging Codex in an agent-first world」(2026-02-17付のBöckelerのメモが言及)
2026-02-17Vivek Trivedy(LangChain)「Improving Deep Agents with harness engineering」(記事)
2026-02-17Birgitta Böckelermartinfowler.comに短い初版メモを掲載(4月の記事で置き換え)(4月の記事の記載)
2026-03-12HumanLayer「Skill Issue: Harness Engineering for Coding Agents」。語をVivek Trivedyの造語と紹介(記事)
2026-04-02Birgitta Böckeler「Harness engineering for coding agent users」(記事)

「harness engineering」という語について、日付つきで確認できた最も早い用例はHashimotoの記事ですが、本人は「こう呼ぶようになった」と書いているだけで、HumanLayerはTrivedyの造語としています。なお、Anthropicの「Building effective agents」(2024-12-19)と「Effective context engineering for AI agents」(2025-09-29)の本文にはharnessの語が出てきません。

OpenAIの記事の中身は、InfoQの要約で確認できた範囲に限ります。5か月の社内実験で約100万行のベータ版製品を作って出荷し、手書きのソースコードはなかったという内容です(InfoQ 2026-02-21)。PR件数や関わったエンジニアの人数は、本文を確認できなかったため書きません。


4. 検証環境と一次資料の対応表

推論性能は測っていないため、GPUやVRAMの欄はありません。

項目内容
棚卸しの実行環境DGX Spark(Ubuntu系Linux、aarch64)
棚卸しの対象作業ディレクトリ直下でCLAUDE.mdを置いたgitリポジトリ35本(全数)
数え方bash・GNU grep・gitによるファイル有無の判定と行数・一致数の集計(コマンドは付録)
ツールのバージョンGNU grep 3.11、git 2.43.0、Claude Code 2.1.325(2026-11-17取得)
検証日2026-11-17
主張一次資料種別確認日
ハーネスはモデル以外のすべてLangChain「The Anatomy of an Agent Harness」、Böckeler記事企業ブログ/専門家の解説2026-11-17
CLAUDE.mdの指示はお願いで、強制はフックClaude Code Docs「Extend Claude Code」公式ドキュメント2026-11-17
CLAUDE.mdは200行未満を目安にClaude Code Docs「Extend Claude Code」公式ドキュメント2026-11-17
同じモデルで52.8→66.5LangChain 2026-02-17開発元による測定2026-11-17
同じモデルで62.7%→98.6%ARC Prize 2026-09-03評価主催者による測定2026-11-17
既製ハーネスは既定のscaffoldを上回らずMETR 2026-02-13第三者の測定2026-11-17

5. 仕組み

Claude Codeの公式ドキュメントは、エージェントループを「コンテキスト収集→行動→結果の検証」の3段階で説明しています(Claude Code Docs『How Claude Code works』)。部品は、このループのどこに差し込むかで役割が決まります。

  1. セッション開始: 指示ファイル(CLAUDE.md・AGENTS.md)が読み込まれる。前回の進捗メモは、読むよう指示しておいた場合に読まれる
  2. 行動の前: 権限設定とPreToolUseフックが、許可されていない操作を止める
  3. 行動: モデルがツールを呼び、ファイルを編集しコマンドを実行する
  4. 行動の後: PostToolUseフック・テスト・lint・型検査が結果を検知する
  5. 完了の前: レビュー役のエージェントや人が、仕様どおりかを判定する
  6. 次回への持ち越し: 失敗の原因を指示ファイルかフックに書き足し、1に戻る

Böckelerは1〜2の側をguides(事前に方向づけるfeedforward)、4〜5の側をsensors(事後に観測して自己修正させるfeedback)と呼びます(martinfowler.com 2026-04-02)。6が、Hashimotoの言う「二度と同じ間違いをしない仕組みを作る」部分です。

長時間タスクでは、1の前に引き継ぎ成果物が加わります。Anthropicの記事では、初期化用のエージェントがinit.sh・進捗ログ・初回コミットを作り、以後のエージェントはそれを読んで1機能ずつ進めます。claude.aiのクローンでは200を超える機能リスト(JSON)を全部「未達」から始めました(Anthropic Engineering 2025-11-26)。同じ記事は、コンパクションだけでは足りないとも書いています。


6. 部品の分類

6-1. 2×2の4区分

Böckelerの2軸(guides/sensors × computational/inferential)で部品を並べると、次の表になります。

決定的(CPUが判定)LLM判定
事前に導く権限の許可・拒否リスト、スクリプトで判定するPreToolUseフック、型付きの専用ツールCLAUDE.md・AGENTS.md、スキル、計画を先に書かせる指示、prompt型・agent型のPreToolUseフック
事後に検知するテスト、lint、型検査、スクリプトで判定するPostToolUseフックレビュー役のエージェント、LLM-as-judge、ファクトチェック、prompt型・agent型のPostToolUseフック

フックは、どのイベントで呼ばれるかと、中の判定方式が別です。Claude Codeには、LLMに判定させるprompt型・agent型のフックもあります(Claude Code Docs『Hooks reference』)。

決定的な部品は毎回同じ結果を返し、速く安価です。LLM判定の部品は意味を読めますが、結果がぶれます。AnthropicはAgent SDKの記事で、lintのような明確なルールによるフィードバックを最良とし、LLMを判定役にする方法は頑健さで劣ると書いています(claude.com 2025-09-29)。

6-2. 「5要素」などの数え方は資料ごとに違う

上位の解説記事には「4要素」「5つの柱」といった数え方が見られますが、部品の数え方に公式の定義はありません。資料ごとの扱いを並べます(○=扱う、−=扱わない、?=本文未確認。判定は筆者)。

部品OpenAI(InfoQ・Böckelerの紹介)Anthropic 長時間記事BöckelerClaude Code hooksAGENTS.md
指示・知識○ docsディレクトリに地図・実行計画・設計仕様○ 進捗ログ・機能リスト○ guides−○ 形式そのもの(テスト手順の記載を含む)
ツールと権限○ アーキテクチャ上の制約○ ブラウザ自動化で検証○ computational○ PreToolUseで阻止−
フック・強制?−○○ 本体−
検知(テスト・lint・型)○ 独自のlinterと構造テスト○ E2Eテスト○ sensors○ PostToolUse−
レビュー・評価?−○ inferential−−
長時間タスクの引き継ぎ?○ 中心テーマ−○ SessionStart−

OpenAI列のdocsディレクトリはInfoQの要約、「アーキテクチャ上の制約」はInfoQに載ったFowlerのコメント、linterと構造テストはBöckelerの4月の記事による紹介です(OpenAIの原本は取得できていません)。このほかLangChainは、system prompt/ツール・スキル・MCP/ファイルシステムとサンドボックス/オーケストレーション/フックとミドルウェアという分け方をしています(LangChain 2026-03-10)。HumanLayerは「設定ポイント」として、指示ファイル・MCP・スキル・サブエージェント・フック・バックプレッシャー(型検査やテストで自己検証させる仕組み)を挙げます(HumanLayer 2026-03-12)。

6-3. ツールごとの置き場所

区分Claude Code(公式)Codex(公式)
常時ルールCLAUDE.md(AGENTS.mdも読める)、.claude/rules/AGENTS.md
学習の持ち越しauto memoryMemories
再利用手順SkillsSkills
外部ツールMCPMCP
コンテキストの分離SubagentsSubagents
権限権限モード(変更の巻き戻しは別機能のチェックポイント)今回は公式の権限関連ページを照合していないため空欄

出典はClaude Code Docs『Extend Claude Code』とCodex公式『Customization』です(2026-11-17確認)。Cursorは照合していないため入れていません。


7. 手元のリポジトリで数えたハーネスの実態

7-1. 何を数えたか

筆者の作業ディレクトリ直下で、CLAUDE.mdを置いたgitリポジトリ35本を全数で数えました(2026-11-17)。CLAUDE.mdの行数は最小17行・中央値50行・最大429行で、200行を超えたのは2本です。2026年9月13日にwc -lで数えたときは31本・中央値41行・200行超2本でした(Claude Codeの使い方)。

今回は第6章の4区分の部品が入っているかも数えました。判定条件は次のとおりです(コマンドは付録)。

  • 権限リストとフックは、各リポジトリの.claude/settings.jsonと.claude/settings.local.jsonで判定しました。ユーザー単位の~/.claude/settings.jsonも別に確認しています
  • テスト一式は、gitで管理しているtests/かtest/配下のファイルの有無で判定しました
  • テスト・lintの実行指示は、CLAUDE.mdにpytest・ruff・eslint・mypy・tsc・npm testなどのコマンド名が出るかで判定しました。関数名の一部に含まれる「lint」のような語は数えていません
  • レビュー工程は、CLAUDE.mdにレビュー・review・codex・geminiのいずれかが出るかで判定しました。題材自体がレビューの場合も一致するため、上限側の数字です

7-2. 4区分に当てはめた集計(35本、2026-11-17)

区分該当本数(35本中)内訳
事前に導く・LLM判定(指示ファイル)35(100%)全本にCLAUDE.md、AGENTS.mdは0本
事前に導く・決定的(拒否リスト・PreToolUse)0(0%)権限リストは6本(17%)にあるが、すべて確認を省くallowだけでdenyは0本。ユーザー単位の設定にもdenyとPreToolUseは無し
事後に検知する・決定的(テスト・PostToolUse)12(34%)テスト一式12本。PostToolUseフックは4本(11%)にあるが、いずれも文書のファイル名を検査するもので、テストは走らせない(これも含めると13本)。GitHub Actionsのworkflowは1本あるが、手動実行のデータ収集でテストではない
事後に検知する・LLM判定(レビュー)9以下(26%以下)CLAUDE.mdでの語の一致は9本、専用エージェント定義(.claude/agents/)は0本

読み取れる偏りは2つです。

1つ目は、指示ファイルは全部にあるのに、Claude Codeの設定に足したdenyとPreToolUseフックが1本も無いことです。ただし権限モードによっては許可していない操作の前に人の確認が入り(Claude Code Docs『How Claude Code works』)、エージェントの外で止める仕組みもあり得るため、「お願い」だけで運用しているとまでは言えません。たとえばこのブログの記事生成用リポジトリ(auto-article-generator)は、gitのコミット前フックでdraft: falseの記事のコミットを止めています(第10章)。gitのコミット前フックは35本中2本にあり、何かを止める処理はこの1本だけでした。

2つ目は、テスト一式を持つ12本のうち、CLAUDE.mdでテストやlintのコマンドに触れているのは5本だけだったことです。残る7本では、テストがあってもエージェントに走らせるきっかけが指示ファイルに書かれておらず、フックでテストを走らせているリポジトリもありませんでした。


8. 同じモデルでハーネスだけ変えた実測

ここは筆者の実測ではなく、公開された測定の整理です。

事例モデル(固定)ベンチマークハーネスの違い結果測定者・日付
LangChain deepagents-cligpt-5.2-codexTerminal Bench 2.0完了前チェックや堂々巡り検知などのミドルウェア追加、推論量の配分52.8 → 66.5(LangChainの記載でTop 30 → Top 5)開発元による測定 2026-02-17
ARC-AGI-3GPT-6 Astra(max)ARC-AGI-3 Semi-Private標準ハーネス → Provider Adapter62.7%・26,098ドル → 98.6%・17,332ドルARC Prize 2026-09-03
METR time horizonClaude Opus 4.5 / GPT-5METRの自律タスク群METR既定のscaffold → Claude Code / Codex有意差なしMETR 2026-02-13

LangChainは、モデルをgpt-5.2-codexに固定したまま13.7ポイント上げたと報告しています(LangChain 2026-02-17)。推論量を全部xhighにすると時間切れが増えて53.9%にとどまり(highでは63.6%)、計画と検証だけをxhighにした構成で66.5%でした。自社製品についての開発元の測定です。

ARC Prizeの結果では、同じGPT-6 Astra(max)が標準ハーネスで62.7%、Provider Adapterで98.6%でした(ARC Prize 2026-09-03)。差は筆者の計算で35.9ポイントです。違いの1つは状態の扱いで、Provider Adapterはリクエスト間で不可視の推論状態を保持し、コンパクションも使います。ただしハーネス構成全体の比較で、どの要素がどれだけ効いたかは切り分けられていません。見出しで見かける99.9%はhigh設定の値で、max設定の数字とは別です。ARC Prizeは2つのハーネスを別の問いに答えるものとして、結果を分けて示しています。

METRは、自律タスクのtime horizonでClaude CodeもCodexもMETR既定のscaffoldを上回らなかったと書いています。ブートストラップ標本でClaude Codeが勝ったのは50.7%、Codexは14.5%で、いずれも有意差はありません(METR 2026-02-13)。METR自身、両製品は人が確認しながら使う対話向けで、完全自律の評価とは条件が違うと注記しています。

3例から、ハーネスを替えれば成績が上がるとは言えません。METRの「有意差なし」は効果ゼロの証明ではなく、優位性が確認されなかったという意味です。改善した2例は検証の追加(LangChain)や推論状態の持ち越し(ARC)のように特定の機能を変えたもので、製品のハーネスを丸ごと入れ替えたMETRでは優位性が出ていません。各部品の単独の効果は分からず、条件も違うため直接は比較できません。


9. 既製のハーネスがあるのに、なぜ自前で作るのか

2026年11月16日、Redditのr/ClaudeCodeに「AIハーネスとは何か、なぜ企業はClaude Codeを使うだけでなくハーネス開発者を雇うのか」という趣旨の質問が投稿されました。当サイトが11月17日に収集した時点でスコアは300でした(Reddit r/ClaudeCode)。ここでは投稿やコメントの中身ではなく、公式ブログが挙げる理由を整理します。

  • コードベースが特殊: Stripeは、数億行のコード、Rails以外のRubyとSorbetという構成、LLMが知らない社内ライブラリ、規制とコンプライアンス上の義務を挙げています。自社製エージェントMinionsが生成したPRは、週1,000件超がマージされていると書いています(stripe.dev 2026-02-09)
  • モデルごとの癖に合わせる: Cursorは、新しいモデルごとに数週間かけてハーネスを調整し、学習時と同じ形式のツールを渡すと書いています。慣れない形式は推論トークンとミスを増やすという説明です(Cursor 2026-04-30)
  • 用途がコーディング以外: Anthropic自身も、リサーチ・セキュリティ分析・エージェントチーム・コードレビューでは、Claude Codeの上に専用ハーネスを作ってきたと書いています(claude.dev 2026-06-02)

自前で作る場合もゼロから書くとは限りません。Claude Agent SDKは、Claude Codeと同じツール・ループ・コンテキスト管理をPythonとTypeScriptで提供します(Claude Code Docs『Agent SDK overview』)。StripeもBlockのオープンソースエージェントgooseのフォークを土台にし、社内MCPサーバーで400を超えるツールを用意しています。求人の件数や年収の統計は、一次資料が見つからなかったため書きません。


10. 公開事例と長期運用の1例

公開事例は第3章のOpenAIと第9章のStripe・Cursor・Anthropicで扱いました。ここでは筆者の運用例を1つ深掘りします。

このブログの記事は、Claude Codeで下書きを作り、人が承認してから公開しています。記事生成用のリポジトリ(auto-article-generator)には、事故が起きるたびに部品を足してきました。日付はgitで最初にコミットされた日です。

日付部品区分きっかけ
2026-02-19承認画面を通さないと公開されない公開処理事前に導く・決定的生成した記事を人が確認してから公開するため
2026-02-28太字記号と日本語の括弧の並びの自動修正と、品質チェックと記録の更新を一度に行う再チェックのスクリプト事後に修正・決定的太字が描画されない事故と、チェック後の記録の更新漏れを防ぐため
2026-03-15文字化け・金額の不整合・定型表現などを数える静的チェック(LLMを使わない)事後に検知・決定的生成文に文字化けや金額の桁違いが残った記事があったため
2026-04-22新規記事はdraft: trueで作る規則と、draft: falseの記事のコミットを止めるgitのコミット前フック事前に導く・LLM判定+決定的承認前の記事が公開されかねない事態の再発防止
2026-05-18自動修正の対象外の並びに対する執筆時の規則と、書き出し後の検索点検事前に導く・LLM判定+事後に検知・決定的自動修正の対象外の並びで太字が描画されない事故があったため
2026-07-12主張ごとのファクトチェック台帳(外部サービスでの確認は2026年4月には始めていた)事後に検知・LLM判定数字や日付の取り違えを、執筆とは別の目で拾うため

部品を足す順番は一定ではありません。公開の承認のように最初から決定的な仕組みで始めたものもあれば、draftの件のように事故の直後に規則とフックを同時に入れたもの、太字の件のように自動修正の取りこぼしを後から規則と点検で補ったものもあります。

第7章の集計と照らすと、このリポジトリもClaude Codeの設定に拒否リストとPreToolUseフックは持っていません。公開を止める役は、Claude Codeの外にあるgitのコミット前フックと承認画面の公開処理が担っています。ハーネスの部品はエージェントの設定ファイルの中だけにあるとは限りません。


11. 限界・反対意見・向かない場面

  • モデルが良くなると部品が重りになる: Anthropic Labsは、ハーネスの各部品はモデルが単独でできないことについての仮定だと書き、Opus 4.6ではスプリント分割を外しました(Anthropic Engineering 2026-03-24)。Sonnet 4.5向けに入れたコンテキストのリセットも、Opus 4.5では不要な重りになったとしています(claude.com 2026-04-02)
  • 費用と時間が増える: 同じAnthropic Labsの記事にある、ゲームを作らせた個別の実験(上のスプリント分割の話とは別の比較)では、単体実行が約20分・9ドルで壊れた結果、フルハーネスが約6時間・200ドルでした。評価役が費用に見合うのは、タスクが現行モデル単独で安定してこなせる範囲を超えるとき、という条件つきです
  • センサーは仕様の曖昧さを救えない: Böckelerは、人が望みをはっきり書いていなければ、正しさはどのセンサーの守備範囲でもないと書いています。AIが書いたテストを信頼しすぎる危うさや、レガシーなコードほどハーネスを作りにくい点も指摘しています(martinfowler.com 2026-04-02)
  • ツール定義を盛りすぎる: MCPサーバーやスキルを足すと、コンテキストに載る定義が増えることがあります(どこまで常時読み込まれるかは機能や設定で異なります)。量の目安はMCPサーバーの選び方で扱いました
  • 小さな使い捨てタスクには過剰: 1回で終わるスクリプトや調査では、フックやレビュー役を用意する手間に見合わないことが多い、というのが筆者の見方です。Anthropicも2024年の時点で、成功例は複雑なフレームワークではなく単純で組み合わせ可能なパターンだったと書いています(Anthropic Engineering 2024-12-19)

12. 始め方

公式ドキュメントの目安と第7章の集計から、既存のリポジトリに足す順番を提案します。

  1. 指示ファイルを1本置く: Claude CodeならCLAUDE.md、CodexならAGENTS.md。ビルド・テストのコマンドと、守ってほしい規約だけを書きます。Claude Codeの公式は200行未満を勧めています
  2. 既存のテストとlintをループにつなぐ: 第7章では、テスト一式を持つ12本のうち7本で、CLAUDE.mdに実行コマンドが見つかりませんでした(コマンド名検索による判定)。指示ファイルに実行コマンドを書けば、既存テストでの自己検証を促せます。指示は実行の保証ではないので、毎回走らせたい場合はフックやCIにつなぎます
  3. 同じ間違いが2回出たら書き足す: 公式も、規約やコマンドを2回間違えたらCLAUDE.mdへ、と書いています(Claude Code Docs)
  4. 毎回守らせたい1つだけフックか拒否リストにする: 秘密ファイルの編集禁止や、消されて困るディレクトリの保護などです。第7章の35本では、Claude Codeの設定でこの区分を使っているものは0本でした
  5. 長時間タスクなら進捗ファイルを残させる: Anthropicの記事の進捗ログと機能リストの形が参考になります
  6. 最後にレビュー役: 別エージェントや外部レビューは費用がかかるので、決定的な検知で拾えない種類の誤りが見えてから足します

CLAUDE.mdを1本作る具体的な手順はClaude Codeの使い方にまとめています。


13. よくある質問

ループエンジニアリングとの違いは何ですか

Addy Osmaniは2026年6月7日の記事で、ループエンジニアリングを、エージェントに指示を出す人の役を仕組みに置き換えることと説明しています。目的を決めるとAIが完了まで反復する仕組みを設計する、という考え方です。同氏はハーネスを1つのエージェントが動く環境と位置づけ、ループエンジニアリングをその1つ上の階に置いています(addyosmani.com 2026-06-07)。統一された定義ではなく、1人の論者の整理です。

OpenAIとはどういう関係ですか

OpenAIのCodexチームは2026年2月に「Harness engineering」という題の記事を出しています(本文は筆者の環境から取得できず、内容はInfoQの要約で確認)。日付つきでは、それより前にMitchell Hashimotoの用例があり、OpenAIが語を作ったとは確認できません。

誰が言い出したのですか

1人には決められません。確認できた最も早い用例はHashimotoの2026年2月5日の記事で、HumanLayerはVivek Trivedyの造語としています(第3章)。

Claude Agent SDKとの関係は

Claude Codeを動かしているハーネスを、自分のアプリに組み込むためのライブラリです。Anthropicは長時間エージェントの記事で、これを汎用のエージェントハーネスと呼んでいます(Anthropic Engineering 2025-11-26)。

CLAUDE.mdを書くだけでもハーネスエンジニアリングですか

指示ファイルは事前に導く部品なので、ハーネスの一部です。ただし公式ドキュメントのとおり、指示はお願いで保証ではありません。守られなかったときに検知する部品を1つ組み合わせて、初めて失敗を減らすループになります。


14. まとめ

  • ハーネスエンジニアリングは、モデル以外の部分を設計して同じ失敗を仕組みで減らす営みです。コンテキストとの包含関係の見方は論者で分かれます
  • 部品は「事前/事後 × 決定的/LLM判定」の4区分で整理できます。手元の35本では指示ファイルが全部にあり、Claude Codeの設定に足した拒否リストやPreToolUseフックは0本、テスト一式を持つ12本のうち実行コマンドを指示ファイルに書いていたのは5本でした
  • 同じモデルで点数が動いた例と、優位性が確認されなかった例の両方があり、足せば上がるものではありません
  • 最初の一手は指示ファイル1本と既存テストの実行指示で、毎回走らせたいものや同じ失敗が2回出た箇所からフック・CIなどの強制の部品に移します

15. 関連記事


付録: 棚卸しに使ったコマンド

実行日は2026-11-17です。作業ディレクトリ直下で次のスクリプトを実行し、1リポジトリ1行の数値を集計しました。.gitの無いフォルダ1つは対象外です。

出力の列は、CLAUDE.mdの行数、AGENTS.mdの有無、allow・deny・PreToolUse・PostToolUseの一致数、テストのファイル数、workflow数、テスト系コマンドの一致数、レビュー関連語の一致数、.claude/agents/のファイル数、gitフック数の順です。

for f in */CLAUDE.md; do
  d=${f%/CLAUDE.md}
  [ -d "$d/.git" ] || continue
  s=$(ls "$d"/.claude/settings.json "$d"/.claude/settings.local.json 2>/dev/null)
  n(){ if [ -n "$s" ]; then cat $s | grep -cE "$1"; else echo 0; fi; }
  printf '%s\t' "$(wc -l < "$f")" \
    "$([ -f "$d/AGENTS.md" ] && echo 1 || echo 0)" \
    "$(n '"allow"')" "$(n '"deny"')" "$(n '"PreToolUse"')" "$(n '"PostToolUse"')" \
    "$(git -C "$d" ls-files 'tests/*' 'test/*' | wc -l)" \
    "$(ls "$d/.github/workflows" 2>/dev/null | wc -l)" \
    "$(grep -cE '(^|[^_a-z])(pytest|ruff|eslint|mypy|tsc|npm (run )?test|make test|unittest)([^a-z]|$)' "$f")" \
    "$(grep -ciE 'レビュー|review|codex|gemini' "$f")" \
    "$(ls "$d/.claude/agents" 2>/dev/null | wc -l)" \
    "$(ls "$d/.git/hooks" | grep -vc '\.sample$')"
  echo
done

ユーザー単位の設定はgrep -cE '"deny"|"PreToolUse"' ~/.claude/settings.jsonで確認しました(一致0件)。フックの中身(イベント名・種類・呼び出すスクリプト)は、該当する設定ファイルのhooks欄を読んで分類しています。