Claude Code › 応用

ハーネスエンジニアリングとは|AIが決まりを守る環境の作り方

「ハーネスエンジニアリング」という言葉、最近よく見かけますよね。

CLAUDE.md に決まりを書いたのに守られない。同じ失敗を何度も繰り返す。

そんな悩みに効く考え方として、名前が出てくることが増えました。

この記事では、言葉の意味、なぜ必要なのか、中身の4つの部品と始め方を説明します。最後に、コードを書かずに Claude Code と Codex で仕事を回している私の実例を紹介します。

この記事の結論

ハーネスエンジニアリングは、AI のモデル以外の仕組みを整えて、決まりを守れる環境を作ることです。

全部を最初から入れる必要はありません。失敗が起きた所にだけ、「記録 → 決まり → 止める仕組み」の順で足していきます。

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

モデル以外の全部がハーネス

ハーネスエンジニアリングでは、モデル(AI の頭脳の部分)以外の仕組みの全部をハーネスと呼びます。決まりを書いたファイル、使わせる機能、止める仕組み、作業の記録、別の AI の確認などが入ります。

Claude Code と Codex を左右に並べ、それぞれ真ん中のモデルの周りを、決まりのファイル・フック・スキル・MCP・サブエージェント・権限の設定の札が囲む図

Claude Code なら CLAUDE.md・フック・スキル・MCP・サブエージェント・権限モード、Codex なら AGENTS.md・フック・スキル・MCP・サブエージェント・サンドボックスです。中で動くモデルの周りにある、これらの仕組みがハーネスにあたります。

エンジニアリングは、その仕組みを設計して、使いながら直していくことです。AI への頼み方ではなく、AI が働く場所のほうを作り込みます。

初心者

新しいソフトを入れる話ですか?

芝田

いいえ。今使っている Claude Code や Codex の周りを整える考え方です。

なぜハーネスが必要なのか

モデルが賢くなっても、任せた仕事が思ったとおりに進まないことがあります。公式の記事には、AI の弱点が主に3つ書かれています。

AI の弱点 起きること 書いている公式
前の会話を覚えていない 新しい会話を始めると、やりかけの作業の状態が分からない Anthropic(2025年11月)
長い作業で手順が抜ける 一度に全部やろうとして途中で行き詰まる。途中まででも「完了」と言ってしまう Anthropic(2025年11月)
自分の作業を甘く採点する 出来が平凡でも、自信をもってほめる Anthropic(2026年3月)

Anthropic は1つ目を、前の担当の記憶が無いまま交代で働くエンジニアにたとえています。

OpenAI も、最初に作業が思ったより進まなかったのは、Codex の力が足りなかったからではなく、働く環境が十分に決められていなかったからだと書いています。

そこでハーネスエンジニアリングでは、モデルそのものには手を入れず、弱点を周りの仕組みで補います。

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

プロンプト、コンテキスト、ハーネスの3つを、内側から外側へ入れ子の円で描いた図。ハーネスがいちばん外側

プロンプトエンジニアリングは、1回の頼み方を工夫することです。コンテキストエンジニアリングは、何を読ませるかを設計することです。

ハーネスエンジニアリングは、その外側にあります。AI が作業して、間違えて、気づいて直す流れ全体を、仕組みとして回るようにします。

✓ 読ませる情報の設計は、こちらの記事でコンテキストエンジニアリングとは?AIに読ませる情報の設計術

公式の2本の記事で見るハーネス

2025年11月の Anthropic の記事と、2026年2月の OpenAI の記事を、左から右への年表に並べた図

Anthropic は2025年11月26日の記事の題に「harness」を使い、長く動く AI の作業を回に分けて引き継ぐ方法を紹介しました。

最初の回の AI が、進み具合を書くファイルと最初の git の記録を用意します。次の回からは少しずつ進めて、記録を残します。

新しい会話でも、そのファイルと git の記録を読めば作業の状態が分かる、という考え方です。

OpenAI は2026年2月11日に「ハーネスエンジニアリング」を題にした記事を出しています。手書きのコードを使わずに約100万行の製品を作った経験から、エンジニアの主な仕事が、AI が働く環境を設計することに変わったと書いています。

記事の中で目立つのは、次の3つです。

  • 長い説明書を渡さず、約100行の AGENTS.md を目次にして、詳しいことは別の文書に置く
  • 文書だけでは守られない決まりは、点検のプログラムに変える。エラーの文に直し方を書いておく
  • AI がつまずいたら、足りない仕組み(ツール・止める仕組み・文書)を探すきっかけにする

