ハーネスエンジニアリング入門：Claude Code設定を診断する

「Opus に変えたのに、思ったほど賢くならない」。同僚の一人がそうこぼしていたのを覚えている。話を聞くと、CLAUDE.mdは半年前に書いたまま更新されておらず、フックは一つも設定されていなかった。モデルを疑う前に確認すべき場所が、実は別にあった。

こうした「モデルのせいにしてしまう」ケースは私自身にも心当たりがある。プロンプトを工夫し、コンテキストの詰め方を見直しても伸び悩む時、原因はもっと外側、モデルを取り巻くシステム全体の設計にあることが多い。この「モデルを取り巻くシステム全体」を指す言葉として、2026年に入ってから急速に定着してきたのが「ハーネスエンジニアリング」だ。この記事を読み終える頃には、この考え方の中身と、自分のClaude Codeセットアップの診断のしかたが見えてくるはずだ。

「並のモデル×優れたハーネス」が「優れたモデル×悪いハーネス」に勝つ

LangChainの Viv Trivedy は「Agent = Model + Harness. If you're not the model, you're the harness.」という言い方をしている。エージェントはモデル単体ではなく、モデルを取り巻くプロンプト・ツール・コンテキストポリシー・フック・サンドボックス・フィードバックループすべての総体だという捉え方だ。

Daily Dose of DSはこれをもう少し噛み砕いて「プロンプトは振る舞いを"お願いする"もの、ハーネスは振る舞いを"統治する"もの」と表現している。CLAUDE.mdに「テストを書いてから実装して」と書くのはお願いであって保証ではない。本当に守らせたいなら、それを強制する仕組みが要る。

この差は数字にも表れている。Terminal-Bench 2.1の公式リーダーボードでは、同じモデルでもハーネスが変わるとスコアが動く。Fable 5というモデルは、Claude Codeというハーネス上では83.8%を記録する一方、Terminus 2というハーネス上では80.4%にとどまる。GPT-5.5もCodex上で83.1%、Terminus 2上では78.0%と、5.1ポイントの差が出ている。モデルを固定したままハーネスだけを変えて、これだけの差が生まれるということだ。

Google出身のエンジニア、Addy Osmaniはこの現象を「今日のモデルができることと、実際にできているように見えることのギャップの大半はハーネスギャップである」と表現している。モデル間の性能差が縮まるほど、勝敗を分けるのはモデル選びよりハーネス設計になる、という論調が2026年前半で急速に広がった。

プロンプト⊂コンテキスト⊂ハーネスという入れ子構造

ここで整理しておきたいのが、プロンプトエンジニアリング・コンテキストエンジニアリング・ハーネスエンジニアリングの関係だ。当ブログでは以前「Claude Codeのコンテキストエンジニアリング」という記事で、コンテキストウィンドウに何を入れるか、何を圧縮・分離するかという話を扱った。ただ、あの記事で扱った内容は、実はハーネスという大きな箱の中の一要素に過ぎない。

Anthropic自身も「コンテキストエンジニアリングはプロンプトエンジニアリングの自然な延長」と位置づけており、ハーネスエンジニアリングはさらにその外側を包む概念として整理できる。プロンプトを整え、コンテキストを整理しても頭打ちを感じるなら、見直す場所はその外側にある。

一つ注記しておきたい。AWS Bedrock AgentCoreには2026年4月にPublic Previewとなった「Harness」という製品コンポーネント名が存在する。こちらはモデル・プロンプト・ツール定義を1つのAPIでまとめて扱うための固有機能の名前であり、本記事で扱う設計思想としてのハーネスエンジニアリングとは別物だ。同じ単語だが指しているものが違うので、AWSの発表を読むときは混同しないよう注意してほしい。

Claude Codeのハーネスを構成する部品カタログ

Claude Code公式ドキュメントは「ハーネス」というブランド名こそ使っていないが、拡張機能の全体像はそのままハーネスの部品カタログとして読める。自分のセットアップがどこまで埋まっているか、次の表で確認してみてほしい。

⚠️ Agent teamsは実験的機能でデフォルト無効になっており、settings.jsonまたは環境変数でCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定しないと有効化されない。また通常のサブエージェントより実行コストが高いため、試す場合はまず小さいタスクで挙動とコストを確認してから使ってほしい。

