Why I use multiple small CLAUDE.md files instead of one big one
My first CLAUDE.md was 800 lines. It covered everything: code style, commit format, testing requirements, error handling conventions, API rate limits, deployment constraints, naming conventions. Everything I'd ever want an agent to know.
It didn't work well.
The problem with one big file
It gets loaded into every turn. 800 lines of context burned on the rare case where the agent needs to know the deployment process for a session that's only doing test coverage.
More importantly: long files create priority ambiguity. Which rules matter most? If there's a conflict between two conventions, which wins? The agent handles this reasonably but imperfectly. Shorter files with clearer scope make the hierarchy obvious.
What I do instead
Core CLAUDE.md (under 100 lines): The rules that apply to every session. Commit format, don't-touch-files-outside-scope, write-tests-first, stop-condition protocol. Things that never change.
Domain-specific files (50-100 lines each): I create these in subdirectories or as separate files that get included when relevant.
-
CLAUDE-api.md: Rate limiting rules, auth patterns, error handling for external calls -
CLAUDE-testing.md: Test file conventions, what gets tested, coverage expectations -
CLAUDE-deploy.md: Build process, environment variables, what not to touch before deploy
Task-specific context: Included in the prompt for that task. "The auth module uses JWT with a 15-minute expiry and refresh token rotation. The refresh logic is in lib/auth/refresh.js." This context is specific to the task and doesn't need to live in CLAUDE.md.
How it works in practice
I start a session with the core CLAUDE.md and then include relevant domain files in the task prompt:
See CLAUDE.md for general rules and CLAUDE-api.md for API conventions.
Task: [specific task]
The agent loads what it needs. Sessions that don't touch APIs don't pay the context cost of API rules. Sessions that do have the exact rules they need.
The one rule that stays in the core
"If a file you need information from isn't in context, ask before assuming."
This is the rule that prevents the agent from inventing conventions. If it needs to know the API error handling pattern and CLAUDE-api.md isn't in context, it asks instead of guessing. That one rule compensates for anything I forgot to include.
From running Claude Code on builtbyzac.com.
