When Claude Code does not follow CLAUDE.md, check whether the file loaded before making it longer. Then look for ambiguous wording, conflicting instructions, and requirements that should be enforced by tools rather than remembered in prose.
CLAUDE.md is project guidance, not a guarantee that every action will comply. The official memory documentation makes that distinction and describes /context for checking loaded memory files and /memory for opening and editing them. The practical goal is to make important rules visible, specific, and independently verifiable.
First identify the failure
Save one example of the behavior you wanted and what happened instead. “Claude ignores our conventions” is too broad to diagnose. “It ran npm even though this repository uses pnpm” gives you a concrete rule to test.
| Observation | Likely area to investigate |
|---|---|
| File is absent from the loaded context | Location or session scope |
| File is present but the rule is vague | Instruction wording |
| Two files prescribe different commands | Conflicting guidance |
| Correct command is known but fails | Environment or dependencies |
| A forbidden change still happens | Missing technical enforcement |
A command failure is not necessarily an instruction failure. If the specified test command cannot run because a service is unavailable, fix that prerequisite or document the limitation. Do not quietly replace a meaningful test with a command that always succeeds.
1. Check the file that the session can see
Run /context in Claude Code and inspect the memory file list. Use /memory to locate the instruction files. A nested CLAUDE.md can load when Claude accesses files under its directory, so a file inside a subdirectory may not appear among the files loaded at startup. These loading behaviors are covered in the memory troubleshooting guide.
For your own debugging notes, write down the repository root, the location of the instruction file, and the path being edited. This is especially useful with worktrees or several clones. Editing instructions in one checkout does not help a session operating in another.
Do not rely only on asking the model, “Did you read the file?” Inspect the available loading evidence and evaluate the next actual action. A confident explanation is less useful than the correct command appearing in the execution history.
2. Replace broad advice with observable rules
Compare these two instructions:
Keep the code clean and test everything properly.
Use pnpm for this repository.
Before finishing a change to the invoice parser, run:
pnpm test -- invoice-parser
Report the result. If the command cannot run, report the error.
Do not claim the tests passed when they were not executed.
The second example is an original template, not a command for every project. Replace it with a command that exists in your repository. The improvement comes from defining the trigger, the action, and the evidence of completion.
For a UI project, a useful rule might identify the existing component library and an example page to follow. For a data pipeline, it might identify the input schema and a fixture with known output. Concrete references reduce interpretation without turning the file into a copy of the whole repository.
3. Resolve contradictions instead of adding emphasis
Look for old setup notes, personal preferences, nested instructions, and current task requests that disagree. Common examples include npm versus pnpm, Jest versus Vitest, or an obsolete deployment directory.
Create a small reconciliation table while cleaning the instructions:
| Rule | Current source of truth | Change needed |
|---|---|---|
| Package manager | Committed lockfile and project setup | Remove stale npm example |
| Unit test command | Existing package script | Correct outdated script name |
| Generated files | Current build process | List actual generated paths |
Capital letters and repeated “MUST” statements will not resolve two incompatible commands. Remove stale guidance and explain any exception next to the rule it modifies. Keep the common path easy to find.
4. Keep a short operational core
Use CLAUDE.md for the information a contributor needs to act correctly: the key commands, important directory boundaries, conventions that are not obvious, and the checks required before reporting completion.
Move long tutorials and background explanations into project documentation. A useful starting outline is:
# Project instructions
## Commands
- Install: [verified command]
- Test: [verified command]
- Build: [verified command]
## Boundaries
- Generated files: [paths]
- Changes requiring a migration: [conditions]
## Verification
- Match checks to the files changed.
- State what ran, what passed, and what could not run.
Fill in the brackets before using it. An unfinished template is worse than a short accurate file because it looks actionable while omitting the details that matter.
5. Enforce requirements that cannot be optional
Use CI checks, repository permissions, and appropriately configured hooks for requirements that need technical enforcement. The Claude Code documentation recommends hooks for actions that must happen at a particular lifecycle event. A sentence in a memory file is not an access-control boundary.
For example, require a passing test job before merging a change. Keep credentials out of files the task does not need. Use a formatter check to verify formatting instead of relying on a prose instruction to catch every whitespace difference.
Test the fix on one small task
Choose a reversible change that exercises the missed instruction. Record whether the correct command ran and whether the final report matches the output. If it works, try a second task in the affected subdirectory. This is a better check than asking the assistant to summarize the new rules.
If the missed instruction belongs to an optional workflow rather than the whole repository, consider a reusable skill. If that skill cannot be found, use the separate skill loading diagnostic.
FAQ
Does CLAUDE.md guarantee compliance?
No. It supplies instructions as context. Use technical checks and permissions for requirements that must be enforced independently of the assistant's judgment.
Should I put every project document into CLAUDE.md?
Keep a concise operational core and point to relevant documentation. Large amounts of background can make the important instructions harder to identify and maintain.
How do I know the fix worked?
Run a small task that previously failed, then inspect the actions and verification results. A restatement of the instructions is not a substitute for observing the expected behavior.