誰が最初に言い出したかは、記事によって書き方が分かれています。この記事では決めつけず、公式の2本の中身を紹介します。

ハーネスを作る4つの部品

ハーネスの中身は、役割で分けると4つになります。決まり・止める・記録して次に渡す・確かめるです。

部品 何をするか 代表的な仕組み
決まり 守ってほしいことを書いて、AI に読ませる CLAUDE.md、AGENTS.md、フォルダ別の決まり
止める 決まりを破る操作を、実行の前に止める フック、点検のプログラム、テスト
記録して次に渡す 作業の状態を残して、次の会話に引き継ぐ 進み具合のファイル、git の記録、失敗の記録
確かめる 作った AI とは別の係が、出来を見る 別の AI のレビュー、評価の係

決まり:AI に読ませる約束ごと

Claude Code では CLAUDE.md、Codex では AGENTS.md に、守ってほしいことを書きます。会話を始めると読み込まれます。

Claude Code の公式は、CLAUDE.md を1ファイル200行未満にするよう勧めています。長いほど文脈を使い、守られにくくなるためです。

一部のフォルダでしか使わない決まりは、.claude/rules/ に分けられます。そのフォルダのファイルを扱うときだけ読まれるので、ふだんの決まりを短く保てます。

✓ 決まりをフォルダ別に分ける方法は、こちらの記事でClaude rulesとは|CLAUDE.mdとの違いと読まれる時

止める:決まりを破る前に止める

決まりは、AI への「お願い」です。公式は、CLAUDE.md を守らせる設定ではなく文脈として扱うと書いています。

必ず止めたい操作には、PreToolUse のフック(AI が操作する直前に動くプログラム)を使うよう案内しています。

AI が操作しようとすると、直前でフックが確かめ、決まりに合えば進み、合わなければ止めて理由を返す流れの図

OpenAI の「決まりを点検のプログラムに変える」も、この部品です。お願いで守られない所だけを、止める仕組みに上げます。

記録して次に渡す:会話をまたいで状態を残す

AI は、新しい会話を始めると前の会話を覚えていません。Anthropic も、次の回のために進み具合のファイルと git の記録を残す方法を紹介しています。

残すのは、どこまで進んだか、何を決めたか、何に失敗したかです。次の会話の AI が最初に読む場所に置いて、前の回の続きから始められるようにします。

例えば、進み具合のファイルはこのくらいの短さで足ります。

進み具合(11月6日)
- できた:申し込みの画面
- 途中:一覧の画面(並べ替えがまだ)
- 決めたこと:日付は「2026-11-06」の形で書く
- 失敗:確かめる前に「完了」と書いた → 次は確かめてから書く

確かめる:作った AI に採点させない

Anthropic は、AI に自分の作業を採点させると、出来が平凡でも自信をもってほめる傾向があると書いています。作る係と評価する係を分けるのが効く、という整理です。

「完了しました」という報告も、そのまま信じず、記録や画面で確かめる係を別に置きます。

そら@sora_biz

「レビュー依頼を送りました」「承認をもらいました」と報告されても、本当にやりとりしてるのか、嘘をついてないか、証跡を掘らないと確かめられない。

X で見る

部品を足すときの考え方

部品は、多く入れるほど良くなるわけではありません。

全部入れると、費用だけ増えることがある

6つの部品を試した結果。効いた棚に状態と文脈、差が出なかった棚にリトライ・フック・スキル、Haiku でだけ効いた棚に評価を並べた図

電通総研のテックブログ(2026年8月31日)は、自作の課題で、6つの部品を AI のモデルの Haiku と Opus で、ある場合と無い場合で比べています。両方のモデルではっきり効いたのは、「状態」と「文脈」の2つでした。

評価(別の AI の点検)は、Haiku でだけ効きました。

あらゆる部品を盛った形は、品質を上げずに、手数と費用だけを増やしました。筆者のまとめは「最初は最低限、足りない所だけ少しずつ足す」です。

connect24h@connect24h

「盛れば効く」を疑う姿勢、めちゃくちゃ好きだ。

X で見る

新しいモデルが出たら、外せる部品を見直す

Anthropic は、部品はどれも「モデルが自分ではできないこと」への仮定だと書いています(2026年3月24日)。

