← Blog · 2026-10-18

CLAUDE.md or .claude/rules Not Working? 12 Causes and Fixes

Shortcut: paste your rule files into our free Claude Code rules checker. It shows which rules load at launch, which load only for matching files and which never load, tests file paths against your paths: globs, and lints a CLAUDE.md's imports and length. It runs in your browser.

Claude Code reads two kinds of instruction files:

When an instruction doesn't seem to apply, the file either didn't load, loaded at a different moment than you expected, or loaded and Claude didn't follow it. Work through the checks below in order.

If the problem is notes Claude saved for itself (auto memory, MEMORY.md) rather than files you wrote, see Claude Code auto memory not working? 12 causes and fixes.

First: see what loaded

Run /context in a session and look at the list under Memory files. If a file is missing there, Claude can't see it. Two exceptions: a subfolder's CLAUDE.md and a rule with paths don't appear at launch, because they load later. When one loads, a one-line Loaded notice with its path appears in the terminal.

For a full log, add an InstructionsLoaded hook. It fires for every CLAUDE.md and rule file as it loads and receives the file_path, a load_reason (session_start, nested_traversal, path_glob_match, include or compact) and, for lazy loads, the trigger_file_path that caused it. Our hooks generator writes the settings block for you.

The file never loads: 6 causes

1. It's in the wrong place or has the wrong name. A project file must be ./CLAUDE.md or ./.claude/CLAUDE.md in the folder you start Claude Code in or a folder above it. Rules must be .md files inside .claude/rules/ (subfolders such as .claude/rules/frontend/ are fine) or ~/.claude/rules/. Claude Code doesn't read Cursor's .cursor/rules/*.mdc or Copilot's .github/copilot-instructions.md as rules. Fix: move the file. Running /init can fold Cursor and Copilot rules into a generated CLAUDE.md.
2. You edited it during the session. Your project-root and user CLAUDE.md files are read once at session start and held in memory, so edits don't apply to the running session. Fix: run /clear or /compact, or restart. Subfolder CLAUDE.md files and path-scoped rules are different: editing one before it loads does take effect, but once it has loaded, a later edit doesn't change what's already in the conversation.
3. An AGENTS.md and a CLAUDE.md compete. By default Claude reads AGENTS.md only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it, so adding a CLAUDE.local.md for yourself can stop Claude reading the team's AGENTS.md. Reading AGENTS.md directly needs v2.1.277 or later. Fix: in /config, set Project instructions to claude-md-and-agents-md, or put @AGENTS.md at the top of your CLAUDE.md.
4. Something excludes it. Check four places. claudeMdExcludes in any settings file skips CLAUDE.md and rules files whose absolute path matches its globs. A Read deny rule that covers the file withholds it, with an Instruction file not loaded (a Read deny rule covers it) notice, and so does permissions.blockReadsOutsideWorkingDirectories for a file outside your working directories. Project rules are skipped when you start with --setting-sources that leaves out project. And Project instructions set to managed-only leaves out your own CLAUDE.md files and rules at launch. Fix: narrow the exclusion or deny rule, then start a new session.
5. The folder came from --add-dir. Claude can read and edit files in an added directory, but its CLAUDE.md files aren't loaded by default. Fix: set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. That loads the added folder's CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md and CLAUDE.local.md.
6. It's a symlink to somewhere outside the project. A .claude/rules/ link whose target is outside your working directory is treated like an external import: it waits for the approval dialog at the start of a session, and after approval only linked rules without paths load. A link to a network path (a UNC share, /net or /Network) isn't followed at all. Fix: keep shared personal rules in ~/.claude/rules/, which needs no approval, or copy the file into the project.

A path-scoped rule loads at the wrong time: 4 causes

7. The frontmatter doesn't parse, so the rule loads everywhere. If the YAML between the --- markers doesn't parse, Claude Code ignores the frontmatter and loads the rule as if it had no paths. The usual culprit is an unquoted glob: paths: **/*.ts is invalid YAML because * starts an alias, and paths: {src,lib}/**/*.ts reads as a mapping. A backslash inside double quotes, as in "photos \[2024/**", is an invalid escape. Fix: quote every pattern, and use single quotes for patterns with a backslash. Run claude --debug to see the parse error.

---
paths:
  - "src/api/**/*.{ts,tsx}"
  - 'photos \[2024/**'
---

8. The field is called something else. paths is the only field Claude Code reads from a rule, and any other field is ignored without an error. A file converted from Cursor with globs: and alwaysApply:, or from Copilot with applyTo:, has no paths, so it loads in every session. Fix: rename the field to lowercase paths. It accepts a YAML list or a comma-separated string.
9. The pattern never matches. Patterns are globs: * stays inside one folder and ** crosses folders. So *.md matches Markdown files in the project root only (use **/*.md for every folder), and src/api with no wildcard matches only a file with exactly that path (use src/api/**). A [ that doesn't form a bracket expression, as in photos [2024/**, makes that pattern match nothing; escape it as \[. Brace groups multiply: a rule's whole paths list shares a budget of 1,000 expanded patterns, and a pattern past the budget is used unexpanded and matches nothing. Also check what triggers the load: the Read, Write or Edit tool on a matching file, or a single-file cat or head. A search across files doesn't. Fix: type real file paths into the rules checker to see which pattern, if any, matches.
10. It was there, then /compact dropped it. After compaction, Claude re-reads the project-root CLAUDE.md and rules without paths from disk. Path-scoped rules and subfolder CLAUDE.md files were part of the conversation, so they're summarized away and come back only when a matching file is opened again. Fix: if a rule must survive compaction, remove its paths frontmatter or move it into the project-root CLAUDE.md.

It loaded, but Claude doesn't follow it: 2 causes

11. The file is long, vague or contradicts another one. CLAUDE.md content reaches Claude as a user message after the system prompt, so it's guidance, not enforced configuration. Anthropic's target is under 200 lines per CLAUDE.md; longer files cost more context and reduce adherence, and Claude Code warns at startup and in /status when a file is over the recommended length. A file over 4 MiB is skipped. If two files disagree, including a user rule and a project rule, Claude may follow either one. Fix: make instructions concrete ("Use 2-space indentation", not "format code nicely"), move instructions that only matter for some files into path-scoped rules, and run /doctor prompt-audit (v2.1.283 or later) to find outdated and conflicting instructions.
12. An @import didn't resolve. Imports load at launch with the file that references them, up to four hops deep, and relative paths resolve from that file's folder, not your working directory. A path ends at the first space unless you put a backslash before it (@Design\ Docs/api.md), a path in quotes isn't imported at all, and @path inside backticks or a code block stays literal. In a project file, an import outside your working directory triggers an approval dialog the first time; if you declined it, those imports stay disabled. Fix: paste the file into the CLAUDE.md section of the rules checker to list each import the way Claude Code reads it.

When it has to happen every time

If an instruction must run at a fixed moment, such as before every commit or after each edit, make it a hook: hooks run as shell commands and apply regardless of what Claude decides. For something that must never happen, use a permissions.deny rule (permissions builder). If your CLAUDE.md sets commit or pull request rules, turn off Claude Code's built-in git guidance with the includeGitInstructions setting and set the attribution text with attribution, so the two don't compete. And for instructions you want at the system-prompt level in scripts, pass --append-system-prompt at launch.

Quick reference

Facts on this page come from Anthropic's memory and rules, debug your configuration, prompt caching, context window, errors and hooks docs. Not affiliated with Anthropic.