Most CLAUDE.md files fail for the same reason: they're written for humans. Here's how to write one Claude will actually follow.
Most CLAUDE.md files I read fail for the same reason: they're written for humans. Onboarding docs, README-style explanations, paragraphs of context. Claude reads them, sure, but it doesn't follow them — because they don't read like instructions, they read like background material.
CLAUDE.md is not a README. It's a system prompt fragment that gets prepended to every Claude Code session in that directory. Treat it like one. Every line is competing for a slot in a finite instruction budget, and every paragraph that exists to make a human nod along is a paragraph displacing something Claude actually needs to obey.
This guide covers what CLAUDE.md does, what belongs in it, the five sections every file should have, and how to verify Claude is actually loading and following your rules.
When Claude Code starts a session, it walks up the directory tree from your current working directory looking for CLAUDE.md files. It loads them all — global (~/.claude/CLAUDE.md), project root, and any nested ones along the path. Their contents get injected into the system prompt before your first message.
A few mechanics worth knowing:
~/.claude/CLAUDE.md always loads, regardless of project.CLAUDE.md files load only when Claude opens files in that subtree.The file is parsed as Markdown. Claude doesn't run any code in it — headings, lists, and tables exist purely to make the structure legible. Use them.
Here's the constraint nobody puts on the box: Claude reliably follows roughly 150 to 200 distinct instructions per session. Past that, instruction-count decay sets in. Rules get ignored. The model picks favorites. You'll see Claude follow rules 1 through 12, then rule 47, then drift on everything in between.
If your CLAUDE.md is 600 lines of prose, you have far more than 200 instructions in there — and you don't get to pick which ones survive. The model does.
Two implications:
This is the single biggest reason CLAUDE.md files fail. Engineers write the file the way they'd write internal documentation: thorough, complete, defensive. That habit produces a 900-line file that Claude treats as a suggestion.
Order matters. Claude reads top to bottom and biases toward instructions at the edges (top and bottom of the prompt). Put the load-bearing rules at the top.
Two or three sentences. Who you are, what this project is, what stack. Not a history lesson — just enough that Claude doesn't have to guess.
## Identity
Solo founder building CoworKit — a Claude productivity tool built with
Node.js, Express, PostgreSQL, and EJS templates. Revenue: early (< $5k MRR).
Stack: Express routes, Neon DB via pg Pool, EJS views, no frontend framework.
Numbered list. Two to six items. This is the most underused section in real CLAUDE.md files and the highest-impact one to add. It tells Claude how to interpret ambiguous requests.
## What I Use You For
1. Implementing features end-to-end: route, DB layer, EJS template
2. Debugging production errors from logs
3. Writing and reviewing database migrations
4. Reviewing diffs before I push — catch logic errors, not style
How you want responses formatted. Be specific. "Be concise" is not specific. "Default to bullet lists, code blocks for any snippet over two lines, no preamble" is specific.
## Communication Style
- No preamble. Skip "Great question!" and "Sure, I can help with that."
- Bullets over paragraphs unless I ask for prose.
- Code first. Show the code, then explain if I need it.
- If I'm wrong about something, correct me directly. Don't soften it.
Things Claude must never do, or must always do. Imperative voice. Numbered so you can reference them.
## Hard Rules
1. All schema changes go in migrations/. Never ALTER TABLE in runtime files.
2. Do not commit or push unless I explicitly ask.
3. All user input goes through Zod schemas before hitting the DB.
4. Use React Server Components by default. Client components only when required.
5. No emoji anywhere — not in code comments, not in copy, not in logs.
Acronyms, internal naming, project-specific terms. Without this, Claude will fabricate plausible-sounding wrong definitions on your first ambiguous prompt.
## Domain Glossary
- Generator: the main app page at /generator — 4-tab tool for creating CLAUDE.mds
- Starter Kit: a bundled .plugin file with pre-configured Claude Code settings
- Trim: the "Trim Existing" tab — shortens an existing CLAUDE.md to a target length
- CoworKit: the app that hosts the Builder, Analyzer, guides, and Starter Kits
That's it. Five sections. Under 200 lines. If your CLAUDE.md has thirty H2s, you've written documentation, not a system prompt.
The single rewrite that improves CLAUDE.md output most is replacing abstract guidance with concrete constraints. Claude is a probabilistic system: "be careful with database changes" and "show me the SQL diff before running any migration" produce different behaviors, even though they mean the same thing to a human reader.
Bad (abstract):
Be careful with database changes and make sure not to break anything.
Write clean, maintainable code following best practices.
Communicate clearly and don't make assumptions.
Good (concrete):
Before running any migration: show me the SQL it will execute and wait for my go-ahead.
All DB queries go in db/<entity>.js. Never write pool.query() in a route handler.
If you're unsure what I mean, say "I'm assuming X — is that right?" before proceeding.
The test: if a rule can't be violated in a way you'd catch in code review, it's not a rule. Delete it.
Three locations matter:
~/.claude/CLAUDE.md — global. Your personal preferences across every project. Communication style belongs here. These rules apply everywhere.<project-root>/CLAUDE.md — project-specific. Stack, conventions, hard rules for this codebase. This is the main file.<subdir>/CLAUDE.md — scoped. Useful in monorepos where apps/web and apps/api have different conventions. The subdir file loads only when Claude is working inside that directory.Rules from deeper files take precedence when there's a conflict. This means your global preferences apply everywhere as a baseline, and project files can override them where needed. If your global file says "always use TypeScript" but your project file says "this is plain JavaScript," the project file wins.
The most common mistake: writing a CLAUDE.md, opening Claude Code, and assuming it works because it loaded. Loading isn't following.
Use /context to confirm the file loaded. In Claude Code, type /context to see what's in the system prompt. Your CLAUDE.md content should appear. If it doesn't, the file isn't in the right location or isn't named correctly (case-sensitive: CLAUDE.md, not claude.md).
Test rules functionally, not visually. Don't scan the output looking for compliance. Give Claude a task specifically designed to trigger each rule:
/generator, not invent a definition.Read a session transcript when something goes wrong. If Claude violated a rule, the transcript usually shows whether it was ignored from the start or drifted mid-session. Early violation = rule not loaded or too deeply buried. Mid-session drift = rule was applied initially but didn't survive the context window. Fix: move the rule higher in the file.
If you want a deeper analysis of how Claude is interpreting your sessions, CoworKit's Analyze My Chats tool scores conversations for instruction-following consistency, identifies which rules aren't landing, and recommends specific rewrites.
The Encyclopedia. A 1,200-line file covering every possible scenario. Claude loads it, processes the first 200 instructions reliably, and treats the rest as optional context. Fix: cut to what actually matters, move reference data to separate files.
The Wish List. "Be insightful. Be creative. Be thorough but concise." Abstract aspirations with no behavioral specificity. Claude interprets these as permission to do whatever looks good. Fix: replace every adjective with a measurable constraint.
The Autobiography. Three paragraphs of background on who you are, your career history, how you got into your field. Claude doesn't need this. It needs to know what you make right now. Fix: one sentence on your role, one on your current project, one on your stack. Done.
The Everything-Bagel. Rules from twelve different contexts mixed together: coding rules, writing rules, meeting notes, project status, old decisions that no longer apply, TODO items. CLAUDE.md is not a project management tool. Fix: strip anything that isn't an operating rule. Move everything else to a separate file that you reference explicitly when needed.
Where exactly does Claude Code look for CLAUDE.md?
It walks the directory tree upward from your current working directory, loading any CLAUDE.md it finds at each level. It also always loads ~/.claude/CLAUDE.md regardless of your current directory. Files are loaded in order from global to local — deepest file is the highest priority.
What's the difference between CLAUDE.md and AGENTS.md?
CLAUDE.md is Claude Code's convention — it's specific to Anthropic's Claude Code product. AGENTS.md is a more recent, product-agnostic convention used by tools like Cursor and others that support custom agent instructions. The format is similar; the key difference is which tool reads which file. If you use Claude Code, use CLAUDE.md. If you use multiple coding tools, check each tool's documentation — some read both.
How long should a CLAUDE.md be?
Under 200 lines of actual instructions. If you need more space, you're either repeating yourself or writing documentation instead of rules. Reference material (API schemas, glossary entries, long examples) can live in separate files that you ask Claude to read when relevant.
Does Claude reliably follow everything in CLAUDE.md?
Not perfectly — no LLM applies every instruction in a long context window with equal consistency. The 200-instruction ceiling is real. What you can control: put your most important rules at the top, write concrete constraints instead of abstract guidance, and test each rule with a fresh session after writing it.
Can I have multiple CLAUDE.md files in one repo?
Yes, and for monorepos you should. Put project-wide rules at the root. Put module-specific rules in each subdirectory. Claude loads both when working inside the subdirectory. This is cleaner than a 400-line root file that tries to cover everything.
What should I do when Claude keeps ignoring a rule?
First, check it's not buried: rules in the bottom third of a long file get the least consistent application. Move it to the top. Second, check it's specific enough: "be careful" is not a rule. "Show me the output before running it" is. Third, check for conflicts: if two rules pull in opposite directions, Claude picks one and ignores the other. Find the conflict and resolve it. If the rule still isn't landing after these fixes, rewrite it in imperative voice: "Always X" or "Never Y" — not "Try to X" or "Prefer Y."
If you're starting from scratch, CoworKit's generator asks 5–6 questions about your role and workflow and produces a scored, structured CLAUDE.md. Free, no signup required.
If you already have a CLAUDE.md that's grown unwieldy, the Trim tab cuts it to a target length while preserving the highest-impact rules, and the Optimize tab resolves conflicting rules and replaces vague guidance with concrete constraints.
Practical guides and prompt patterns — no fluff, unsubscribe any time.