The longer your CLAUDE.md grows, the faster Claude Code burns through your usage

Share

Each CLAUDE.md file loads in full at the start of every session. The official docs advise keeping each one under 200 lines. Move workflows into Skills and file-specific rules into path-scoped rules. A slimming prompt is included.

Machine translation. Read the original

SourceAnthropicReported Nov 15, 2026Not yet tested

A long CLAUDE.md makes every Claude Code session use more of your usage. The official docs recommend keeping each CLAUDE.md under 200 lines. The whole file is read into the context at the start of a session. Every message you send after that carries it, even when the task has nothing to do with the file.

How a long file costs you

CLAUDE.md is the project guide for Claude Code. It covers things like how to build the project and which coding rules to follow. The official docs make three points about it:

  • It loads in every session. If you wrote long sections on PR review or database migration steps, those tokens are in the context even when you only fix a typo today.
  • The longer the file, the less reliably Claude follows it. The official docs say that a long file takes up more context, and Claude follows it less consistently.
  • Importing other files with @ does not save anything. Imports only help you organize your notes. The content still goes into the context in full.

One user report says that the instruction files in their project were too heavy, and their usage dropped noticeably at every startup. This is one person's experience. We have not verified how much it dropped. You can measure it with /usage. On a subscription, it shows the reasons that account for more than 10% of recent usage. The official docs include an example line: "Trim a CLAUDE.md, 49k tokens per request."

Where to move the content

Content Where to put it When it loads
Facts you always need: build commands, coding rules, folder structure CLAUDE.md Every session
Detailed steps for one workflow Skill Only when it is used
Rules that only apply to some kinds of files Path-scoped rules in .claude/rules/ When a matching file is touched

Ask your AI agent to slim it down

Send this to your AI agent:

Help me slim down this project's instruction files. Make a plan first. Do not change anything yet:
1. Count the lines in CLAUDE.md, CLAUDE.local.md, AGENTS.md, and each file under .claude/rules/.
2. Sort the content into three groups: facts needed in every session; detailed steps for one workflow; rules that only apply to one directory or type of file.
3. Suggest moving the second group into Skills, and the third group into path-scoped rules. For each, give a new file name and a draft of the content.
4. Find conflicting or outdated entries and list them separately.
5. Give me a table showing the line count before and after the move. Wait for my confirmation before doing anything.

The official docs also include a built-in check: /doctor prompt-audit scans these instruction files and finds conflicting and outdated content.

Notes

  • If you edit CLAUDE.md in the middle of a session, the change does not take effect right away. It takes effect after your next /clear or /compact, or after a restart.
  • Claude also reads CLAUDE.md files in subdirectories and files from team members. In a large repo, you can use claudeMdExcludes to skip the files that do not matter.
  • Auto memory loads only the first 200 lines or 25KB in each session. You do not need to manage it.

Official docs: How Claude remembers your project and Manage costs.

Done with this one? Mark it to track your path.Sign in
Save it for laterSign in
Questions about this piece?Ask AI about this

Comments (0)

No comments yet. Start the conversation.

Sign in to join the discussion.Sign in