CLAUDE.md のベストプラクティス: 何を書き、何を書かず、サイズをどう測るか

Anthropic のドキュメントが CLAUDE.md について示す数字は 1 つだけです。"target under 200 lines per CLAUDE.md file." あわせて、各行を判定するよいテストと、含めるもの・外すものの表も載っています。どれも正しいのですが、ファイルのコストについては何も教えてくれません。行はコストの単位ではないからです。モデルが払うのはトークンです。

この種のファイルを 2 つの階層で管理しています。自分のすべてのエージェントが読み込むグローバルな ~/.claude/CLAUDE.md と、リポジトリごとのプロジェクト用 ./CLAUDE.md または ./.claude/CLAUDE.md です。どちらかが他方を上書きするのではなく、Claude Code は両方を連結します。ユーザー用ファイルが先、プロジェクト用ファイルが後です。何か月もかけて削り、増やし、測ってきたので、その経緯は git に残っています。そこから見えてきたことで、ドキュメントに書かれていないものがあります。CLAUDE.md の各行は「これがなければエージェントは間違える」という主張であり、その主張はほとんどコストなしで書けて、めったに検証されません。

本記事で引用するドキュメントの記述は、すべて Claude Code 2.1.310 で確認しました。

CLAUDE.md には何を書くべきか

欠けていてもエージェントが気づけない行です。Claude が推測できないビルドコマンド、エラーを出さずに失敗する落とし穴、デフォルトと異なる規約。こうした行がなければ、セッション中に、エージェントが探しに行くきっかけが何もありません。

Anthropic のベストプラクティスのページは、このテストを各行への問いとして示しています。

"Would removing this cause Claude to make mistakes?" If not, cut it.

含めるもの側の列は、その実践版です。Claude が推測できない Bash コマンド、デフォルトと異なるコードスタイルのルール、テストの手順、リポジトリの作法、プロジェクト固有のアーキテクチャ上の決定、必須の環境変数のような環境の癖、そして "common gotchas or behaviors that aren't self-evident." メモリのドキュメントは、行を追加すべきタイミングも示しています。Claude が同じ間違いを 2 回したとき、あるいは前回のセッションと同じ修正をまた打ち込んでいるときです。

7 月にグローバルガイドを推定 12,866 トークンから 5,694、さらに 3,737 まで削ったとき、コミットメッセージに書いた「残す基準」は、同じテストをもっと鋭くしたものでした。常に読み込む行として残したのは "a rule whose failure gives the agent no signal to go look anything up" に当たるものです。それ以外は読みに行く先へ移しました。タスクツールの使い方はその --help へ、監視の例は専用のドキュメントへ、サービスの表は runbook へ。エージェントはそれでも見つけられます。タスクに取りかかった時点で、使い方が必要だとわかるからです。存在を知らないルールを探しに行く人はいません。毎回読み込む必要があるのは、その種類の行だけです。

CLAUDE.md から外すべきもの

Claude がコードから導けるもの、Claude Code がすでに注入しているもの、ときどきしか必要にならない手順、そしてルールがどう生まれたかという経緯です。

導けるものは、ドキュメントの外すもの側の列にあります。コードを読めばわかること、言語の標準的な規約、ファイルごとの説明、"information that changes frequently." 今では /doctor のチェックが、コミット済みの CLAUDE.md に対してまさにこうした削除を提案します。ディレクトリ構成、依存関係の一覧、アーキテクチャの概要は削除を勧め、"pitfalls, rationale, and conventions that differ from tool defaults" は残します。

注入されている分は、自分で書いたものではないので見落としがちです。Claude Code はすでにコンテキストウィンドウにいくつかのものを入れています。説明付きのスキル一覧、MCP ツールの名前、自動メモリとその使い方の指示です。プラグインはフックを通じてさらに追加できます。7 月には、ハーネスが毎回のセッションで注入しているスキル一覧を、グローバルガイドが丸ごと繰り返していたことに気づきました。プラグインのフックが、把握していなかった 1,000 トークンほどを足していたこともわかりました。ハーネスと重複させれば、同じコンテキストに 2 回払うことになります。行を足す前に、セッションにすでに何があるかを見てください。

