AI Tools
Tutorial7 minNovember 11, 2026By AIGCDev

Claude Code Ignoring CLAUDE.md? How to Diagnose Loading and Instruction Issues

When Claude Code doesn't follow CLAUDE.md, don't assume the file failed to load. It may be outside the current session's loading scope, or it may have loaded but contain vague or conflicting instructions, or the model may not have followed them. Check the loading record first, then the instructions and actual behavior.

This guide covers local Claude Code sessions and is based on the official memory documentation checked on November 11, 2026. Commands and interfaces can change between versions. The diagnostic examples have not been tested end to end by AIGCDev; operations involving the model may use your allowance. Work in a disposable project copy and record the version, launch directory, instruction text, and observations. Avoid using sensitive project data in the test.

For an MCP server that will not connect or whose tools are unavailable, see the Claude Code MCP troubleshooting guide.

First, check when the file should load

In the terminal where you launch Claude Code, check the working directory and version:

pwd
claude --version

A project instruction file is normally CLAUDE.md or .claude/CLAUDE.md in the launch directory. CLAUDE.md and CLAUDE.local.md in the working directory and its ancestors load at startup. Files in subdirectories load on demand when Claude reads, writes, or edits another file in that subdirectory. Discovered instructions are combined in context; a later file does not automatically override an earlier one. See the official loading rules.

In the session, enter /context all and check Memory files for paths that should load at startup. If the target is listed, move on to its content and behavior. If it is missing, check the launch directory, path, and exclusions below. You can browse and edit memory files with /memory, but its list also includes locations for files that do not yet exist, so appearing there alone does not prove a file loaded.

For a subdirectory file, absence from the startup list is not enough to conclude it failed. Create or confirm the subdirectory's CLAUDE.md from the shell, then ask Claude in the session to read another file in that subdirectory. Look for a Loaded line with the target path in the terminal. If it still does not appear, check the actual path accessed, working directory, and exclusions. If the terminal did not retain the loading information, the official InstructionsLoaded hook can record which files loaded, when, and why; read its scope before configuring it.

If it didn't load: check scope, exclusions, and imports

A file's presence on disk does not establish that Claude received it. Check the relevant conditions:

  • Different working directory or worktree: confirm where the session started. A personal CLAUDE.local.md may exist in only one worktree.
  • Exclusions or launch options: inspect claudeMdExcludes, --setting-sources in the launch arguments, and Project instructions in the session's /config. managed-only excludes project, local, and user CLAUDE.md files at startup, although subdirectory files can still load on demand. Do not blindly override organization-managed configuration; consult settings scope and precedence to inspect effective settings.
  • Additional directories: --add-dir grants file access but does not load the directory's CLAUDE.md by default. If needed, check the environment variable and limitations in the additional directories documentation.
  • @ imports: relative paths resolve from the importing file. References in inline code or fenced code blocks do not trigger imports. A project-level import outside the working directory requires approval on first encounter and does not load if declined. Check the target, syntax, and approval state, not just the main file. See import rules.
  • File size: the official documentation says files loaded at startup are skipped if they exceed 4 MiB; on-demand files have smaller separate limits described below. A length warning at startup or in /status is worth investigating, but exceeding the recommended line count does not mean the whole file failed to load.

After correcting a problem, start a new session in the same directory and repeat the loading check. If the path is still missing, retain the version, launch method, paths, and relevant settings for the official troubleshooting guidance. Do not treat the file's presence on disk as proof of loading.

If it loaded: check conflicts, length, and wording

List the user, project, and subdirectory instructions and .claude/rules/ applicable to this task. Look for contradictory requirements and check whether the current request itself conflicts with a project instruction. Context order does not guarantee that the closest directory wins: the documentation says Claude may choose either conflicting instruction. Have the maintainer decide the intended rule, then remove or rewrite the conflict.

Rewrite instructions in terms of observable actions. This is an illustrative rule, to be replaced with your project's actual convention:

After changing TypeScript files, run bun run lint; if it cannot run, report why.

This is easier to check than “ensure code quality”: inspect the tool or terminal record for the command and its result, including any reason it could not run. Asking Claude to repeat the rule does not establish compliance. Do not copy the command if your project does not have it.

The documentation recommends keeping each CLAUDE.md under 200 lines; this is guidance, not a compliance threshold. Imports can organize material, but their content still enters context. For on-demand subdirectory CLAUDE.md files and path-scoped rules, the current documentation also specifies a per-file character limit. Above it, Claude initially receives only the beginning and a note to read the rest. The limit depends on the context window and model and did not apply before v2.1.309. Use wc -m path/to/CLAUDE.md and check the version and applicable limit. A path in a loading record does not prove that instructions at the end were included in context.

Does it happen only in a long session or after compaction?

Record whether the problem appeared before or after /compact, then compare the same instruction in a fresh session. According to the documentation, the project-root CLAUDE.md is reread from disk and reinjected after compaction; subdirectory CLAUDE.md files and rules with paths frontmatter load again on demand. Instructions given only in conversation may not remain in the compacted context. See what happens after compaction.

If a subdirectory instruction seems lost after compaction, first have Claude read a relevant file in that subdirectory, check the loading record, and then observe the task result. For a path-scoped rule, check whether the accessed file matches its paths. If both the fresh and compacted sessions show loading records but behave differently, record the difference as a session-state clue; it does not by itself establish compaction as the cause.

Confirm behavior, not just a repeated instruction

In a disposable copy, choose one low-risk rule with an observable result and a small task. For example, if the rule requires running the project's existing lint command after an edit, ask Claude for a small change containing no sensitive data, then inspect the command record and exit result. Record the instruction, prompt, version, loading record, and actual action. Change one condition at a time when retrying, such as resolving a conflict and repeating the same task in a fresh session. This is a diagnostic example, not an AIGCDev test result.

  • A file that should load has no loading record: return to its path, scope, and exclusions.
  • The rule is in the truncated part of an on-demand file: shorten the file or reorganize the rule, then check loading again.
  • The rule entered context but the action didn't happen: inspect conflicts and wording. If it still fails, record that instance as noncompliance, not proof of a loading failure. One success or failure does not establish long-term reliability.

CLAUDE.md supplies context to the model; it is not an enforcement mechanism. If an action must be restricted or run at a particular event, evaluate permissions and hooks, their scope, and independently verify the configuration. Do not treat written instructions as a security boundary.

claude-codeai-codingtroubleshooting