「ハーネスをやりすぎるとモデルが本来の力を出せなくなるので、ハーネスはやめた」という話を見かけて、少し不安になりました。自分もCLAUDE.mdやルールやスキルをかなり足してきたからです。
調べてみると、盛りすぎると逆効果だという報告はいくつもありました。ただ、ハーネスを全部やめればいいという話でもなさそうです。
盛っても良くならず、減らしたら良くなった
少し前の話ですが、Vercelは2025年12月に、データ分析のエージェントに渡すツールを17個から2個（bashとSQLの実行）に減らした話を書いています。代表的な5問で比べると、成功は4問から5問に増え、かかった時間は274.8秒から77.4秒に縮み、トークンは約37%減りました。
We were building tools to summarize what was already legible.
（すでに読めるものを要約するためのツールを作っていた）
※測ったのは5問だけです。（出典: We removed 80% of our agent's tools）
ETH Zurichの研究では、AGENTS.mdのようなコンテキストファイルを渡しても、タスクの成功率はおおむね上がらず、コストは平均で20%以上増えました。人間が書いたファイルでも、LLMに生成させたファイルでも同じ傾向です。
providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average.
（コンテキストファイルを渡しても、タスクの成功率は全体としては上がらず、推論のコストは平均で20%以上増える）
（出典: Evaluating AGENTS.md）
日本語の資料では、Gotaさんの「ハーネスエンジニアリングをやりすぎた話 ~そのハーネスは解体された~」（Harness Engineering Meetup Tokyo #1、2026年4月）があります。設定ファイルが300行を超え、タスクのテンプレートを1つ変えるだけで10箇所を直す必要が出てきたそうです。全体のテストにも1時間かかるので、どの修正が効いたのか分からなくなった、という話です。（出典: Speaker Deck）
AIは渡されたものを全部読んで、全部守ろうとする
AIは、渡されたルールや情報を全部読んだうえで動きます。そのため、量が増えると次のようなことが起きます。
- 今の作業に関係ないルールまで気にするようになり、本当に大事なルールの重みが薄まります
- ツールが多いと、どれを使うかで迷います。似たツールがあると選び間違えます
- ルール同士が少しずつ矛盾していると、どちらを守るかで止まったり、回り道をしたりします
- 古いモデルのために書いた細かい手順が、新しいモデルには余計な縛りになります
いちばん分かりやすいのは矛盾です。ルールは1つずつ足していくので、1つずつ読むとどれも正しく見えます。
<!-- CLAUDE.md -->
- コードを変更したら、必ずテストを実行してから完了とすること
<!-- .claude/rules/safety.md（あとから足した） -->
- DBに接続するコマンドは絶対に実行しないこと
テストがDBにつながるリポジトリでは、この2つがぶつかります。AIは「必ず」と「絶対に」の両方を守ろうとして、テストを飛ばして完了と言ったり、DBにつながないようにテストを書き換えたり、何度も確認を求めて止まったりします。書いた本人は、2つが同時に効く場面を想定していませんでした。
ルールが数行のうちはすぐ気づけます。何十行にもなると、どこでぶつかっているのかを人間が探すのも大変になります。
削るのは指示、残すのはドメイン知識と強制の仕組み
ハーネスと一言で言っても、中身は2種類あると思っています。
- 指示: CLAUDE.mdやルールに「こうして」「これはしないで」と書くもの。AIが読んで守ろうとしますが、守るかどうかはAI次第です
- 強制: hook、権限の設定、テスト、lintのように、AIの判断と関係なく必ず止めたり確かめたりする仕組み
盛りすぎで困るのは、ほとんどが指示のほうです。増えるほど迷い、矛盾し、古くなります。強制の仕組みは、増えてもAIを迷わせません。止めるか通すかを決めるのは仕組みの側だからです。この2つを同じ「ハーネス」と呼んでいると、削るときに強制の仕組みまで削る対象に見えてしまいます。「ハーネスをやめた」という話も、この2つが混ざっているように見えます。分けておけば、どこを消せばいいかも分かりやすくなります。
さっきの矛盾の例も、両方が指示だったから起きました。「DBに接続しない」をhookにしておけば、AIはテストを実行しようとした時点で止められます。迷って回り道をすることはなく、止められたことを人に伝えて終わります。
そのうえで、削るものと残すものは次のように分けています。
| 中身 | 例 | 理由 | |
|---|---|---|---|
| 削る | 手順の指示 | 「こう書いて」「この順でやって」 | モデルが賢くなると要らなくなりやすい |
| 削る | コードを読めば分かること | ディレクトリ構成の説明、使っているライブラリの一覧 | AIが自分で読める |
| 残す | コードを読んでも分からないドメイン知識 | 業務の用語、なぜこの作りになっているかという経緯、取引先や他チームとの約束 | 書いていなければ、モデルがどれだけ賢くても知りようがない |
| 残す | コードから推測できない動かし方 | テスト前にDBの起動が要る、必要な環境変数、普段回すテストの範囲 | 知らないとテストが落ちて、原因探しで回り道をする |
| 残す | 強制の仕組み | hook、テスト | 必ず守らせたいことは、指示に書くのをやめてこちらに移す |
Vercelの「すでに読めるものを要約するツールを作っていた」という一文は、表の「コードを読めば分かること」と同じ話だと思います。コードから分かることを書き直しても効果はなく、コードの外にしかない知識を書いたときに効きます。
このブログのリポジトリでも、102行あったCLAUDE.mdを50行にしました。いつでも要る情報だけをCLAUDE.mdに残し、ルールは.claude/rules/に、媒体ごとの情報はフォルダのCLAUDE.mdとスキルに分けています。分けたあとどう変わったかは、しばらく使ってからまた書こうと思います。
CLAUDE.mdの中身を「いつでも要るか、作業やフォルダごとか」と「ルールか、情報か」で仕分けて、置き場所を提案させるスキルも作りました。hookやlintに移せそうなものも拾います。よければ使ってみてください。
Claude Codeの/doctor prompt-auditもおすすめです。古いモデル向けに書いた指示や、もう存在しないファイルへの参照、指示同士の矛盾を探してくれます。tidy-contextが置き場所を見るのに対して、こちらは書いた内容が今も正しいかを見ます。使ってみた話は別の記事に書きました。
この記事はZennにも投稿しています。