iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
When Claude Code seems to ignore CLAUDE.md, first check which instruction files actually loaded with /context. Then verify the working directory, instruction-file selection, imports, and conflicting or vague rules. Even a correctly loaded file guides Claude’s behavior; it does not guarantee compliance.
1. Claude Code started in a different directory than you expected
Claude Code’s instruction loading depends on where the session starts and which files it works with. At session start, it loads CLAUDE.md and CLAUDE.local.md files in the current working directory and its ancestor directories. Instruction files in child directories are discovered but load on demand when Claude works with files beneath them. Starting at a repository root therefore does not mean every nested instruction file is already in context.
![Claude AI for Beginners Bible: [5 in 1] The Ultimate Guide to Automate Your Work, Save Hours Every Week, and Use AI for Real-World Results](https://m.media-amazon.com/images/I/415+fSJacsL._SL160_.jpg)
Instruction scope also matters. A project file can be at ./CLAUDE.md or ./.claude/CLAUDE.md; user-level instructions can be at ~/.claude/CLAUDE.md, while managed instructions can apply organization-wide. These locations are not interchangeable: copying guidance between them can introduce duplicate or conflicting instructions. See Anthropic’s memory documentation for the loading model.
Check the session’s actual context
- Run
/contextand inspect the Memory files list for the expected file. - Check the shell’s current directory. If the session started in the wrong location, start Claude Code from the intended project directory.
- Run
/memoryto locate memory files. If the missing file is nested, ask Claude to work with files in that subtree so its instructions can load on demand.
2. Claude Code selected CLAUDE.md instead of AGENTS.md
Claude Code can use AGENTS.md as project instructions, but it is not always the default. If an AGENTS.md exists and there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it, Claude Code can load the AGENTS.md. If a CLAUDE file exists in that project path, the default is to load the CLAUDE files instead. The Project instructions option in /config, the session configuration, and the Claude Code version can affect what happens.
#1 Best Overall
Anthropic’s current documentation says direct AGENTS.md reading requires Claude Code v2.1.277 or later; earlier releases have additional compatibility conditions. Consult the current memory documentation if your version or configuration differs.
Diagnose an AGENTS.md mismatch
- Look for
CLAUDE.md,.claude/CLAUDE.md, andCLAUDE.local.mdin the working directory and its ancestors. - Open
/configand check the Project instructions setting. - Confirm the Claude Code version and whether it supports the expected AGENTS.md behavior.
3. An added directory is accessible, but its instructions are not loaded
The --add-dir option gives Claude Code access to another directory. That access does not automatically load instruction files from the added directory. For that, Anthropic documents the environment variable CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. Check this when shared instructions live outside the main working directory; details are in the memory documentation.
Rank #2
4. An import is malformed, skipped, or awaiting approval
A CLAUDE.md file can import another file with @path/to/import. The path is resolved relative to the file containing the import, not necessarily the project root. A path containing spaces needs escaped spaces; putting the path in quotes does not import it. Imports inside Markdown code spans or fenced code blocks are skipped.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsProject-level imports that resolve outside the working directory trigger an approval dialog. If you decline, the import remains disabled. Use /memory to locate the files, then check the exact import syntax and whether approval was granted. Imports do not reduce context use: imported content counts toward the context just like content in the main file. See Anthropic’s import and memory guidance.
Import checklist
- Confirm the import begins with
@and points to the intended file. - Resolve the path from the file that contains the import.
- Escape spaces in paths; do not rely on quotes.
- Make sure the import is not inside backticks or a fenced code block.
- Approve an external project-level import when prompted.
- Remember that imported text still consumes context.
5. The file loaded, but the instructions are vague, conflicting, or unenforceable
Anthropic puts the limitation plainly: “Claude treats them as context, not enforced configuration.” Its documentation says CLAUDE.md is delivered as a user message after the system prompt, so strict compliance is not guaranteed, especially when directions are vague or conflict. A rule such as “format code nicely” is less actionable than naming the indentation style or exact test command to use.
Review instructions across ancestor, project, local, and rule files for contradictions. Keep each file focused: Anthropic recommends targeting fewer than 200 lines per CLAUDE.md. Longer files consume more context and can reduce adherence. Put guidance that applies only to particular paths in path-scoped .claude/rules/ files. Splitting a large file with imports can improve organization, but it does not shrink the imported content’s context cost. Details are in Anthropic’s memory documentation and settings documentation.
Use the right mechanism for the requirement
- Behavioral guidance: Use concise, specific instructions for preferences and project conventions.
- Configuration: Use settings for options whose scope and effect are defined by Claude Code’s configuration system. User, shared-project, project-local, and managed settings have different audiences; check
/configor the documented confirmation steps to establish what took effect. - Required lifecycle actions: Use a hook for actions that must happen at a fixed point, such as before every commit. Test the hook rather than relying on prose instructions.
- System-prompt-level instructions: Anthropic documents
/append-system-promptas an option, particularly for scripts or automation that need instructions at that level.
Run this diagnostic sequence
- Run
/contextand confirm the expected file appears under Memory files. Remember that nested files may load only when Claude works in their subtree. - Run
/memoryto locate the relevant files. Check the current working directory and ancestor paths if the file is missing. - If you expected
AGENTS.mdto load, inspect CLAUDE files in the project path, the Project instructions setting in/config, and your Claude Code version. - Check imports for path resolution, escaped spaces, code fences or backticks, and any declined approval prompt.
- Make rules concrete, remove contradictions, and move path-specific directions to
.claude/rules/. The/doctor prompt-auditcommand can check for outdated or contradictory instruction files; Anthropic says it requires Claude Code v2.1.283 or later. - For behavior required at a specific lifecycle event, configure and test a hook.
Anthropic’s documentation does not provide a measured rate for how often Claude Code ignores CLAUDE.md. The documented 200-line recommendation is guidance, not a compliance benchmark; the documentation also states that a file larger than 4 MiB is skipped. Check the current memory documentation for limits and version details, which can change.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
