Claude Media
CLAUDE.md is too long警告の意味と直し方 — Claude Code
Claude CodeTips

CLAUDE.md is too long警告の意味と直し方 — Claude Code

Claude Codeの起動時に出る「CLAUDE.md is too long」警告は、200行の目安と合算の上限を見ています。警告の仕組みと、path-scoped rulesや/doctorで減らす手順をまとめます。

読了目安 約9分

Claude Codeを起動すると「CLAUDE.md is too long」という警告が出ることがあります。これは動作を止めるエラーではなく、指示ファイルが推奨の長さを超えているという通知です。放置してもセッションは始まりますが、長いファイルは常にコンテキストを使い、指示への従い方も落ちやすくなります。

公式の目安は「1ファイル200行未満」です。ただし警告が出る境目は、この200行と同じとは限りません。v2.1.169から、警告のしきい値はモデルのコンテキストウィンドウに応じて変わります。数値は公開されていないため、行数だけで警告の有無は予測できません。

警告が出る条件を3つに分けて読む

警告の背景には、公式ドキュメントとchangelogに書かれた3つの仕組みがあります。

仕組み

警告に関わる3つの上限

  • 1ファイルの推奨長さ

    目安は200行未満です。推奨の長さを超えると、起動時と/statusの実行時に警告が出ます(境目はモデルによって変わります)。

  • 複数ファイルの合算

    個別には収まっていても、合計が上限を超えると、セッション開始時に警告されます。v2.1.281で追加された挙動です。

  • 4 MiBの読み込み上限

    4 MiBを超えるCLAUDE.mdは、警告ではなく読み込まれません。

1ファイルの目安は200行

公式のSizeの項は「CLAUDE.mdは1ファイル200行未満を目安にする」と書いています。長いファイルはコンテキストを多く使い、指示への従い方が下がる、というのが理由です。

警告のしきい値は、v2.1.169のchangelogに「CLAUDE.md is too longの警告しきい値がモデルのコンテキストウィンドウに応じて変わるようになった」とあります。コンテキストの大きいモデルと小さいモデルで、同じファイルでも警告の出方が変わることがあります。モデルを切り替えたら警告が出た、という場面はこれで説明がつきます。

ファイルを数える単位は「読み込まれる1本ずつ」

合算の判定では、CLAUDE.md、rulesファイル、@pathでインポートしたファイルが、それぞれ別の1本として数えられます。v2.1.281では、この合算を警告に含める改善が入りました。中くらいのファイルを多数置いたり、@で分割したりして、見かけの行数を減らしても、警告を避けられない理由です。

分割そのものは悪くありません。公式も「インポートは整理に役立つが、コンテキストの負担は減らない。インポート先のファイルも起動時に読み込まれるため」と説明しています。

4 MiBは別の話

警告より重いのが読み込み上限です。4 MiBを超えるCLAUDE.mdは読み込まれません。通常の手書きで届く大きさではなく、ログや生成物を貼り付けたときに起こることがあります。

自分の環境で何が読み込まれているかを確かめる

行数を数える前に、実際に読み込まれているファイルを確認します。/contextのMemory filesの一覧が、起動時に読み込まれた指示ファイルです。

/context
/status

/statusには、推奨の長さを超えたファイルの警告が出ます。サブディレクトリのCLAUDE.mdは、そのディレクトリのファイルをClaudeが読み書きするまで読み込まれません。そのため、/contextの一覧には出てきません。

行数はシェルでも数えられます。リポジトリの指示ファイルをまとめて確認する例です。

wc -l CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md 2>/dev/null
find .claude/rules -name '*.md' -exec wc -l {} +

合計行数が多いのに個別のファイルは短い、という状態なら、合算の警告を疑います。

警告が出たときの減らし方

残すのは、毎セッション必要な事実だけです。公式は、CLAUDE.mdを「毎セッション保持すべき事実」の置き場にし、複数ステップの手順やコードベースの一部にしか関係しない内容は、skillかpath-scoped ruleに移すよう勧めています。

手順

警告を解消する手順

  1. 1

    導出できる内容を削る

    ディレクトリ構成、依存関係の一覧、アーキテクチャの概説は、Claudeがコードから読み取れます。まずここを落とします。

  2. 2

    一部のファイルにしか効かない指示をruleへ移す

    .claude/rules/に置き、pathsで対象を絞ります。該当ファイルを扱うときだけ読み込まれます。

  3. 3

    手順書はskillへ移す

    リリース手順のように、必要なときだけ使う長い手順は、skillにすると呼ばれたときだけ読み込まれます。

  4. 4

    残った分を再点検する

    /contextと/statusで、警告が消えたかを確かめます。

path-scoped rulesで特定のファイルだけに効かせる

.claude/rules/のファイルにpathsのfrontmatterを付けると、マッチするファイルをClaudeが開いたときだけ読み込まれます。pathsのないrulesは、.claude/CLAUDE.mdと同じ優先度で起動時に読み込まれる点に注意してください。ルールを分けただけでは、起動時の負担は減りません。