新しいモデルが出たら、効いていない部品を外し、新しくできることのための部品を足します。

Anthropic は一度に大きく削って、どの部品が効いていたか分からなくなりました。そこで、1つずつ外して確かめる方法に変えたそうです。

人気の設定をまとめて入れないでください。部品は、困ったことが起きた所から足します。

ハーネスエンジニアリングの始め方

困ったことを記録し、決まりに1行足し、それでも起きたら止める仕組みに上げる流れを、3段の階段で描いた図

最初から全部をそろえる必要はありません。困ったことが起きた所から、1つずつ足します。

  1. 困ったことを1行で記録する

    AI が間違えたこと、自分が直したことを、日付と一緒に1行で残します。

  2. 2回目が起きたら、決まりに1行足す

    CLAUDE.md(Codex なら AGENTS.md)に、守ってほしいことを具体的に書きます。

  3. それでも起きたら、止める仕組みに上げる

    フックや点検のプログラムで、その操作の前に止まるようにします。作るのは AI に頼めます。

  4. 大事な成果物は、別の AI に確かめさせる

    作った AI とは別の AI に、読み取りだけで確かめてもらいます。

  5. 新しいモデルが出たら、外せる決まりを見直す

    モデルが自分でできるようになったことの決まりは、外して確かめます。

最初の1回は、AI にこう頼むと始めやすいです。

今日の作業で、あなたが間違えたことや、私が直したことを1行ずつ書き出してください。
それぞれについて、次に同じことが起きないように CLAUDE.md に1行足す案と、
フックや点検で止めるならどんな形になるかを、並べて見せてください。
まだ何も変えずに、案だけ見せてください。
✓ 最初のフックの作り方は、こちらの記事でClaude Code hooksの使い方|最初の1本と確かめ方

実例:私の仕組みを4つの役割で見る

私の仕組みを4つの役割に分けた地図。決まり、止める、記録して次に渡す、確かめる

ここからは私の実物です。上の4つの部品を、コードを書かない私がどう組んでいるかを紹介します。

決まり:2026年11月5日時点で、CLAUDE.md は164行です。一部のフォルダでしか使わない決まりは、.claude/rules/ の6つのファイルに分けています。

止める:私のフックは全部で6種類です。そのうち止める役は、元の資料を置くフォルダの既にあるファイルの書き換えを止めるものや、API キーなどを書いたファイル(.env)を直接指定して読むコマンドを止めるものです。

記事の原稿は、15番まで並んだ点検のプログラムを通してから、確認用のページに上げます。

記録して次に渡す:私は失敗を1件ずつ記録していて、その数は432件になりました。作業の区切りでは「締めて」の一言で、記録と保存の7項目を順に回します。

確かめる:記事の原稿を書いたあと、別の AI(Codex)に読み取りだけで確かめさせています。

実例:決まりを守る環境に変えた4つの記録

ここからは、決まりを書いても守られなかった所を、どう変えたかの記録です。記録・決まり・フック・別の AI の確認を組み合わせて変えた4つの例です。

返事が英語になる → 書く直前に決まりを置き直す

設定にも CLAUDE.md にも「日本語で」と書いたのに、作業の途中で返事が英語になることがありました。決まりを何度書き足しても止まりませんでした。

会話の記録を数えると、英語になるのは主に作業の途中の短い一言でした。冒頭に決まりを書くだけでは、途中の英語の返事を防げていませんでした。

フックを入れる前と後で、Opus 5.5 の英語の返事の割合を比べた棒グラフ。7.7%から2.3%へ

そこで、AI が操作するたびに「日本語で」を差し込むフックを Claude Code に作らせました。Opus 5.5 の返事のうち英語と判定されたものの割合は、7.7%(659/8,527件)から 2.3%(156/6,648件)に下がりました。

前後で期間と作業が違うので、同じ条件の実験ではありません。導入前は2026年8月24日〜10月20日、導入後は10月21日〜31日の返事を数えました。

英語の返事は、0にはなっていません。

✓ フックの中身は、こちらの記事でClaude Code が英語になる原因と止める方法|フック2本

失敗メモが読まれない → 会話の始めに読ませる

失敗を記録しても、次の作業で読まれていないことがありました。「書く」決まりはあっても、「読む」決まりが無かったのが原因です。