手順はスキルへ移します。スキルの説明は毎回のセッションでコンテキストに入りますが、本文が読み込まれるのは "when you invoke them or when Claude determines they're relevant" のときだけです。コードベースの一部だけに関わる指示はパス指定のルールへ移します。適用範囲を決めるのはフォルダではなく frontmatter です。.claude/rules/ にあっても paths フィールドのないファイルは、CLAUDE.md と同じく起動時に読み込まれます。フィールドがあれば、Claude が一致するファイルを読むか編集したときにだけ読み込まれます。

---
paths:
  - "src/api/**/*.ts"
---
 
- API handlers validate input with the shared schema module.

経緯は changelog かコミットメッセージへ。理由と経緯は別物なので、これについては後で詳しく書きます。

CLAUDE.md はどのくらいの大きさにすべきか

Claude Code 自身が数えたトークン数が、意図して決めた予算内に収まる程度に小さく。200 行という目安は出発点としては妥当ですが、行数ではコストの高いファイルが通ってしまいます。

ドキュメントの理屈は正しく、長いファイルは "consume more context and reduce adherence" (コンテキストを多く消費し、指示が守られにくくなる) とされています。 弱いのは指標のほうです。7 月、あるプロジェクトの CLAUDE.md は 83 行で、監査スクリプトの行数チェックを通過しました。同じスクリプトの見積もりでは約 12,000 トークンでした。中身の大半が 25,782 文字の 1 行に収まっていたからです。しかも次の節で示すとおり、この見積もり自体が低めに出ます。行数の上限ではこうしたことが一切見えないので、スクリプトをファイルごとのトークン予算に切り替えました。大半のプロジェクトファイルは 2,500、グローバルガイドには別のもっと大きな予算、そして貼り付けられた巨大なブロックを捕まえるための 1 行の長さの上限です。

import とコメントは逆方向に働きます。import でファイルが安くなることはありません。ドキュメントは、@path の import は "help you organize a long file but don't reduce its context cost" とはっきり書いています。import されたファイルは、import する側と一緒に読み込まれるからです。ブロック単位の HTML コメントなら、ファイルは安くなります。内容がコンテキストに入る前に取り除かれるので、人間のメンテナー向けのメモにはコストがかかりません。コードブロック内のコメントは残ります。

CLAUDE.md のサイズをトークン数で測るには

Claude Code に聞きます。/context コマンドは、起動時に読み込まれたメモリファイルをトークン数付きで一覧表示し、ヘッドレス実行でも動きます。

対話的に使うなら、プロジェクトのディレクトリで /context を実行し、Memory files の下を見ます。シェルからは、同じディレクトリで次のように実行します。

claude -p "/context" | awk '/^### Memory Files/{f=1} /^### Skills/{f=0} f'

手元の環境では、ファイルごとに 1 行の表が出力されます。ユーザー用 CLAUDE.md、ユーザー用ルール、プロジェクト用 CLAUDE.md、それぞれのトークン数です。出力でこの後に別のセクションが続く場合は、フィルターなしで claude -p "/context" を実行してください。

わざわざこうする理由は、この数字と自作の見積もりとの差にあります。自分のスクリプトは文字数からトークンを見積もります。ラテン文字 4 文字で 1 トークン、キリル文字は 1 トークンあたりの文字数をそれより少なく数えます。グローバルガイド (424 行、19,114 文字) に対しては約 4,800 トークンと出ますが、/context では 7.1k です。スクリプトが 2,484、つまり予算 2,500 ぎりぎりと見積もったプロジェクトの CLAUDE.md は、/context では 4.1k でした。ファイルは 2 つだけで、値も丸められています。/context 自体もローカルの見積もりに切り替わることがあるので、絶対的な正解ではなく、ツールの物差しとして扱ってください。それでも、どちらのファイルでも /context の値は自分の見積もりの 1.5〜1.7 倍でした。バッククォート、パス、フラグだらけの Markdown は散文ではありません。文字数とトークン数の固定比率は、そのことを知りません。

