CLAUDE.md Size Effects

Your CLAUDE.md loads into context every single session. It's always-on cost. That makes its size one of the most important optimization decisions you'll make.

Size vs. effectiveness

Not all CLAUDE.md files are created equal. Here's how size affects Claude Code's behavior:

The fix: move details elsewhere

The solution isn't to delete useful information -- it's to put it in the right place. Claude Code has purpose-built features for this:

.claude/rules/ -- path-specific rules

Rules are markdown files that only load when Claude Code is working on matching files. They stay out of context until they're relevant.

.claude/
  rules/
    testing.md      → only loads when working on *.test.ts files
    api.md          → only loads when working on src/api/** files
    components.md   → only loads when working on src/components/** files

This means your testing conventions only consume tokens when you're actually working on tests. Your API patterns only load when you're in the API layer.

Skills/commands -- on-demand loading

Custom commands (like the ones you built in Chapter 2) only load their full content when invoked. Their descriptions appear at session start, but that's just a sentence or two.

The result: a lean CLAUDE.md

Keep CLAUDE.md focused on what Claude Code needs every session: project overview, tech stack, build commands, and key conventions.

Before and after

Here's a real example of slimming down a bloated CLAUDE.md:

BEFORE: 300-line CLAUDE.md with everything

# My Project
Tech stack, overview, build commands...
 
# Code Conventions (50 lines)
Naming, file structure, import ordering...
 
# Testing Patterns (80 lines)
Test file naming, mocking strategies, coverage thresholds,
example test templates...
 
# API Documentation (70 lines)
Endpoint patterns, error handling, auth flow,
request/response formats...
 
# Deployment Steps (40 lines)
Build process, environment variables, staging vs production,
rollback procedures...
 
# Troubleshooting (60 lines)
Common errors, debug techniques, log locations...

AFTER: 60-line CLAUDE.md + targeted files

# My Project
Tech stack, overview, build commands...
 
# Code Conventions (50 lines)
Naming, file structure, import ordering...
 
# Quick Reference
- Run tests: npm test
- Build: npm run build
- Deploy: /project:deploy

Plus these separate files that load only when needed:

.claude/rules/testing.md          → testing patterns (80 lines)
.claude/rules/api.md              → API conventions (70 lines)
.claude/commands/deploy.md        → deployment steps (40 lines)
.claude/commands/troubleshoot.md  → debugging guide (60 lines)

Same total information. But now the per-session token cost is 60 lines instead of 300 -- and the instructions Claude Code does see, it follows more reliably.

The rule of thumb

If you find yourself adding something to CLAUDE.md, ask: "Does Claude Code need this for every task, or only for specific kinds of work?" If the answer is "specific kinds," it belongs in a rule or command, not in CLAUDE.md.