この表を見て「Hooksを一つも設定していない」と気づいた人は多いはずだ。CLAUDE.mdに「.envを編集しないで」と書いても、それだけでは強制力を持たない。本当に守らせたいなら、PreToolUseフックで機械的にブロックする。これが「お願い」から「統治」への転換であり、ハーネスエンジニアリングの核にある発想だ。

小さな一歩から始めるハーネス設計

ここまでの話を聞くと、大掛かりなシステムを組まないといけないと身構えてしまうかもしれない。実際、Anthropicが公開したレトロゲームメーカーの実験では、単一エージェントによるソロ実行が20分・9ドルで基本機能すら動かなかったのに対し、プランナー・ジェネレーター・エバリューターの3エージェントによるフルハーネスは6時間・200ドルをかけて完全に機能する実装を仕上げている。約20倍のコストをかけて、動くものを手に入れた計算だ。

ただ、これは個人開発者や小規模チームがいきなり真似すべき例ではない。むしろ最初の一歩はもっと小さくていい。CLAUDE.mdを1本書き、そこに「本当に守ってほしいルール」を1つだけPreToolUseフックに移す。それだけで「お願い」から「強制」への転換を体験できる。

その次の段階として使えるのが、生成と評価を分離する発想だ。実装したエージェント自身に「テストは通ったか」と聞いて「はい」と答えたら完了扱いにする、というのは自己評価の典型的な失敗パターンだ。自分の成果を採点する側は甘くなりやすい。Anthropic公式が公開しているanthropics/cwc-long-running-agentsでは、書き込み・編集権限を持たない独立した評価用サブエージェントを用意し、PASSかNEEDS_WORKだけを返させるパターンが示されている。これはSubagentsが1体あればすぐ試せる規模の仕組みだ。

Addy Osmaniが提唱する「ラチェット」の考え方も参考になる。良いCLAUDE.mdの各行は、実際に起きた具体的な失敗に遡れるべきだという原則だ。思いつきでルールを足すのではなく、実際に踏んだ失敗を1つずつ記録に変えていく。Osmaniは60行程度を目安に挙げているが、それだけの分量でも、そういう積み重ねであれば十分に機能する。

大掛かりな3エージェント構成は、長時間かけて機能をまるごと作り切りたいときの選択肢の一つとして頭の片隅に置いておけばいい。まずはCLAUDE.md1本とフック1個から動かしてみるほうが、多くの読者にとって手が届きやすいと思う。

モデルが良くなるほどハーネスは要らなくなるのか

ここで一つ疑問が浮かぶ。モデル自体が賢くなれば、こうした仕組みはいずれ不要になるのではないか。実際、Anthropicはモデルの改善によってハーネスの一部要素が不要になる例を認めている。Sonnet 4.5では必須だった「コンテキストリセット機構」が、Opus 4.6では不要になったという研究者コメントが紹介されている、という報告がある。一次ソースを直接確認できていないため、ここは断定を避けて紹介にとどめておく。

この報告が示唆しているのは、ハーネスが消えていくということではなく、ハーネスが担うべき役割が入れ替わり続けるということだと私は捉えている。ある層の複雑さをモデルが吸収してくれれば、エンジニアの手はまた別の層(たとえば複数セッションをまたぐ進捗管理や、生成物の検証)に回せる。モデルのバージョンを上げることと、ハーネスを見直すことは、対立する選択肢ではなく、両輪として並走させるものだ。

まとめ:今すぐ確認できることから

自分のセットアップを診断するなら、まずは5分でできることから手をつけるといい。code.claude.com/docs/en/features-overviewの一覧と自分のプロジェクトを見比べ、CLAUDE.md・Skills・Hooks・Subagents・MCPのうち使っていない層を確認する。そこで「本当は毎回守ってほしいのに、お願いする書き方になっているルール」が見つかったら、今日中にPreToolUseフックへ置き換えてみる。余裕があれば今週のうちに、長めのタスクを1つ選んで進捗ファイルと評価用サブエージェントの組み合わせを試す。モデルやバージョンを変える判断と並べて、ハーネスを見直すことも定期的な点検項目に加えておきたい。

モデルの性能差を追いかけるより先に、自分の手元にあるハーネスを見直してみてほしい。