Why Claude Code Ignores Your CLAUDE.md: Check File Location, Scope and Conflicts

Nested CLAUDE.md files help a monorepo keep local guidance close to the code it governs. They can also create confusion when a general rule, a team rule, and a personal preference all appear in the same session. The practical task is to make scope visible, keep instructions specific, and check which files Claude Code has loaded before you trust the result.

What Claude Code loads

Claude Code reads CLAUDE.md and CLAUDE.local.md files from the current directory and its parent directories. A project file can sit at the repository root or in .claude/CLAUDE.md. A local file is intended for personal project preferences and should remain out of version control. Files above the working directory load at startup. Files below it load when Claude reads files in those directories; merely placing a file in a nested folder does not make it part of every session.

A nested file is useful when a part of the repository has rules that do not apply everywhere. A frontend package may have component conventions; a service package may have API and testing rules.

Treat the files as context that guides Claude. They are not a hard enforcement layer. If an action must be blocked regardless of what Claude decides, use an appropriate permission or hook control. The Claude Code memory documentation explains this distinction and the loading order.

An illustrative monorepo

Consider this repository:

acme-platform/
├── CLAUDE.md
├── .claude/
│   └── rules/
│       └── typescript.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md
│   └── admin/
└── services/
    └── billing/
        └── CLAUDE.md

The root file might say that all packages use the shared test command, never place credentials in source, and record API changes in the changelog. The apps/web/CLAUDE.md file might describe its routing and component conventions. The billing file might add rules for idempotency, decimal money values, and tests around retries.

If you start Claude Code in apps/web/, the root guidance and web guidance are relevant. If you start in services/billing/, the billing guidance is relevant instead. A rule that says “use the shared test command” should identify the command and package scope. “Test thoroughly” leaves too much room for interpretation.

The same structure becomes risky when documents disagree. For example, the root file may require a lockfile update while a nested file says to avoid lockfile changes. Keep one owner for each rule, remove stale text, and make exceptions explicit.

A practical debugging sequence

When Claude seems to ignore a rule, check:

1. Confirm the working directory. A file in a sibling package does not apply merely because it exists in the repository.
2. Check CLAUDE.md, CLAUDE.local.md, and .claude/rules/ in each relevant directory. Look for duplicate rules and wording that can be read in two ways.
3. Use /context in the session to check which memory files Claude Code reports as loaded.
4. Check imported instructions as well as the main file. A conflicting rule can be hidden in a referenced document.
5. Ask Claude to restate the applicable rule before it edits. Correct the instruction if the restatement is wrong.
6. Run the relevant checks yourself. Guidance can improve behaviour, but a test, linter, or review is the evidence that the code meets the rule.

A small test plan

For the illustrative monorepo, create three harmless test tasks:

• Ask for a web component change and check whether the response names the web rules and the shared test command.
• Ask for a billing retry change and inspect whether the response discusses idempotency and money handling.
• Ask for a change that touches both packages and check whether Claude identifies both scopes instead of applying the billing rules to the web package.

Record the working directory, files Claude says it loaded, proposed files, and checks that actually ran. This test plan is a way to evaluate instruction scope. It is not a claim that these tests have been executed in this article.

Questions readers usually ask

Does every package need its own CLAUDE.md?

No. Add a nested file when the package has stable rules that would otherwise be repeated or misunderstood. A small package with no distinct conventions may be clearer with the root guidance alone.

Does a nested CLAUDE.md replace the root instructions?

The files are concatenated into context in root-to-working-directory order. A closer file supplies more specific guidance, but it does not magically resolve a contradiction. Write the exception plainly or remove the older rule.

Can CLAUDE.md enforce a security restriction?

No. It guides Claude’s behaviour as context. Use permissions, settings, or hooks for controls that must be enforced independently of model judgement.

How can Timo help me practise Claude Code configuration decisions?

Use the original questions and worked explanations in Timo's Developer Foundations and Architect Foundations previews to practise reasoning about the constraints in a scenario. Combine that practice with the repository checks above.

If you also need a route to official certification registration, Timo is run by Amotion AI, a registered member of the Claude Partner Network. Timo reviews applications from individuals who need partner access and explains the agreement and account setup for accepted applicants. The registration guide describes that separate process. Partner access is available through Timo. Anthropic sets the official exam requirements and awards the credential.