ですから予算を決めるなら、単位と物差しをセットで選び、ツールが使う物差しを使ってください。wc -m を 4 で割って確認する予算は、モデルが実際に読むものとは別のファイルを測っているのと同じです。

サイズの制限のうち 1 つは、推奨ではなく強制です。サブディレクトリにあるもの、または paths: に一致したときに読み込まれるもの、つまり必要なときに読み込まれる CLAUDE.md やルールファイルは、ファイルごとの上限で切り詰められます。200K のコンテキストウィンドウでは 40,000 文字、1M では Opus 4.6 と Sonnet 4.6 で 200,000 文字、それ以降のモデルで 150,000 文字です。Claude が受け取るのはファイルの先頭部分と、残りを読むようにという注記で、読みに行くまでは後半の指示は存在しません。wc -m で確認してください (2.1.309 以降に適用)。

CLAUDE.md は /init から始めるべきか

最初の下書きとしてなら、はい。ドキュメントも勧めていますし、空のファイルよりはましです。ただし、生成されたものは CLAUDE.md のうち真っ先に削る必要のある部分として読んでください。

/init はコードベースを解析し、ビルドコマンド、テスト手順、見つけた規約を書き出します。CLAUDE.md がすでにあれば、上書きせずに改善案を出します。CLAUDE_CODE_NEW_INIT=1 を設定すると対話的なフローになり、スキルとフックも提案し、何かを書き込む前に案を見せます。.cursorrules や Copilot の指示など、見つけた他のツールのルールも取り込みます。

コードを読んで生成したファイルは、大半がコードから導けるものでできています。それはまさに /doctor が最初に削除を提案するものです。Claude が推測できなかったはずのコマンドは残し、ディレクトリの案内は消して、あとはドキュメントの説明どおりに育ててください。Claude が同じ間違いを 2 回するたびに 1 行です。そしてコミットしておけば、各行の経緯はファイルの外に残ります。

CLAUDE.md のルールには存在理由を書くべきか

はい。現在形で、ルールのすぐ隣に書きます。そのルールを生んだ出来事は、その行を追加したコミットに書きます。そして理由も仮説として扱ってください。理由が間違っていることもあるからです。

これはモデルがファイルをどう読むかに関わります。理由のないルールは、コンテキスト内の他のすべてと比べて重み付けされますが、その基準がありません。理由付きのルールなら、書いた人が想定していなかった状況にも当てはめられます。経緯を指示ファイルの不要物として指摘する /doctor のプロンプト監査との兼ね合いについては、別の記事で書きました。理由はファイルに残し、武勇伝は git へ。そこなら git blame で見つかり、どのセッションもうっかり読むことはありません。

理由にも検証が必要なことは、自分のガイドが示しています。7 月の削減で、数えられるルールが 1 つ消えました。返答に箇条書きが 5 つ、絵文字が 2 つ、表が 1 つ、見出しが 3 つを超えたら散文に書き直す、というものです。5 日後に戻し、日付付きのメモを添えました。消したのは出力量が急に増えたのと同じ朝であり (原文 "the same morning output volume jumped")、Opus 5 のデフォルトの返答が長いので、ルールの定性的な版だけでは足りない、という内容です。妥当な推論ではありましたが、測定ではありません。同じ週に Opus 5 がデフォルトのモデルになっていて、ルールを戻した当日、セッションを Opus 4.8 に固定し直してもいました。

1 週間後、あらかじめ判定基準を決めておいた測定を行いました。フォーマットのルールが効いているなら、箇条書きと見出しの数が減る。モデルが原因なら、構造はそのままで長さが減る。対象は、エージェントたちが書く朝のブリーフィングです。ブリーフィングの平均の長さは、削減前の 1,932 文字から削減後は 2,935 文字に増え、モデル固定後の 7 本では 1,775 文字に戻りました。1 本あたりの箇条書きは 12.4、14.8、19.0 と推移しました。ルールが狙った数は一度も減らず、長さはセッションが Opus 4.8 に戻った時点で縮みました。2 つの変更が同時に入ったので、ルールの効果だけを切り分けることはできません。ブリーフィングの長さは、夜のあいだに起きた出来事の量にも左右されます。最も裏付けのある原因はモデルですが、証明されたわけではありません。