会話を始めると、直近5日分の失敗の見出しが自動で読み込まれ、作業の前に目に入る流れの図

いまは、会話の始めに1回だけ動くフックで、直近5日分の失敗の見出しを自動で読ませています。前日の失敗が、次の作業の前に目に入ります。

頼んだ言葉が何度も出る → 原稿の点検で止める

記事で使わないでと頼んでいた言葉が、1本の記事の本文や図に9か所も入っていたことがありました。決まりに書いてから、5日後のことです。

そこで、原稿の点検に15番目の検査を足しました。使わない言葉の一覧に1行足すと、本文や画像の説明文にその言葉があるとき、確認用のページに上げる前の点検で止まります。

図の中の文字は、この点検では読めません。画像を頼む文と、できた画像を見て別に確かめます。

使わない言葉の一覧から点検のプログラムへ線が伸び、原稿の中の言葉に赤い印が付いて止まる図

株式会社ジェネフィアの note(2026年11月4日)にも、似た話があります。決まりを書いていたのに AI が別の部門の書きかけを一緒に提出し、提出の直前に確かめて止める仕組みに変えたそうです。

自分の誤りは自分で見つけにくい → 別の AI に確かめさせる

このサイトの1本目の記事は、Codex に読み取りだけで3回レビューさせました。1回目で、重大3件・中6件の指摘がありました。

記録に無い体験の一文や、時系列のずれなどです。3回目で合格しました。

原稿を書く AI と、読み取りだけで確かめる別の AI を、左右の机に分けて描いた図。間を原稿が行き来する

2026年11月4日に書いた記事でも、チャットボットの数字の意味を取り違えていたのを、別の AI が1回目で見つけました。

著者の意見

いちばん助かっているのは、別の AI に確かめさせることです。

よくある質問

プロンプトエンジニアリング・コンテキストエンジニアリングとの違いは?

プロンプトは1回の頼み方、コンテキストは読ませる情報、ハーネスはその外側の仕組み全体です。

ハーネスの中に、ほかの2つが入っていると考えると分かりやすいです。

エンジニアでなくてもできますか?

できます。私もコードは書いていません。

フックや点検のプログラムも、失敗を止める仕組みを作ってほしいと Claude Code に頼んで作りました。

CLAUDE.md は何行までにすればいいですか?

公式の目安は、1ファイル200行未満です(2026年11月5日確認)。

一部のフォルダでしか使わない決まりは、.claude/rules/ に分けると、ふだん読まれる量を減らせます。

✓ CLAUDE.md を縮めた手順は、こちらの記事でCLAUDE.mdベストプラクティス|345行を169行に縮めた実録

Codex でも同じ考え方ですか?

同じです。Codex では決まりのファイルが AGENTS.md になります。

OpenAI は、短い AGENTS.md(約100行)を目次にして、詳しいことは別の文書に置く形を紹介しています。

✓ AGENTS.md の書き方は、こちらの記事でCodexのAGENTS.mdの書き方|日本語テンプレート付き

まとめ

  • ハーネスエンジニアリングは、AI のモデル以外の仕組みを整えて、決まりを守れる環境を作ること
  • 前の会話を覚えていない・長い作業で手順が抜ける・自分に甘い、という AI の弱点を、周りの仕組みで補う
  • 部品は、決まり・止める・記録して次に渡す・確かめる、の4つ
  • 全部入れず、失敗が起きた所にだけ「記録 → 決まり → 止める仕組み」の順で足す
  • 新しいモデルが出たら、効いていない部品を1つずつ外して確かめる

参考資料・出典

公式の資料(2026年11月5日に確認)

第三者の検証・発信(2026年11月5日に確認)

企業・事業者のかたへ

自社の業務に AI エージェントを取り入れたい企業・事業者のかた向けに、無料の AI 業務診断を行っています。

無料のAI業務診断を申し込む

個人で学びたいかたへ

Claude Code を自分の仕事で使えるようになるまで、1対1で伴走します。

個別伴走の申込ページへ

この記事を書いた人

芝田拓望のイラスト芝田拓望DevAIse 代表

DevAIse(ディバイズ)代表。毎日5〜15時間、Claude Code と Codex を使い、記事づくり・情報の整理・毎朝のまとめを AI の仕組みにしています。コードを書かずに作ってきたやり方を、1対1の個別伴走でもお伝えしています。

著者ページへ

関連記事

URL をコピーしました