CLAUDE.mdが長くなりすぎたとき：残す・分ける・消すの判断基準

3つの問いと行き先

行き先は4つです。

• 残す：CLAUDE.mdに置く。ビルドやテストのコマンド、守るべき規約、プロジェクト構成など、毎回必要なもの
• 分ける（rules）：.claude/rules/に置き、YAMLのpathsで対象ファイルを絞る。一致するファイルを扱うときだけ読み込まれます
• 分ける（スキル）：API仕様、リリース手順など、必要なときだけ使う資料や手順。説明文は毎セッション読み込まれ、本文は呼び出したときや依頼に関連するとClaudeが判断したときに読み込まれる
• 消す／hookにする：不要な行は削除する。例外なく守らせたいことはhookにする

迷う行は、まず「その一文がなくてもClaudeは正しく動くか」を試すのが手早いです。動くなら消す候補です。

判断表

• ビルド・テスト・lintのコマンド、判断：残す、理由と行き先：毎回使い、コードから推測しにくい
• 「pnpmを使う、npmは使わない」などの規約、判断：残す、理由と行き先：短く、全作業に関係する
• 特定言語や特定ディレクトリだけの規約、判断：分ける、理由と行き先：paths付きのrulesにする
• API仕様、DBスキーマの詳細、判断：分ける、理由と行き先：スキルにするか、参照先を1行だけ書く
• リリース、デプロイの手順、判断：分ける、理由と行き先：/名前で呼び出すスキルにする
• 「.envは編集しない」など破れない制約、判断：hookにする、理由と行き先：CLAUDE.mdの文章は強制ではなく依頼。PreToolUse hookで該当操作をブロックできる
• コードを読めば分かる説明（ディレクトリ一覧など）、判断：消す、理由と行き先：毎回の読み込み分だけ損になる
• 解決済みの不具合メモ、古い移行計画、判断：消す、理由と行き先：今の作業に関係しない
• 同じ趣旨を言い換えた重複行、判断：消す、理由と行き先：残すなら1つに統合する
• 「丁寧に」「きれいに」などの曖昧な指示、判断：書き直す、理由と行き先：確認できる形（「関数は50行以内」など）にする

整理前後の例

次は説明用の例です。実在のプロジェクトでも、実測した結果でもありません。

整理前（抜粋）：

# CLAUDE.md
- src/ にはUI、api/ にはサーバー処理、lib/ には共通関数がある
- コードはきれいに書くこと
- npmではなくpnpmを使う
- テストは `pnpm test`、型チェックは `pnpm typecheck`
- 2024年の認証移行は完了済み（経緯メモ20行）
- 決済APIのエラーコード一覧（40行）
- リリース手順（15行）
- .env は絶対に編集しない
- フロントエンドのコンポーネントは関数コンポーネントで書く

整理後：

# CLAUDE.md
- パッケージ管理はpnpm。npmは使わない
- テスト: `pnpm test` / 型チェック: `pnpm typecheck`
- 変更後は上の2つを実行し、結果を報告する

移した先は次のとおりです。

• フロントエンド規約は、.claude/rules/frontend.mdにpaths: ["src/**/*.tsx"]を付けて移す
• 決済APIのエラーコード一覧は、スキルpayment-errorsにする
• リリース手順は、/releaseスキルにする
• .envの編集禁止は、PreToolUse hookにする
• ディレクトリ説明、認証移行の経緯、曖昧な「きれいに」は削除する

整理をClaudeに頼むときの依頼文と、人が確認すること

仕分けの下書きはClaude Codeに作らせられます。ただし、書き換えを一度に任せません。まず提案だけを出させます。

CLAUDE.mdを整理したい。ファイルはまだ変更しないでください。
各行について、次のどれかに分類した表を作ってください。
- 残す（毎セッション必要で、コードから読み取れない）
- rulesへ分ける（対象パスの案も）
- スキルへ分ける（名前と説明文の案も）
- 消す（理由も）
- hookにすべき（破れない制約）
判断に迷う行は「要確認」とし、理由を書いてください。

この下書きに対して、人が確認する点は3つあります。

1. 「消す」の行：チームの暗黙知やコードに書かれていない理由が含まれていないか。Claudeはリポジトリの外の事情を知りません。
2. hookの提案：その制約を機械的に止めてよいか。設定は人が確認してから反映します。
3. 整理後の動作：新しいセッションで、同じ依頼を出して挙動が変わっていないか見ます。

Claude Codeの/contextで、読み込まれているCLAUDE.mdや自動メモリのファイルとコンテキスト使用量を確認できます。公式のメモリ説明では、古い・矛盾する指示などを監査する機能として/doctor prompt-auditを紹介しています。これは提案を報告する機能で、ファイルは適用を指示するまで変更されません。v2.1.283以降が必要です。

分けたあとに起きやすいこと

@importでは軽くならない可能性が高い。 メモリ説明のページは、@pathで読み込むファイルがそのCLAUDE.mdと一緒に読み込まれ、コンテキスト消費は減らないと説明しています。整理には役立ちますが、節約が目的なら、rulesやスキルに移すほうが効きます。

paths付きrulesは対象ファイルを扱うときに読み込まれます。 コンテキストウィンドウの解説によれば、対象ファイルを読み書きしたときに読み込まれ、会話の圧縮時には会話とともに要約されます。圧縮後も有効にしたい規約は、pathsを外して常時読み込むrulesにするか、プロジェクト直下のCLAUDE.mdへ移します。

スキルの説明文は短く具体的に。 Claudeは説明文と依頼内容を照らし合わせて、どのスキルを使うか決めます。説明があいまいだと、別のスキルが使われたり、使われなかったりします。副作用のあるスキルには、disable-model-invocation: trueを付けると、自分で呼んだときだけ動かせます。

Claudeが同じ間違いを繰り返したときは、先に判断表に当てはめます。 公式は同じ間違いが2回起きたらCLAUDE.mdに加える例を示しています。追加する前に行き先を決めれば、再び肥大化しにくくなります。