そのルールは今もガイドにあり、添えたメモは今も、モデルの出力の長さを抑えているのはこのルールだと主張しています。測定はそれを裏付けませんでした。自分のファイルで警戒すべきなのは、まさにこの失敗です。修正した瞬間に書いた理由は、その後ずっと確定事項のように読めてしまいます。大事な行なら、効いていることが何でわかるかを書き留め、一度は確かめてください。

CLAUDE.md で IMPORTANT は効くか

1 行だけに使うなら、強調は役に立つことがあります。多くの行に散らすと、何の意味もなくなります。そして、どれだけ強調しても CLAUDE.md の行が保証になることはありません。

ベストプラクティスのページは率直にこう書いています。

If Claude keeps skipping one instruction, add emphasis such as
"IMPORTANT" to that line alone. If you emphasize many lines, none of
them stands out.

これは、プロンプト監査が圧力をかける言葉づかいに反対する理由とも一致します。大文字だらけのファイルは警報だらけのファイルとして読まれ、最近のモデルはそれを過剰に適用します。強調した 1 行の横に理由を添える形が、どちらの問題にも耐えられる書き方です。

強調には上限もあります。ドキュメントによれば、CLAUDE.md の内容はユーザーメッセージとして、Claude Code 自身の指示の中ではなくその後に届き、Claude は "tries to follow it, but there's no guarantee of strict compliance" (従おうとはするが、厳密に守られる保証はない) とされています。 毎回必ず起きなければならないことについて、ドキュメント自身が勧めるのはフックです。フックは、モデルがどう判断しようと、決まったタイミングでシェルコマンドとして実行されます。守られなければならないルールは 散文ではなくゲートに置くべきで、ゲートに移したら CLAUDE.md の行は参照先を示すだけに縮めるか、消してかまいません。

CLAUDE.md が再び膨らむのを防ぐには

触るたびに、ツールの物差しでサイズを記録してください。それでも膨らむものと考えておくことです。増え方は 1 行ずつで、どの行も妥当に見えます。予算のチェックだけでは、すでに大きくなるまで知らせてくれません。

自分のグローバルガイドがその例です。7 月の削減後、スクリプトでは 3,737 トークンで、同じ日に決めた 5,000 の予算を下回っていました。3 か月後、同じスクリプトは 4,789 と出ます。28 パーセント増で、追加したときにはどれも正当な理由がありました。自動チェックは今も通ります。ファイルが予算内にあり、スクリプトは警告を出す前に 5 パーセントの上乗せを許すからです。増加が見えるのは、記録した 2 つの数字を並べたときだけです。しかも /context では、このファイルはすでに 7.1k あり、スクリプト上は守っていることになっている予算を大きく超えています。

ずれを見える状態に保つチェックは、それぞれ別のものを捕まえます。毎回のセッションで読み込まれるファイルを編集した後の /context は、前回と比べるための数字をくれます。コミット済みの CLAUDE.md に対する /doctor は、いつのまにかコードから導けるようになった行を見つけます。モデルを変えた後の /doctor prompt-audit は、乗り換える前のモデル向けに書かれたルール、ファイル間の矛盾、もう存在しないパスを見つけます。Claude Code は、1 つの指示ファイルが推奨の長さを超えたとき、あるいは小さなファイルの合計が全体の上限を超えたときにも、起動時と /status で警告を出します。リポジトリに AGENTS.md もあるなら、実際にどのファイルが読み込まれているかを確認してください。デフォルトでは、Claude Code は AGENTS.md をフォールバックとしてしか読みません。作業ディレクトリかその上位に CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md のいずれもない場合だけです。この判定に ~/.claude/CLAUDE.md は数えられません。どれが読み込まれたかは /context でわかります。

どのチェックも、ある行がまだその場所に値するかどうかは教えてくれません。わかるのは、ファイルが変わったということだけです。中に書いた理由が今も正しいかどうかだけは、自分の手で確かめるしかありません。