CLAUDE.md — the project instruction file Claude Code reads at the start of every session, written by hand by a person. This article flips the guidance in Claude Code's official memory documentation to spotlight six CLAUDE.md mistakes seen often on usingclaude.com, pairing each with a before/after fix. If your project already has a CLAUDE.md, you can skim this in five minutes and find something to fix immediately.
🟢 Model references match the current lineup · model notice · Fable subscription
Fable 5 and 5.1 subscription (updated September 7, 2026): Claude Fable 5.1, released September 1, 2026, is the current Fable model and Fable 5 is now legacy. Plan terms are the same for both — Max and Team Premium plans include Fable at up to 50% of the weekly usage limit; Pro and Team Standard use usage credits (
How are CLAUDE.md and auto memory different?
CLAUDE.md is an instruction file you write by hand; auto memory is a set of learning notes Claude writes itself based on your corrections and preferences. The official docs draw the line this way: use CLAUDE.md files when you want to guide Claude's behavior, and auto memory to let Claude learn from your corrections without manual effort. As the diagram above shows, CLAUDE.md is entirely human-written and loaded in full every session, while auto memory accumulates per repository but only the first 200 lines or 25KB load per session. Confusing the two roles is exactly what causes anti-pattern 6 below.
Quick term glossary
- CLAUDE.md — a markdown instruction file you write by hand for a project or your personal workflow.
- Auto memory — learning notes Claude writes itself, based on your corrections and preferences.
- Skill — a way to move a multi-step procedure into its own file. The official docs say that if an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead.
- Path-scoped rule — an instruction placed under
.claude/rules/so it applies only to specific paths or file types. - Hook, specifically a PreToolUse hook — a rule that runs automatically in a given situation. Since Claude treats CLAUDE.md as context, not enforced configuration, the docs say to use a PreToolUse hook when you need to block an action regardless of what Claude decides.
- CLAUDE.local.md — a file for personal, project-specific preferences, meant to be added to
.gitignoreso it isn't committed.
| Anti-pattern | Why it's a problem | How to fix it |
|---|---|---|
| 1. Bloated and unfocused | Specific, concise instructions are followed more consistently — this goes the other way | Trim to core rules only |
| 2. Narrow procedures at the top level | Multi-step procedures don't belong in CLAUDE.md | Move to a skill or path-scoped rule |
| 3. Treated as a hard block | Claude treats it as context, not enforcement | Use a PreToolUse hook for real blocking |
| 4. Personal info committed to a shared file | ./CLAUDE.md is shared with the team via source control | Move to CLAUDE.local.md and gitignore it |
| 5. Repeated corrections never recorded | You re-explain the same thing every session | Record it the second time it repeats |
| 6. CLAUDE.md and auto memory roles mixed up | Manually managing what Claude would learn on its own | Check with /memory, split the roles |
Anti-pattern 1: Filling CLAUDE.md with too much, too vague content
The more specific and concise your instructions, the more consistently Claude follows them — so a CLAUDE.md stuffed with everything works against itself. The official docs state this directly, and treat an oversized CLAUDE.md as common enough to get its own troubleshooting entry.
❌ Before
- This project started a while back for various reasons...
- Please try to write clean, nice-looking code
- It's good to check a few things before committing
- CI sometimes fails weirdly, just retry it
✅ After
- Build: npm run build / Test: npm run test
- Lint must pass before every commit
- API responses always use camelCaseThe "before" version is full of vague phrases like "try to," "a few things," and "sometimes," leaving Claude to guess what actually matters. The "after" version keeps only concrete commands and "always do X" rules, which are easier to follow consistently.
Anti-pattern 2: Putting a narrow, multi-step procedure at the top level
A multi-step procedure, or anything that only matters for one part of the codebase, belongs in a skill or a path-scoped rule, not in CLAUDE.md. The official docs state this exact criterion: if an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead.
❌ Before (root CLAUDE.md)
- Payment module deploy procedure:
1) Deploy to staging
2) Wait for QA sign-off
3) Run migration scripts
4) Deploy to production
5) Check monitoring dashboard
...(continues)
✅ After
- Payment module deploy procedure → see skills/deploy-payment
- (full procedure moved to a dedicated skill file)Keeping a narrow, multi-step procedure like a deploy sequence at the top level means it gets loaded in full every session, even for work that has nothing to do with it, bloating CLAUDE.md over time. Moving it to a skill or a path-scoped rule under .claude/rules/ lets it load only when relevant.
Anti-pattern 3: Treating CLAUDE.md as a hard block
Writing "never do this" in CLAUDE.md gives Claude context to consider, not a guarantee it will be enforced. The official docs are explicit: Claude treats CLAUDE.md as context, not enforced configuration, and to block an action regardless of what Claude decides, you should use a PreToolUse hook instead.
❌ Before
- Never connect to the production database
(→ written in CLAUDE.md and assumed to be "safe now")
✅ After
- Don't connect to the production database (CLAUDE.md, context)
- + A PreToolUse hook that actually blocks the dangerous command
(enforced regardless of Claude's judgment)A CLAUDE.md line is guidance Claude follows most of the time, not a 100% guarantee. For anything that truly must never happen, pair the instruction with a PreToolUse hook that enforces it directly.
Anti-pattern 4: Committing personal-only info to a shared CLAUDE.md
A personal sandbox URL or test data belongs in CLAUDE.local.md, not in the project CLAUDE.md that your whole team shares. The official docs' location table describes project instructions (./CLAUDE.md) as "team-shared instructions... shared with team members via source control," while local instructions (./CLAUDE.local.md) hold "personal project-specific preferences," are meant to be "added to .gitignore," and are illustrated with examples like "your sandbox URLs, preferred test data."
❌ Before (./CLAUDE.md, shared and committed)
- My local test DB is at localhost:5433
- My personal staging server: my-sandbox.example.com
✅ After
./CLAUDE.md → team-wide build commands and rules only
./CLAUDE.local.md → personal sandbox URL, test data
(added to .gitignore)The key point to watch for: project CLAUDE.md is committed through source control, so every teammate's session loads it. Accidentally dropping a personal URL or test account there means it now loads for everyone else too.
Anti-pattern 5: Never recording a correction you keep repeating
If the same mistake or the same correction keeps coming up, that repetition is the signal to add it to CLAUDE.md. The official docs list four specific triggers: Claude makes the same mistake a second time; a code review catches something Claude should have known about the codebase; you type the same correction or clarification into chat that you typed last session; or a new teammate would need the same context to be productive.
❌ Before
Session 1: "Please write commit messages in Korean"
Session 2: "Oh, commit messages should be in Korean"
Session 3: "Commit messages in Korean, please!" (keeps repeating)
✅ After
The moment the same correction repeats a second time, add one line to CLAUDE.md:
- Write commit messages in KoreanThe docs describe CLAUDE.md as "the place you write down what you'd otherwise re-explain." If you're typing the same correction session after session, moving that exact sentence into CLAUDE.md is enough to close this anti-pattern.
Anti-pattern 6: Mixing up the roles of CLAUDE.md and auto memory
If you're manually copying debugging insights or small preferences into CLAUDE.md by hand — things Claude would have learned on its own — the two systems' roles have gotten mixed up. According to the official comparison table, CLAUDE.md is meant for "coding standards, workflows, project architecture," while auto memory is meant for "build commands, debugging insights, preferences." The latter is better left for Claude to record automatically from your corrections.
❌ Before
- Debugging tips and small preferences (that Claude would
already learn on its own) get manually copied into CLAUDE.md
every time
✅ After
- CLAUDE.md holds only rules you always want enforced
- Debugging insights and preferences accumulate in auto memory
- Curious what's saved? Check with the /memory commandThe official docs' "audit and edit your memory" section explains that the /memory command lets you view and edit what's been saved. Before manually adding something to CLAUDE.md, checking /memory first to see if it's already been captured automatically can save you duplicate work.
Where should each kind of content go?
Which file to use depends on how widely the content should be shared: managed policy, user CLAUDE.md, project CLAUDE.md, or CLAUDE.local.md. The official docs list these four locations "in load order, from broadest scope to most specific," so a project instruction appears in context after a user instruction.
CLAUDE.md and CLAUDE.local.md files above your working directory load in full at launch, while files in subdirectories load on demand, only when Claude reads files in that directory. In a large project, using subdirectory files or path-scoped rules under .claude/rules/ is another way to shrink the "bloated, unfocused CLAUDE.md" problem covered in anti-patterns 1 and 2.
Frequently asked questions
Q. If I write "never run this command" in CLAUDE.md, will it actually be blocked?
No, not on its own. The official docs state that Claude treats CLAUDE.md as context, not enforced configuration, so anything that must be blocked regardless of Claude's judgment needs a separate PreToolUse hook.
Q. How do I check what's been saved in auto memory?
Use the /memory command to view and edit it. The official docs point to this command for auditing and editing auto memory.
Q. Does CLAUDE.md always load in full every session?
CLAUDE.md and CLAUDE.local.md files above your working directory load in full at launch, but files in subdirectories load on demand, only when Claude reads files in that directory.
Q. If I have managed policy, user, project, and local CLAUDE.md files all at once, what order do they apply in?
They load from broadest scope to most specific. The official docs list the order as managed policy, then user instructions, then project instructions, then local instructions, so a project instruction ends up in context after a user instruction.
All six anti-patterns share one root cause. CLAUDE.md works best as specific, concise instructions, and anything outside that scope — multi-step procedures, hard blocks, personal info, or things Claude would learn on its own — has its own proper home: a skill, a hook, CLAUDE.local.md, or auto memory. That's the organizing principle the official docs point to.
Related articles
- CLAUDE.md Templates — Copy-Paste Sections and Examples
- CLAUDE.md examples by project type — ready to paste
- What Is CLAUDE.md? — A Simple Explanation for First-Timers
- The Complete CLAUDE.md Guide: Project Memory for Claude Code
- CLAUDE.md Examples: Web App, Monorepo, Rules & Anti-patterns (Copy-Paste)