Your CLAUDE.md Is Probably Too Long (And It's Slowing You Down)

CLAUDE.md is the instruction file Claude Code reads at the start of every session. It lives at ~/.claude/CLAUDE.md (global) or ./CLAUDE.md (per project). Oversized CLAUDE.md files waste tokens and slow responses. The fix is to keep only behavioral rules in CLAUDE.md and move reference documentation to ~/.claude/references/ files that Claude reads on demand. A real setup reduced 1,578 lines to 107 lines, cutting token usage by roughly 85%.

Every Claude Code session starts the same way: Claude reads a file. Before you type a single word, it already has instructions. Those instructions come from CLAUDE.md, and if you’ve been using Claude Code for any length of time, that file is probably way bigger than it should be.

This post covers what CLAUDE.md is, how tokens and context windows work, why the file tends to grow out of control, and what to do about it.

What is CLAUDE.md?

CLAUDE.md is a plain text file Claude Code reads automatically at the start of every session. It lives in two places:

~/.claude/CLAUDE.md (your global file, loaded in every project)
./CLAUDE.md (a project-level file at the root of a specific codebase)

The ~ symbol is shorthand for your home directory. So ~/.claude/ is a hidden folder called .claude sitting in /Users/yourname/ on a Mac.

Whatever you put in CLAUDE.md, Claude treats as standing instructions. If you write “always ask before deleting files,” it will always ask. If you write “I’m working on a podcast called Is This Working, the co-host is Connor,” Claude knows that from word one. No re-briefing. No explaining your setup every session.

It’s part of Claude Code’s memory system. The official docs describe it as a way to “add context, instructions, and information that you want Claude to always have available.” That’s accurate, but undersells how much leverage there is in a well-maintained CLAUDE.md.

What are tokens, and why do they matter here?

A token is roughly 3-4 characters of text, or about three-quarters of a word. AI models don’t read words the way you do. They process everything as sequences of tokens.

When you start a Claude Code session, every character in your CLAUDE.md gets converted to tokens and loaded into Claude’s working memory. That working memory has a limit, called the context window. Claude can only see a fixed number of tokens at once. On current models that’s quite large (tens of thousands of tokens), but it’s not infinite.

Here’s what matters practically: every token your CLAUDE.md consumes is a token unavailable for the actual work. If your CLAUDE.md is 800 lines of text, you’re spending somewhere between 15,000 and 20,000 tokens before you’ve typed a single prompt. That’s tokens that can’t be used for code, context, or conversation.

Loading less context means Claude can hold more of your actual project in its working memory. It also means faster responses, since there’s less to process at the start.

The ~/.claude/ directory

While we’re orienting: ~/.claude/ is the root of Claude Code’s configuration on your machine. It contains:

CLAUDE.md (your global instructions)
settings.json (preferences like model selection)
commands/ (your custom slash commands, like /chief-of-staff)
projects/ (project-specific memory and context)

When people talk about “configuring Claude Code,” they usually mean files in this directory. It’s worth knowing what’s in there. Run ls -la ~/.claude/ in your terminal and see what you have.

How CLAUDE.md grows out of control

No one sits down and writes an 800-line CLAUDE.md on day one. It grows by accumulation.

Week 1: you add a note about how you want code formatted. Week 3: you paste in your Netlify deploy instructions so Claude knows the process. Month 2: you add your client list with project statuses. Month 3: you add the full structure of your API configuration files. Month 4: you add a reference section explaining how your email system works.

Each addition felt justified. Each one also made the file a little slower and a little noisier.

The real problem isn’t that CLAUDE.md is long. It’s that most of what ends up in a long CLAUDE.md doesn’t need to be there on every turn. Your Netlify docs don’t need to be pre-loaded for a session where you’re writing email copy. Your API configuration details don’t need to burn tokens during a brainstorm.

What belongs in CLAUDE.md vs. what doesn’t

A good CLAUDE.md has behavioral rules, not reference material.

Belongs in CLAUDE.md:

How you want Claude to work (tone, decision-making style, communication preferences)
Workflow rules that apply to everything (“always commit before closing a session”)
Safety constraints (“never send emails without confirmation”)
Standing context that shapes every interaction (“I run a course called Code for Creatives with 20 students”)

Doesn’t belong in CLAUDE.md:

Full documentation for a specific tool or service
Step-by-step deploy instructions
API endpoint lists
Client history and project status
Anything you only need in specific situations

The test: if you’re in a random session doing unrelated work, does Claude actually need this? If the answer is “only sometimes,” it doesn’t belong in the main file.

The reference file pattern

The fix for the second category is to move it out of CLAUDE.md and into separate files that Claude reads only when relevant.

Create a folder at ~/.claude/references/. Put your Netlify docs in netlify-pattern.md. Put your API configs in api-configs.md. Put your client-specific patterns in separate files per client.

Then in your CLAUDE.md, add a short section like this:

## Reference Files (Read When Relevant)
- Netlify deploys: ~/.claude/references/netlify-pattern.md
- API configs: ~/.claude/references/api-configs.md
- Connor/podcast: ~/.claude/references/connor-itw.md

Now Claude knows those files exist and can read them when the work calls for it. They don’t burn tokens on every session. When you’re working on a deployment, Claude reads the Netlify file. When you’re doing podcast work, it reads the Connor file.

This is the single highest-leverage change you can make to an oversized CLAUDE.md.

The rules/ pattern

For behavioral rules, the same logic applies. If you have rules about writing voice, rules about email safety, rules about how you work with clients, those can live in modular files under ~/.claude/rules/ and get referenced from the main file.

## Rules (loaded from .claude/rules/)
- voice.md - writing tone, banned phrases
- email-safety.md - confirmation gate before sending
- git-deploy.md - commit habits, deployment restrictions

The main CLAUDE.md becomes a table of contents instead of an encyclopedia. It tells Claude where the rules are, and Claude reads them. You can update a rule by editing one small file instead of hunting through 800 lines.

This also makes rules easier to maintain. A voice.md file is just voice rules. You can read it, update it, share it with someone else’s setup. Clean separation.

For the data on how monolith vs. modular CLAUDE.md files actually perform, see Your CLAUDE.md File Is Too Long (And It’s Making Claude Worse).

The real example: 1,578 lines to 107

Here’s what this looked like in practice.

Two CLAUDE.md files, one global and one project-level, had grown to 789 lines each. Both were loading on every session. Before any actual prompt, roughly 17,000 to 20,000 tokens were being consumed just to load configuration.

The audit found the problem in layers:

First, the files were nearly identical. The project-level CLAUDE.md was a copy of the global one with a few additions. Every session was loading the same content twice.

Second, the files contained full documentation. Netlify deploy instructions, complete API configuration references, step-by-step workflow guides. Useful information, but not “load it every single time” useful.

Third, there was stale content. Notes about clients who’d moved on. A workflow section for a tool no longer in use. Hardcoded API keys that shouldn’t be in the file at all.

The fix took a few hours:

Created ~/.claude/references/ and moved six categories of reference material there
Rewrote the main CLAUDE.md to keep only behavioral rules
Deleted the duplicate project-level file
Pruned stale content
Removed hardcoded keys

Result: from 1,578 total lines to 107 lines. From roughly 20,000 tokens to roughly 1,200 tokens per session. About 85% reduction.

The behavioral rules that actually shape how Claude works are all still there. The reference material Claude needs for specific tasks is still there. It just gets loaded when it’s relevant rather than on every turn.

How to audit your own CLAUDE.md

Open your file (nano ~/.claude/CLAUDE.md or in any text editor) and go section by section:

Is this a rule or is it documentation? Rules stay. Documentation moves to ~/.claude/references/.

Do I need this on every single session? If not, it’s a reference file candidate.

Is this still true? Old client notes, outdated project statuses, dead workflows. Cut them.

Is this sensitive data? Hardcoded API keys, passwords, or credentials should never be in CLAUDE.md. Use environment variables or separate config files.

Is this here twice? If you have both a global CLAUDE.md and a project-level one, make sure they’re not duplicating each other. The global file should have universal rules; the project file should have project-specific overrides only.

After the audit, count your lines. If you’re still over 200, look for more documentation that can move out.

The relationship between CLAUDE.md and slash commands

CLAUDE.md and slash commands work as a pair. CLAUDE.md carries the standing rules. Slash commands carry the session-specific setup. For a step-by-step guide to building your own, see How to Make a Claude Code Skill.

The chief-of-staff setup (covered in How to Give Claude Code Memory Across Sessions) is a good example: a slash command that reads your current project notes and orients Claude before you start. That session context doesn’t need to live in CLAUDE.md. It gets loaded when you run the command, and only then.

The combination works like this:

CLAUDE.md: “Here are the rules for how I work”
Slash command: “Here’s what we’re working on today”
Reference files: “Here’s the documentation for this specific task”

Each file does one job. Nothing loads unless it’s needed.

A note on the effort level setting

One thing CLAUDE.md can’t fix: the effort level reset bug, where Claude Code reverts to medium effort every session regardless of what you’ve set. That’s a separate issue with a separate fix. The alias approach (alias c='claude --effort max') is covered in Claude Code Max Effort Level Keeps Resetting.

CLAUDE.md handles instructions. CLI flags handle session settings. Both matter, they just work differently.

Common Questions

What is CLAUDE.md in Claude Code?

CLAUDE.md is a plain text file Claude Code reads automatically at session start. It holds standing instructions like behavioral rules, workflow preferences, and safety constraints. It lives at ~/.claude/CLAUDE.md for global settings or ./CLAUDE.md for project-specific ones.

How long should my CLAUDE.md file be?

Under 200 lines. Every line loads as tokens on every session start, consuming context window space. Move reference material and documentation to separate files in ~/.claude/references/ that Claude reads only when relevant. Keep CLAUDE.md for behavioral rules that apply universally.

What are tokens in Claude Code?

A token is roughly 3-4 characters of text. Claude’s context window has a fixed token limit. Every character in CLAUDE.md converts to tokens loaded before you type anything. A large CLAUDE.md can consume 15,000-20,000 tokens before your first prompt, leaving less room for actual work.

How do I reduce my CLAUDE.md file size?

Create ~/.claude/references/ and move tool documentation, API configs, and client details into separate files. Add a short reference section in CLAUDE.md listing file paths. Claude reads them when relevant instead of loading everything every session.

A note from Alex: hi i’m alex - i run code for creatives. i’m a writer so i feel that it is important to say - i had claude write this piece based on my ideas and ramblings, voice notes, and teachings. the concepts were mine but the words themselves aren’t. i want to say that because its important for me to distinguish, as a writer, what is written ‘by me’ and what’s not. maybe that idea will seem insane and antiquated in a year, i’m not sure, but for now it helps me feel okay about putting stuff out there like this that a) i know is helpful and b) is not MY voice but exists within the umbrella of my business and work. If you have any thoughts or musings on this, i’d genuinely love to hear them - its an open question, all of this stuff, and my guess is as good as yours.