CLAUDE.mdの書き方｜「IMPORTANT」は逆効果？Claude Codeで3モデル90回実測

CLAUDE.mdの「IMPORTANT」は逆効果なのか？

範囲があいまいなルールでは逆効果でした。同じ文を強調すると全テスト通過は12回中1回、平叙文では8回です。一方、作業そのものを禁じるルールは強調を外しても結果が変わらず、効いたのは理由と例外を1文足すことでした。

まず全体の結果です。作業は「消費税の端数処理を、インボイス制度に合わせて税率ごとに1回・切り捨てに変える」というもの。仕様が変わるので、古い期待値を持つ既存テストも直さないと全テストは通りません。下の表は、全テストが通った回数です。

同じ文なのに、強調しただけで8回が1回まで落ちました…！ 逆に、強調を外しただけのCとPは0回のまま。正直、Pは「prompt-auditに直してもらえば解決」と思っていたので、ここは予想外でした、、、

ちなみに、新仕様の計算そのものは90回すべてで正解でした（採点用の隠しテスト5件で確認）。差が出たのは「古いテストを新しい仕様に合わせて直し、全体を通すか」の一点です。

Anthropicは強調について何と言っている？

AnthropicのLydia Hallie氏は、IMPORTANTや感嘆符は今のモデルでは不要で、モデルを脱線させると話しています。公式ドキュメントも、強調を重ねるとルールを過剰に適用しがちだとして、この方法を「やめてよい古い助言」に挙げています。

講演はAI Engineerのチャンネルで11月12日に公開され、1日で30万回以上再生されています。該当箇所はこちらです。

「今年前半のベストプラクティスに従っていたなら、CLAUDE.mdにまだ『重要』『絶対にこれをするな』や感嘆符が入っているかもしれません。でも今のモデルなら、それは本当に要りませんし、かえってモデルを脱線させることがあります」

"If you followed our best practices from earlier this year, you may still have things like important or never do this, exclamation mark, all these things in your CLAUDE.md file. But with today's models, you really don't need that and it can actually make the model go off track."

Lydia Hallie（Anthropic・Claude Codeチーム）— Rethinking Claude Code Best Practices 3:03（自動字幕から引用。固有名詞は当研究所で表記を修正）

Hallie氏は続けて、CLAUDE.mdには「Claudeがコードから見られないことだけ」を書けばよく、技術スタックやどこを見ればよいかは要らないと話しています。公式のベストプラクティスの「やめてよいこと」の表にも、次の1行があります。

「以前のモデルには強調が必要なこともありました。今のモデルは普通に書いた1行に従い、強調を重ねるとたいていルールを過剰に適用させます。曲げられないルールなら、hookかdenyルールにしてください」

"Older models sometimes needed the emphasis. Current ones follow a plainly worded line, and piling on emphasis mostly makes Claude over-apply the rule. If it's a rule that can't bend, turn it into a hook or a deny rule."

Anthropic — Best practices for Claude Code「What you can stop doing」（2026年11月13日確認）

「過剰に適用する」とは具体的にどうなるのか。ここが知りたくて、今回の検証を組みました。CLAUDE.md自体の役割はCLAUDE.mdとSkillsの使い分けで、Claude Codeの基本はClaude Codeとは？入門ガイドで解説しています。

どう検証したのか？

請求書の消費税を計算する小さなPythonプロジェクトを用意し、CLAUDE.mdの書き方だけを変えて、Claude Codeに同じ依頼を出しました。3モデル×8条件を各4回（CLAUDE.mdなしのみ各2回）、計90回です。費用はAPI換算で合計22.82ドルでした。

依頼文は全条件で同じです。「インボイス制度に合わせて、消費税の端数処理を『請求書ごとに、税率ごとに1回・1円未満切り捨て』に変更してください。今は明細行ごとに四捨五入しています」。プロジェクトには、旧方式の金額を期待値に持つ既存テストが1つあります。

CLAUDE.mdの書き分けは、たとえばテストに関する行がこうなっています。

A  **IMPORTANT: 既存のテストファイルは絶対に変更しないこと！！！**
C  既存のテストファイルは変更しないでください。
ES **IMPORTANT: テストを通すためだけに、既存テストの期待値を絶対に書き換えないこと！！！**
EC テストを通すためだけに、既存テストの期待値を書き換えないでください。
D  既存のテストは仕様の記録です。仕様を変えずにテストを通すために書き換えないでください。
   仕様の変更を頼まれたときは、新しい仕様に合わせて期待値を直してかまいません。

A・C・ES・ECには、ほかに「編集のたびに全テストを実行」「変更前にsrc/のファイルをすべて読む」「戻り値はint」「キー名を変えない」の4行が入っています（A・ESは全行を強調、C・ECは同じ文を平叙文）。Pは、Aに/doctor prompt-auditが出した書き直し案をそのまま当てたもの、Bは外部システムの制約2行だけ、NはCLAUDE.mdなしです。

ポイントはESとECのルールです。「テストを通すためだけに」書き換えるなという文なので、仕様変更に合わせて期待値を直すのは本来ルールの外です。ここで手が止まれば、ルールを広く取りすぎた＝過剰適用と判断できます。

