Claude Code Rules: What to Put in CLAUDE.md and .claude/rules
By Neo Zino - builder of ClockedCode10 min readClaude Code rules are single lines in CLAUDE.md or .claude/rules that Claude reads each session. See which to write, how to scope them, and which to leave out.
Made with DispatchSEO
On this page
A Claude Code rule is one instruction, written as a line in a markdown file, that Claude reads as context at launch or when it touches matching files. The ones that work are short, checkable, and tied to a mistake you already watched Claude make. Put project-wide rules in CLAUDE.md, one-topic or file-specific rules in .claude/rules/, and anything that must never slip in a hook.
TL;DR: Start with five rules: verify before done, stay in scope, ask before adding dependencies, commit message format, no destructive commands without asking. Keep each file under 200 lines. Scope the rest with
paths:frontmatter so they only load when needed. Rules are guidance, not enforcement.
Five homes for a rule
- CLAUDE.mdEvery sessionRules the whole project follows
- ~/.claude/rules/Every session, before project rulesYour habits in every repo
- .claude/rules/*.mdEvery session, same priority as CLAUDE.mdOne topic per file
- .claude/rules/ with paths:When Claude reads a matching fileRules for one part of the codebase
- A hook in settings.jsonRuns as a shell command, not readAnything that must happen every time
Which file should a rule go in?
Anthropic's memory docs describe a stack, and the choice comes down to who needs the rule and when.
./CLAUDE.mdor./.claude/CLAUDE.mdfor rules the whole project follows. Commit it so the team shares it..claude/rules/*.mdfor one topic per file, liketesting.mdorsecurity.md. Files are found recursively, sofrontend/andbackend/subfolders work.~/.claude/CLAUDE.mdand~/.claude/rules/for your own habits in every repo. User-level rules load before project rules.- A hook for anything that has to happen every time. Both CLAUDE.md and rules are delivered as context, and the docs are explicit that Claude may not comply strictly.
The split between a short CLAUDE.md and rule files is mostly about organization, plus one real saving: rules with a paths field do not cost context until Claude reads a matching file. If you are still deciding between memory systems, CLAUDE.md vs auto memory covers that choice. The full file hierarchy is in the complete CLAUDE.md guide.
What does a good rule look like next to a bad one?
A good rule names an action you could check in a diff. The docs make the same point with their own example: "Use 2-space indentation" works better than "format code nicely."
| Weak rule | Rule Claude can follow |
|---|---|
| Write clean code | Prefer early returns over nested conditionals |
| Be careful with the database | Never run DROP or DELETE without asking first |
| Test your work | Run pnpm lint and pnpm build before saying a task is done |
| Keep commits tidy | Commit messages are imperative, under 72 characters, one change each |
| Don't over-engineer | No new abstraction until two real call sites need it |
Two habits keep rules honest. Write each one in the form "do X" or "never X", and write it after you have seen the failure, not before. A rule you cannot tie to a past mistake is a guess, and guesses are where a 400-line file comes from.
Which rules are worth having in every project?
Five earn a place almost everywhere because each one stops a failure that costs you review time. Here is the starter file I would paste into a fresh repo:
# Project rules
- Run `pnpm lint` and `pnpm build` before saying a task is done. Paste the last 10 lines of output.
- Only change files the task names. If a nearby file needs a fix, list it at the end instead of editing it.
- Ask before adding a dependency. Name the package, its size, and what it replaces.
- Commit messages: imperative mood, under 72 characters, one logical change per commit.
- Never run destructive commands (rm -rf, git reset --hard, DROP TABLE) without asking first.
Swap pnpm for your package manager and the first rule is the one I would keep above all the others, because "it should work" without a run is the most common false finish. My own global file carries a verification rule for the same reason, and the annotated real example explains why each of its lines is there. For rules shaped by project type, CLAUDE.md examples has twelve across solo, team, and monorepo setups.
If you would rather not write the first draft, the CLAUDE.md generator builds one from a few questions.
How do you scope a rule to certain files with paths?
Put frontmatter at the top of a file in .claude/rules/. Per the docs, paths is the only field Claude Code reads from a rule; anything else is ignored without an error.
---
paths:
- "src/api/**/*.{ts,tsx}"
---
# API rules
- Validate input at the route boundary with zod.
- Return the shared error shape from src/api/errors.ts.
- Never log request bodies.
The rule loads when Claude uses Read, Write, or Edit on a matching file, and also when a Bash command like cat views a single matching file. A few details from the docs that catch people:
- Brace groups multiply:
src/*.{ts,tsx}expands to 2 patterns,{a,b}/{c,d}/*.{ts,tsx}to 8. A rule's wholepathslist shares one budget of 1,000 expanded patterns. - A
pathslist that fails to parse as YAML is ignored, and the rule loads as if it had no scope.claude --debugshows the parse error. - A rule without
pathsloads unconditionally at launch, same priority as.claude/CLAUDE.md. - Symlinks work, so one shared rules folder can be linked into several repos. A link that points outside the project asks for approval once.
To see what actually loads, run /context and read the Memory files list. Path-scoped rules and nested CLAUDE.md files will not appear there, because they load on demand. The InstructionsLoaded hook logs when each file loads and why, which is the quickest way to debug a scoped rule that never fires.
What does a five-rule setup cost in context?
I built a small version of this setup in a scratch directory and counted it with wc: the five-rule CLAUDE.md above, an unscoped code-style.md, and two scoped files (testing.md and api.md).
$ wc -lc .claude/CLAUDE.md .claude/rules/*.md
7 491 .claude/CLAUDE.md
10 190 .claude/rules/api.md
5 181 .claude/rules/code-style.md
11 248 .claude/rules/testing.md
33 1110 total
$ cat .claude/CLAUDE.md .claude/rules/code-style.md | wc -lc
12 672
What loads when - 4 files, 33 lines, 1,110 bytes
12 lines
672 bytes, 61% of the total
- .claude/CLAUDE.md - 7 lines, 491 bytes
- .claude/rules/code-style.md - 5 lines, 181 bytes
21 lines
438 bytes, 39% of the total
- .claude/rules/testing.md - 11 lines, 248 bytespaths: **/*.test.ts, tests/**/*
- .claude/rules/api.md - 10 lines, 190 bytespaths: src/api/**/*.{ts,tsx}
Only the CLAUDE.md and the unscoped file load at launch: 12 of 33 lines, 672 of 1,110 bytes. The other 21 lines wait for a test file or an API file. That is a tiny example, so the saving is small in absolute terms. The shape is what matters: as the scoped files grow, the launch cost stays flat.
I could not run Claude Code against this directory in this environment because it was not logged in, so these numbers describe file sizes and the documented loading rules, not a measurement of the model's behavior. For scale, this repo's own instruction load is a 21-line CLAUDE.md (1,942 bytes) plus a 105-line AGENTS.md (12,253 bytes), 126 lines in total, well inside the 200-line guidance for each file.
Which rules should you leave out?
Lines that do not earn their place
- Directory listings and file toursClaude can read the tree itselfDelete it
- "Write clean code" and other wishesNothing to check, nothing to followA testable line
- Multi-step proceduresCosts context on every turnA skill
- Rules that repeat a linterThe tool already enforces itLint config or a hook
- "Always" rules that must never slipCLAUDE.md is context, not enforcementA hook
The docs say it directly: keep CLAUDE.md to facts Claude should hold in every session, and move multi-step procedures or single-area guidance to a skill or a path-scoped rule. Two more cuts I make on a first pass:
- Anything contradicting another rule. The docs warn that if two instructions conflict, Claude may pick one arbitrarily. This includes a user-level rule fighting a project rule, since neither overrides the other.
- Anything Claude Code already does itself. If your commit rules compete with the built-in git instructions, the docs point at the
includeGitInstructionsandattributionsettings rather than piling on more text.
Claude Code can also audit the pile for you. The memory docs describe a prompt audit through /doctor that covers CLAUDE.md, AGENTS.md, and the rules, skills, and subagents under .claude/.
Why does Claude break a rule you wrote?
Work down this list in order:
- It never loaded. Run
/context. A missing file under Memory files is invisible to Claude, and the fix is the file's location. - The scope is wrong. A
pathsglob that matches nothing means the rule never fires. Test it by asking Claude to read a file you expect it to match. - The rule is vague. Rewrite it as something checkable, using the table above.
- The file is too long. Past 200 lines adherence drops, and the docs show a startup warning when files run long. Each CLAUDE.md, rules file, and
@pathimport counts separately toward the combined limit. - It was only said in chat. Chat instructions do not survive a new session. Project-root CLAUDE.md is re-read from disk after
/compact, so a rule written there survives, as covered in the auto-compact guide.
If a rule survives all five checks and still slips, the problem is the tool, not the wording.
When a rule is the wrong tool
Rules are probabilistic. For "run the formatter after every edit" or "block writes to the migrations folder", a rule will work most of the time and fail at the worst moment. Hooks run as shell commands at fixed points and apply regardless of what the model decides, so see what hooks are in Claude Code and hooks examples for the pattern. Rules are also the wrong place for a long procedure (use a skill, see Claude Code skills) and for one-off task context (say it in the prompt).
FAQ
What are Claude Code rules?
Claude Code rules are plain-markdown instructions Claude reads as context: lines in a CLAUDE.md file, or whole files in .claude/rules/. Rules without a paths field load at launch. Rules with a paths field load when Claude reads a matching file. They shape behavior but are not enforced.
Where do I put Claude Code rules?
Project-wide rules go in ./CLAUDE.md or ./.claude/CLAUDE.md. One-topic files go in .claude/rules/, such as testing.md. Personal rules that apply to every repo go in ~/.claude/CLAUDE.md or ~/.claude/rules/. Use /context to confirm the file actually loaded.
How do I make a rule apply only to certain files?
Add YAML frontmatter with a paths list of glob patterns at the top of a file in .claude/rules/, for example paths: ["src/api/**/*.ts"]. The rule loads when Claude reads, writes, or edits a matching file instead of at launch.
How many rules should I have?
Fewer than you think. Anthropic's docs recommend keeping each CLAUDE.md under 200 lines because longer files cost context and reduce adherence. A first project file usually needs five to ten rules. Add one only when you have watched Claude make the mistake it prevents.
Why does Claude Code ignore my rules?
Usually the file is not loaded (check /context), the rule is vague, two rules conflict, or the file is too long. If a rule must hold every time, rules are the wrong tool: use a hook, which runs as a shell command regardless of what the model decides.
Do .claude/rules files override CLAUDE.md?
No. Rules without a paths field load at launch with the same priority as .claude/CLAUDE.md. User-level rules load before project rules, but neither overrides the other, and if they conflict Claude may follow either. Keep them consistent.
Start small, then prune
Five rules you can verify beat fifty you cannot. ClockedCode ships a tuned global CLAUDE.md built on that idea, so you begin with a short file that already respects these limits.