ハーネスは設定ファイルではない。

AIエージェント運用の本体を「4回路＋証跡基盤」で捉え直す

Claude Code や Codex の議論になると、すぐに CLAUDE.md や AGENTS.md の書き方へ話が寄ります。
もちろん重要です。
ただ、そこを主役に据えると、AIエージェント運用の本体を見失います。

OpenAI は、0行の人手コードという制約で5か月運用し、約100万行・約1,500PR規模のプロダクトを作る中で、エンジニアの役割が「コードを書く」ことから「環境を設計し、意図を指定し、フィードバックループを組む」ことへ移ると整理しました。
Anthropic は、文脈を有限資源とみなし、長時間タスクでは compaction、構造化メモ、サブエージェント、評価分離が重要になると書いています。
Thoughtworks は、feedforward / feedback、computational / inferential、steering loop、harnessability という語彙で、その制御を言語化しました。
議論は別々に見えて、実は同じ問題を違う断面から見ています。 (OpenAI)(Anthropic)(Thoughtworks)

結論を先に置きます。
ハーネスの本体は設定ファイルではありません。
モデルの外側に置かれた運用制御系であり、その骨格は 状態回路・制御回路・接続回路・評価回路 と、それを持続させる 証跡基盤 にあります。
CLAUDE.md は、その入口のひとつにすぎません。

まず、CLAUDE.md論で止まると本質を外す

AGENTS.md や CLAUDE.md は、たしかに効きます。
Thoughtworks は AGENTS.md をエージェント向け README と位置づけていますし、Anthropic の Claude Code も CLAUDE.md を upfront に読み込みつつ、glob や grep で必要情報を just-in-time に取りに行くハイブリッドを採っています。
けれど OpenAI は、巨大な1枚の AGENTS.md は失敗しやすいとして、短い AGENTS.md を入口にし、構造化された docs/ を system of record に置く設計へ寄せました。
つまり、1枚の魔法の文書を書く話ではなく、リポジトリ全体をエージェントが読める知識空間に作り替える話です。

だから、CLAUDE.md だけを磨いても足りません。
仕様の所在が曖昧で、完了条件が曖昧で、進捗の記録がなく、品質規則が散らばっていれば、エージェントは依然として半盲です。
入口を整えることと、運用系を立ち上げることは、別の仕事です。

ハーネスの本体は「4回路＋証跡基盤」

1. 状態回路

状態回路は、いま何を作っていて、何が終わり、何が未完で、次に何をやるべきかを、エージェントが毎セッション復元できるようにする回路です。Anthropic が initializer agent に init.sh、claude-progress.txt、機能要件ファイルを作らせ、coding agent が feature_list.json と git log を毎回読んでから着手するのは、そのためです。
JSON を選んだのも、Markdown より不適切に上書きされにくく、完了 / 未完の状態を機械的に保持しやすいからでした。

ここで重要なのは、状態回路が単なる「メモ残し」ではないことです。
done の定義、未完了機能の一覧、直前の判断理由、再起動手順まで含めて、セッションをまたぐ一貫性を作る話です。
長時間タスクが壊れるとき、多くは能力不足より先に状態喪失で壊れます。

2. 制御回路

制御回路は、エージェントが逸脱しにくいように事前にガイドし、逸脱したら事後に検知して戻す回路です。
Thoughtworks はこれを feedforward と feedback、さらに computational と inferential で整理しました。前者はルール、スキル、AGENTS.md、アーキテクチャ文書のような事前ガイド、後者はリンター、型チェック、テスト、AIレビューのような事後センサーです。しかも、まずは速くて安い computational な制御を左側に寄せ、繰り返し起きる失敗は steering loop でハーネス側へ戻して再発防止する、と書いています。
Anthropic も一貫して、最も単純な解決から始め、必要なときだけ複雑さを足すべきだと勧めています。

この回路の肝は、エージェントに「もっと賢く振る舞ってほしい」と願うことではありません。
不変量を外側に置くことです。
型、lint、依存方向、禁止操作、完了条件、レビュー観点を、モデルの気分に依存しない形へ外出しする。
そこで初めて、モデルの賢さが歩留まりへ変わります。

3. 接続回路

接続回路は、モデルが何に、どの権限で、どの順序で触れられるかを決める回路です。
OpenAI が Responses API に shell、隔離コンテナ、ファイルシステム、構造化ストレージ、制限付きネットワークを組み込み、「中間ファイルをどこに置くか」「大きな表をどう扱うか」「リトライやタイムアウトをどう扱うか」を環境側で解いたのは、まさに接続回路の設計です。
Anthropic の context engineering でも、全文を upfront で詰め込むのでなく、軽い識別子を持ち、必要なときにツールで just-in-time に読み込む方が有効だと述べています。
Thoughtworks が reference application を live な参照実装として MCP で公開し、エージェントにドリフト検出をさせる話も同じ文脈です。