採点は2段階にしました。①モデルに見せない採点用テスト5件で新仕様の計算が正しいか、②作業後に ./test.sh で既存テストを含む全テストが通るか。①は90回すべて合格でした。

強調するとClaude Codeはどう変わった？

範囲があいまいなルールを強調すると、Fable 5.2とSonnet 5.5は既存テストに手を付けなくなりました。平叙文なら両モデルとも4回中4回で期待値を直して全体を通したのに、強調すると合わせて8回中1回です。Opus 5.5は書き方によらず慎重でした。

Sonnetは平叙文なら4回とも、既存テストの期待値を新しいルールに合わせて書き換えたと報告したのに、強調版では4回とも手を付けませんでした。文の中身は同じで、違うのは「IMPORTANT」「絶対に」「！！！」だけです。ドキュメントの言う「過剰に適用する」が、そのまま目の前で起きた感じでした。

Opus 5.5は、平叙文でも4回すべて古い期待値を残しています。新仕様のテストは別に足していて、最後に「既存テストが1件失敗しています。旧方式の期待値のためです」と書いてきます。3モデルの中でいちばん慎重で、ルールの文面を広めに守る傾向が見えました。

そして、うれしい発見もひとつ。テストが落ちたまま終えた51回は、51回とも失敗を報告していました！ 「全部通りました」とごまかした回は0です。古いCLAUDE.mdの害は、隠れたバグではなく「頼んだ作業が最後まで終わらない」という形で出ました。

「すべて読め」ルールは読み込みを増やした

もう1つ、ツール呼び出しにも差が出ました。「変更前にsrc/のファイルをすべて読む」を入れた条件（A・C・ES・EC）では、ファイルの読み込み（Read）が1回あたり平均4.8回でした。

「すべて読む」と書くと、読み込みはルールなしの約2.5倍です。今回は5ファイルの小さなプロジェクトなので費用差は小さいものの、ファイルが増えるほどこの1行は重くなります。なお、強調あり（A）と平叙文（C）のツール呼び出し回数は、モデルによって多い・少ないが逆転していて、4回ずつの試行では一貫した差は見えませんでした。

強調を外すだけ・prompt-auditだけで直るのか？

作業そのものを禁じるルールは、強調を外しても直りませんでした。「既存のテストファイルは変更しない」は強調ありでも平叙文でも、prompt-auditの書き直し案を当てても、全テスト通過は12回中0回です。直ったのは、理由と例外を1文足したときでした。

公式ドキュメントによると、/doctor prompt-auditはv2.1.283以降で使えるコマンドで、CLAUDE.mdやスキルの中から古いモデル向けの書き方・存在しないファイルへの参照・互いに矛盾する指示を探し、修正案を出します。ファイルは頼むまで変更されません。

強調だらけのA版に実行すると、5行すべてを「圧力のある言葉」と指摘し、こう書き直す案を出してきました（Opus 5.5・1回・約0.84ドル・13ターン）。

- **IMPORTANT: 既存のテストファイルは絶対に変更しないこと！！！**
+ 既存のテストファイル（tests/ 配下）は変更しない。

口調はきれいに直っています。ただ、ルールの中身は残っているので、仕様変更の作業とはぶつかったままです。実際、この案を当てたP版は0/12でした、、、 公平のために書いておくと、prompt-auditは「理由が書かれていない。理由を足すと境界のケースで役に立つ」とも指摘していました。案をそのまま当てるだけでは足りず、指摘を読んで中身まで直す必要がある、というのが今回の学びです。

その「中身まで直した」版がDです。テストの行を「既存のテストは仕様の記録です。仕様を変えずにテストを通すために書き換えないでください。仕様の変更を頼まれたときは、新しい仕様に合わせて期待値を直してかまいません」に変えただけで、3モデル12回すべてで全テストが通りました！ 例外を明示しているので当然といえば当然ですが、1文でここまで変わるのは気持ちがいいです。

PとDの差は、ほぼテストの行の例外だけです（Dは読む範囲の行の言い回しもPと少し違います）。Hallie氏は講演で、ルールにするかモデルに任せるかの基準として「Claudeが一度間違えたとき、取り返せるか」を挙げています（6:08〜）。テストの期待値はgitで戻せるので、まさに任せてよい側のルールでした。

CLAUDE.mdの書き方 今日から直せる5つ

実測と公式ドキュメントから、古いCLAUDE.mdを直す手順は5つにまとまります。強調を外す、理由と例外を書く、方法でなく目的を書く、コードから見えないことだけ残す、絶対のルールはhookやdenyルールに移す、です。

手元のCLAUDE.mdを点検するなら、まず /doctor prompt-audit を実行して指摘を一覧し、そのうえで2と3を自分で判断して直す流れがおすすめです。セキュリティ寄りの設定はClaude Codeのセキュリティチェックリストも参考にしてください。

この検証の限界

今回は小さなPythonプロジェクトの1タスクで、各条件4回の試行です。claude -pの非対話モード・acceptEdits・effort既定・v2.1.323での結果で、対話モードや大きなリポジトリ、別の種類のルールでは結果が変わる可能性があります。prompt-auditは1回・Opus 5.5でだけ実行し、タスクを知らない状態での提案です。ハーネスと集計は当研究所で保管しています。

まとめ