CLAUDE.md 評価チェックリスト｜効いてるか 5 つの指標で診断
「CLAUDE.md を書いたのに、Claude の振る舞いが変わっているのかわからない」——CLAUDE.md を導入したあと、多くの人がこの疑問にぶつかる。設計原則や書き方の情報は豊富にある一方で、「自分の CLAUDE.md が本当に機能しているか」を確認するための具体的な指標は、あまり語られていない。
本記事では、CLAUDE.md の効果を判断するための 5 つの評価指標、効いていない状態が示す 4 つのサイン、そして CLAUDE.md の構造的な限界と向き合うための視点を整理する。
CLAUDE.md の評価基準はシンプルで、Claude の振る舞いが実際に変わったかどうか の一点だ。「丁寧に書いた」「行数が多い」は評価指標にならない。
効果を確認するための指標は 5 つある。①毎回の説明コストがゼロか・②同じミスの再現率が下がったか・③制約ルールが遵守されているか・④行削除テストで本当に必要な行か・⑤コンテキスト消費と品質のバランスが保たれているか だ。
CLAUDE.md には構造的な限界もある。手動更新の負担・動的情報への非対応・コンテキスト圧迫 の 3 点は仕組み上回避できない。絶対保証が必要な制約は Hook に移し、CLAUDE.md は「削れない一行だけが残るファイル」として月次で剪定するのが長期的に最も効く運用だ。
目次 (10)
1. 「書いた」と「効いている」は全く別の問題
CLAUDE.md は Claude Code がセッション開始時に自動で読み込む指示書だ。しかし、ファイルを置くだけでは十分ではない。Claude Code 公式のベストプラクティス は「CLAUDE.md をコードと同じように扱え——Claude の挙動が実際に変わったかどうかで変更をテストせよ」と明示している。
つまり評価の基準は、Claude の振る舞いが変わったかどうか の一点に尽きる。「丁寧に書いた」「行数が多い」「構造がきれい」は評価指標ではない。
また、CLAUDE.md が「効いているか」と「正しく書けているか」は別の問いでもある。書き方が正しくても届いていないこともあれば、書き方が粗くても行動変容が起きていることもある。評価は必ず、実際のセッションで Claude がどう動くか を観察することで行う。
2. 評価指標① 毎回の説明コストがゼロに近いか
最もシンプルな評価指標は、新しいセッションを開いたときに「説明ゼロで作業に入れるか」 だ。
CLAUDE.md を導入する前、Claude に毎回伝えていた情報のリストを書き出す。たとえば「このプロジェクトは TypeScript でスタイルは ESLint を使う」「DB 接続は .env.local を読む」「legacy/ 配下は触らない」といった内容だ。
CLAUDE.md が機能していれば、これらをセッション冒頭で説明しなくても Claude が正しく振る舞うはずだ。逆に、セッションを新しく開くたびに同じことを説明し直しているなら、その情報が CLAUDE.md に入っていないか、書き方が届いていないかのどちらかだ。
改善の手順:
- 前回のセッションで「プロンプトで補足した情報」を書き出す
- その情報が CLAUDE.md に含まれているか確認する
- 含まれていなければ追加し、含まれているなら書き方を見直す
3. 評価指標② 同じミスの再現率が下がったか
CLAUDE.md の中で最も ROI が高いのは、固有の落とし穴(Gotchas)セクションだ。Claude が過去に繰り返したミスをここに書けば、次のセッションで同じミスが減るはずだ。
評価のやり方:
- 「前回ここで詰まった」という状況を意図的に再現する指示を Claude に出す
- CLAUDE.md の Gotchas に書いた内容に反する動作が出るか観察する
- 回避できたならその行は効いている。同じミスが出るなら書き方か強調語を見直す
たとえば「この関数は同期版を呼ぶ、非同期版に変えると本番バッチが壊れる」と Gotchas に書いたなら、「非同期版に変えて」と明示的に指示してみる。Claude が制約を伝えた上で断るか、警告を出すかが確認ポイントだ。
4. 評価指標③ 制約ルールの実遵守率 — IMPORTANT テスト
「絶対にやらせたくないこと」をどれだけ守らせられているかも評価軸になる。Claude Code 公式は IMPORTANT: や YOU MUST: で始まる強調語を付けると遵守率が上がると述べている。
評価の手順:
- 禁止事項を CLAUDE.md に書き、それを意図的に破るよう誘導する指示を Claude に出す
- Claude が制約を伝えた上で「できません」「それは制約に反します」と返すかを確認する
- 守れなかった場合は強調語の付け方か、禁止事項の書き方を変える
ここで重要な留意点がある。CLAUDE.md は 助言(advisory) であり、100% の保証はない。「絶対に守らせなければならない」処理は、CLAUDE.md ではなく Hook に移すのが正解だ。Hook は決定論的(deterministic)に動き、アクションが起きることを保証する。評価した結果「CLAUDE.md では担えない」と判断したルールは、積極的に Hook へ移行する。
5. 評価指標④ 行削除テスト — 本当に必要な行か逆算する
CLAUDE.md を育てると、行数は自然に増えていく。しかし公式が強調するとおり、肥大化した CLAUDE.md は Claude が重要な指示を無視する原因になる（"Bloated CLAUDE.md files cause Claude to ignore your actual instructions"）。
行削除テストは、「この行を消したら Claude がミスをするか?」を実際に試す評価だ。
手順:
- 評価したい一行を CLAUDE.md から一時的に削除する
- その行に関連する作業をセッションで実施する
- Claude が正しく振る舞うかを観察する
削除しても Claude が変わらず正しく振る舞うなら、その行は現状では届いていない。Linter で管理できるスタイル規約や、Claude がもともと知っている言語標準は削除しても問題ないことが多い。逆に、削除した途端にミスが出るなら、その行は確実に効いている証拠だ。
6. 評価指標⑤ コンテキスト消費と品質のバランス
CLAUDE.md が長くなるほど、毎セッションのコンテキストウィンドウを圧迫する。コンテキストが埋まると Claude は前半の指示を忘れ始める。felo.ai の CLAUDE.md 活用ガイド も「ファイルが大きくなるほど、実際の作業に使えるコンテキストが減る」と指摘している。
評価の観点:
- 長い作業セッションの終盤で、CLAUDE.md の制約が守られているか
- コンテキストが半分以上埋まったときに Claude の精度が落ちていないか
終盤で守れなくなるルールがあるなら、そのルールは CLAUDE.md に書くより Hook か外部の仕組みで保証したほうがいい。また、ファイルが 300 行を超えていて終盤精度が落ちているなら、@import 構文でファイルを分割し、本体を薄く保つ設計への移行が有効だ。
7. 効いていない CLAUDE.md が示す 4 つのサイン
以下の状態が続くなら、CLAUDE.md の見直しが必要だ。
- 毎回同じことを説明している — CLAUDE.md に入っていないか、書き方が届いていない
- 過去に直った問題が再発する — Gotchas セクションの内容が薄いか強調が足りない
- 禁止したはずの行動が出る — 強調語の付け方か位置を変え、Hook への移行も検討する
- セッション終盤でルールが守られなくなる — CLAUDE.md が長すぎてコンテキストを圧迫している
これらはすべて「CLAUDE.md が機能していない」ではなく、「CLAUDE.md の書き方・構成・運用を変えれば改善できる問題」だ。サインを見つけたら、対応する評価指標に戻って原因を絞り込む。
8. CLAUDE.md の構造的限界を把握する
評価を正確に行うには、CLAUDE.md が構造上対応できないことも理解しておく必要がある。felo.ai の記事 は以下の 4 つの限界を挙げている。
- 手動更新の負担: プロジェクトの状態が変わるたびに自分で更新しなければならない
- 動的情報への非対応: 「今日どこまで進んだか」「次に何をすべきか」といった状態管理には向いていない
- 複数プロジェクト管理の複雑化: どのプロジェクトの CLAUDE.md が最新か把握しきれなくなる
- コンテキスト圧迫: ファイルが大きくなるほど実際の作業に使えるコンテキストが減る
CLAUDE.md は「セッション開始時に渡す永続コンテキスト」として強力だが、動的な状態追跡や決定論的な制約保証は Hook や外部ツールと組み合わせる必要がある。評価の結果「CLAUDE.md では担えない」と判断した領域を正しく分類し、適切な手段に移すことが成熟した運用につながる。
9. 月次評価フローで CLAUDE.md を育てる
Claude Code 公式は「月に一度は CLAUDE.md を剪定し、Claude の挙動が実際に変わったかで変更をテストせよ」と述べている。評価を一度で終わらせず、月次の定期プロセスに組み込むことが重要だ。
推奨する月次フロー:
- 全行に「消したら Claude がミスするか?」を問い、しない行を削除する
- 前月に Claude が繰り返したミスを Gotchas に一行追加する
- 制約ルールのうち 100% 保証が必要なものを Hook に移す
- 剪定後の CLAUDE.md で新セッションを開き、主要な制約が守られるかを一通り確認する
この流れを月一回実行するだけで、CLAUDE.md は肥大化せず信号密度を保ちながら成長する。「追加は慎重に、削除は大胆に」が基本姿勢だ。
10. 評価チェックリスト早見表
| 評価指標 | チェック内容 | 問題時の対応 |
|---|---|---|
| 説明コスト | 新セッションで説明ゼロで作業に入れるか | 毎回説明した内容を CLAUDE.md に追加する |
| ミス再現率 | Gotchas のミスが次のセッションでも再発するか | 書き方・強調語（IMPORTANT）を見直す |
| 制約遵守率 | 禁止事項を誘導テストして守られるか | IMPORTANT 付加、または Hook へ移行する |
| 行有効性 | 削除テストで「消しても大丈夫」な行を特定できるか | 無効な行を剪定し信号密度を上げる |
| コンテキスト量 | セッション終盤でルールが守られているか | @import で分割するか CLAUDE.md を短縮する |
| 動的情報 | 状態追跡を CLAUDE.md に持たせようとしていないか | Hook や外部ツールへ委譲する |
CLAUDE.md は書いて終わりではなく、評価して育てるファイルだ。上記の指標を月次ルーティンに組み込み、「削れない一行だけが残るファイル」を維持することが、長期的に最も効く CLAUDE.md への最短ルートになる。