接続回路の本質は、ツール数ではありません。
ground truth への経路設計です。
どの docs が真実源なのか。
どのコマンドは自動許可で、どこから先は確認が要るのか。
どの参照実装へ寄せるのか。
そこが曖昧だと、エージェントは賢くても迷います。

4. 評価回路

評価回路は、出来上がったものを誰がどう falsify するかを決める回路です。
Anthropic が generator と evaluator を分離し、自己批判より独立 evaluator を懐疑的に調整する方が扱いやすいと報告したのは重要です。さらに evaluator は Playwright MCP で実際にアプリを触って判定し、generator と evaluator は各スプリントの前に sprint contract を結んで done の定義を合わせていました。
もっと大事なのは、その後です。Opus 4.6 ではモデル能力が上がり、以前は evaluator が必須だった領域の一部が、solo 実行でも越えられるようになったため、evaluator は固定で要る部品ではなく、「能力境界の外側にあるタスクにだけ効く部品」だと明示されました。
フルハーネスは 20 倍以上高価でも、境界上のタスクでは意味がある一方、境界内のタスクでは過剰設計になり得ます。

ここを読み違えると、何でも evaluator を足す設計になります。
それは違います。
評価回路は万能薬ではありません。
計算的センサーで十分なタスクに高価な推論的評価を足すと、複雑さだけが増えます。

5. 証跡基盤

4回路は、それだけでは持続しません。
毎回の実行が、次回の実行に引き継がれる証跡基盤が要ります。
OpenAI は repository knowledge を system of record に置き、短い AGENTS.md を目次にし、さらに golden principles をリポジトリへ埋め込み、定期的な background task でドリフトを走査し、1分未満でレビューできる refactoring PR を回しました。人手で毎週金曜に AI slop を掃除していた運用は、週の20%を吸って拡張しなかったからです。
Anthropic も、claude-progress.txt、feature_list.json、git log を組み合わせて、セッションをまたぐ作業履歴を残しています。

証跡基盤がない環境では、compaction はしばしば「混乱の要約」になります。
何を保持し、何を捨て、何が真実源かが決まっていなければ、要約も評価も再開も安定しません。

一次情報をこの地図で読み直す

この地図で見ると、OpenAI が主に解いているのは 接続回路と証跡基盤 です。repo を読めるようにし、構造を強制し、ドリフトを定期回収することで、エージェントが長期的に壊れにくい作業場を作っている。
Anthropic が主に解いているのは 状態回路と評価回路 です。有限な context window の中で coherence を保ち、必要なときだけ evaluator を足す境界条件を探っている。
Thoughtworks が言語化しているのは 制御回路と harnessability です。どのコードベースが制御しやすいか、どの制御をいつ左に寄せるかを整理している。
これは競合する理論ではありません。同じ system を別の断面から見たものです。

ここまで来ると、見え方が変わります。
ハーネスは「便利設定の寄せ集め」ではありません。
小さな Production OS です。
モデルはその上で動く推論器にすぎず、実務の歩留まりは、回路と証跡の設計で決まります。

実務での着手順を、逆にしない

最初に evaluator を足してはいけません。
最初にやるべきは、repo を唯一の真実源に近づけることです。
短い AGENTS.md / CLAUDE.md を入口にし、仕様、アーキテクチャ、不変量、テスト方針、品質基準を docs 側へ逃がす。
次に、feature_list.json や progress log のような状態 artifacts を置く。
そのあとで lint、typecheck、fast test、hooks のような安い計算的制御を先に整える。
さらに shell / browser / DB / reference app への安全な接続を作る。
最後に、タスクがモデル単独では不安定なところだけ evaluator を足す。
この順番なら、複雑さを増やすたびに歩留まりが上がります。
逆順にやると、ハーネスは豪華なのに repo は読みにくい、という一番つらい状態になります。

ハーネス時代に強いのは、モデルを神格化する人ではありません。
どの失敗を、どの回路へ戻すかを決められる人です。
CLAUDE.md を書けることより、壊れた理由を再発防止の構造へ変換できることの方が、ずっと重要です。

――ここまでは思想と全体地図です。
ここから先は、実際に運用へ落とすための最小構成と判定基準です。――