Fix CLAUDE.md Not Working

Match the symptom

• `/context` does not list the expected CLAUDE.md file.
• A root file loads but a nested file or path rule does not.
• An `@` import does not contribute its expected content.
• Claude can repeat a rule but applies it inconsistently.

First checks

Collect evidence before changing configuration

/context
/memory
/doctor

claude doctor

Diagnosis 1

Check what actually loaded

Use Claude Code's context view before renaming or duplicating files.

1. Look under Memory files for the expected project and local entries.
2. Confirm the displayed path is the file you edited.
3. Start a new session after changing startup-level instructions.

/context
/memory

Decision: If the file is absent, fix discovery. If present, move to conflict and specificity checks.

Diagnosis 2

Correct the file location and scope

Shared project guidance belongs in `./CLAUDE.md` or `./.claude/CLAUDE.md`; private project guidance belongs in `CLAUDE.local.md`.

1. Confirm the session started inside the intended project hierarchy.
2. Remember that subdirectory CLAUDE.md files load on demand when Claude reads files there.
3. For conditional rules, verify the file is under `.claude/rules/` and its `paths` pattern matches.

Decision: Read one known matching file, then rerun `/context` to distinguish on-demand loading from a broken rule.

Diagnosis 3

Debug imports without duplicating content

An unquoted `@path` imports content relative to the CLAUDE.md containing it; code-formatted paths are only mentioned.

1. Use `@AGENTS.md` outside backticks to import shared guidance.
2. Check that the relative path resolves from the instruction file, not the shell working directory.
3. Approve external imports when Claude Code presents the trust dialog.
4. Reduce deep or unnecessary imports that consume startup context.

Decision: Use `/context` to confirm the parent CLAUDE.md loaded, then ask Claude to summarize the imported rule specifically.

Diagnosis 4

Remove conflicts and vague instructions

CLAUDE.md is contextual guidance rather than enforced configuration. Contradictory or broad statements reduce reliable application.

1. Review user, project, local, nested, and rules files together.
2. Replace ‘follow best practices’ with an exact action and evidence.
3. Move hard prohibitions into permissions or hooks.
4. Keep each CLAUDE.md concise; Anthropic recommends targeting under 200 lines.

/doctor

Decision: Test one rewritten rule on a small task, then inspect the diff and command output rather than relying on Claude's summary.

If it still fails, send this evidence

A useful support request is reproducible and does not expose credentials.

• Claude Code version and working directory.
• The Memory files portion of `/context`, with personal paths redacted.
• Relevant CLAUDE.md and rule locations, including imports.
• Output from `/doctor` or `claude doctor` and one minimal reproduction.