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
/clearor/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
claudeMdExcludesto 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.


Comments (0)
No comments yet. Start the conversation.