次は、公式のrules記法に沿った例です。API関連の規約を、src/api/配下を扱うときだけ読ませます。

---
paths:
  - "src/api/**/*.ts"
---
 
# API Development Rules
 
- All API endpoints must include input validation
- Use the standard error response format

CLAUDE.mdの側に書いていた「API層の規約」の節を、このファイルへ移します。CLAUDE.mdには、全ファイルに共通の規約だけを残します。

人間向けのメモはHTMLコメントにする

ブロックレベルのHTMLコメント(<!-- maintainer notes -->)は、コンテキストに入る前に取り除かれます。保守者向けのメモをCLAUDE.mdに残したいときは、コメントにすればトークンを使いません。コードブロック内のコメントは残ります。ファイルをReadツールで直接開いたときは、コメントも見えます。

/doctorに削る候補を出させる

v2.1.206から、/doctorはリポジトリにコミットされたCLAUDE.mdについて、削れる内容の提案を出します。ディレクトリ構成や依存関係、アーキテクチャの概説のように、コードベースから導出できる内容を削り、落とし穴や理由、ツールの既定と違う規約は残す、という方針です。

/doctor
/doctor prompt-audit

/doctor prompt-auditは、古いモデル向けに書かれた指示や、存在しないファイルへの参照、互いに矛盾する指示を探します。指示ファイル、rules、skills、サブエージェントなどが対象で、v2.1.283以降が必要です。提案が出るだけで、ファイルは変更されません。/claude-api同梱スキルを経由するため、そのスキルを無効にしている環境では動きません。

/doctorの役割の違いは/doctorと/checkupの違いにまとめています。

警告を消すことが目的ではない

警告を消すために、行を詰めたり1行に複数の指示を押し込んだりするのは本末転倒です。公式は、CLAUDE.mdを「強制される設定ではなく、コンテキストとして扱われる」と説明しています。短くする狙いは、指示への従い方を保つことです。

記述の質の話はCLAUDE.mdの書き方が詳しく、知識をskillsへ移してコストを下げる考え方はCLAUDE.mdをSkillsに移行する方法にあります。必ず守らせたい動作は、CLAUDE.mdではなくhooksに書くのが公式の勧めです。

削ったあとに指示が効かなくなったとき

指示を移した直後は、「消えた」と感じることがあります。切り分けの順番は次のとおりです。

切り分け

指示が効かないときの切り分け

  1. Q`/context`のMemory filesに、そのCLAUDE.mdが載っているか?
    答えがいいえのとき

    読み込まれていません。置き場所が読み込み対象のパスにあるかを確かめます。

    答えがはい
  2. Q移した先はpath-scoped ruleで、対象のファイルを開いたあとか?
    答えがいいえのとき

    path-scoped ruleは、マッチするファイルを読み書きするまで読み込まれません。対象のファイルを開いてから試します。

    答えがはい
  3. QサブディレクトリのCLAUDE.mdに移したか?
    答えがいいえのとき

    サブディレクトリのCLAUDE.mdも、そのディレクトリのファイルに触れて初めて読み込まれます。

    答えがはい

指示同士の矛盾を探す

2つのファイルが同じ振る舞いについて食い違うと、Claudeはどちらかを任意に選びます。/doctor prompt-auditで矛盾を洗います。

読み込み状況はInstructionsLoadedフックで記録することもできます。どのファイルが、いつ、なぜ読み込まれたかを残せます。パスやsymlinkが原因のときは、rulesのsymlinkが読み込まれない原因も確認してください。

/compactのあと、ルートのCLAUDE.mdはディスクから再度読み込まれます。サブディレクトリのCLAUDE.mdとpaths付きのrulesは、必要になったときに読み込み直されます。会話の中だけで伝えた指示は、compactで失われます。残したい内容はCLAUDE.mdへ書く、というのが公式の説明です。

MEMORY.mdの上限とは別のものとして扱う

200行という数字は、auto memoryの索引MEMORY.mdにも出てきます。こちらは最初の200行または25KBのうち先に届いたほうまでしか読み込まれず、超過分は読み込まれません。CLAUDE.mdの200行は推奨の目安で、読み込みを打ち切る境界ではありません。

対象200行の意味超えたとき
CLAUDE.md200行の意味推奨の長さ(目安)超えたとき警告が出ることがある(境目はモデル次第)。4 MiBまでは全文が読み込まれる
MEMORY.md200行の意味読み込みの上限(25KBとも併用)超えたとき超過分は読み込まれない

MEMORY.md側の対処はMemory index read limitの対処で扱っています。

まとめ

「CLAUDE.md is too long」は、200行の目安、合算の上限、モデルのコンテキストウィンドウに応じたしきい値が絡む通知です。具体の数値は公開されていないので、行数ではなく、どの指示が毎セッションに必要かで判断します。導出できる内容を削り、一部にしか効かない指示はpath-scoped rulesへ移し、/doctorで提案を受けるのが、公式の示す順路です。三層の使い分けの全体像はClaude Code memoryの三層構造にあります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →