← All guides

how does claude code use the claude md file

How Does Claude Code Use the Claude MD File? Load Order

By Neo Zino - builder of ClockedCode·November 2, 2026·11 min read

Claude Code loads CLAUDE.md at session start as context, not enforced rules. See the load order, where files live, and why it gets ignored.

TL;DR: So, how does Claude Code use the Claude MD file? It reads CLAUDE.md at the start of every session and places it in context as a user message after the system prompt (institute.sfeir.com). It is context, not enforced configuration, so a short file holding only non-obvious rules is followed far better than a long one. Keep it under 200 lines.

What is the CLAUDE.md file, and what does Claude Code do with it?

Prerequisites: Claude Code installed and the claude command working in your terminal, plus a project folder you can open it in. If you only need a starting file, the Claude MD Generator produces one in about 30 seconds.

CLAUDE.md is a Markdown file where you write persistent, project-specific instructions that Claude Code reads at the start of every development session (readme.com). Without it, each new session starts from scratch and you lose team conventions, critical file paths and workflow preferences (institute.sfeir.com).

That is the whole change. The file does not add a feature or a new tool. It removes the need to re-explain your test command, your folder layout or your "never touch this directory" rule every morning. One commenter on Hacker News put the audience split well: READMEs are written for people, CLAUDE.md files are written for coding assistants (news.ycombinator.com). Write it for the assistant. Short imperatives beat explanations.

When and how does Claude Code load it into the conversation?

Here is the lifecycle, with what you should see at each step.

1. Start a session. Run claude inside your project folder. Claude Code looks for memory files and detects your CLAUDE.md. Expected result: no prompt from you is needed, the lookup happens before your first message.
2. The file is loaded into the context window. It is delivered as a user message after the system prompt, before any interaction (institute.sfeir.com). Expected result: Claude can act on your rules in the very first reply.
3. Check what was loaded. Run /memory. It lists the loaded memory files, opens them in your editor and lets you toggle auto memory (institute.sfeir.com). Expected result: you see your project file, and your user file if you have one. If a file you expected is missing, it is not in context, and no wording tweak will help.
4. Work normally. The file now sits in context like any other message. It costs tokens on every session, which is why length matters later in this guide.

The key detail is step 2. Because the content arrives as a message and not as a setting, Claude weighs it against everything else in the conversation. That explains most "it ignored my rule" complaints.

Where can a CLAUDE.md live, and how are several files combined?

The usual home is the repository root, but a file can also exist at the personal or organization level (readme.com). The project version can be ./CLAUDE.md or ./.claude/CLAUDE.md, and version control carries it to the whole team. The user-level file belongs to your machine and is never versioned. For private notes on one project there is CLAUDE.local.md, and an organization can add a managed-policy file (institute.sfeir.com).

When more than one exists, Claude Code stacks them into context ordered from broadest to most specific. Organization and user files arrive first, and the narrower project file comes after.

Do not treat "more specific wins" as a guarantee. These files are context, not enforced settings, and when two instructions clash, Claude Code settles it non-deterministically with no strict ranking between levels (institute.sfeir.com). The practical rule: never put contradictory advice in two files and hope the right one prevails. Give each rule exactly one home.

When this is the wrong choice: if you work alone on a single repo, skip the layering. One project file is enough, and a second file only adds a chance of conflict.

How do nested CLAUDE.md files and .claude/rules/ get pulled in?

Directory-specific context can go in a CLAUDE.md inside that directory instead of the main one. If you have a database layer with critical caveats, put them in src/persistence/CLAUDE.md, and Claude pulls that file in whenever it reads a file in that directory (news.ycombinator.com). The same commenter's example: when Claude wants to read tests/foo_test.py, it automatically pulls in tests/CLAUDE.md if it exists.

The benefit is that your root file stays small. Database rules cost nothing in a session that never touches the database.

For topic-based splitting, use the rules folder. Each .md file in .claude/rules/ is loaded as an additional CLAUDE.md (institute.sfeir.com). That suits rules grouped by concern, such as testing, security or git workflow, instead of by folder. Our guide to Claude Code rules covers how to scope a rule to certain files with paths and which rules to leave out.

One dissenting view is worth knowing. A commenter advises going for skills first before littering a project with these config files everywhere (news.ycombinator.com). We would pick nested files for stable, always-relevant facts about a directory, and skills for multi-step procedures Claude should run on demand. If you are weighing the two, see Claude Code Skills vs Subagents.

Which file should a given rule go in?

Run each instruction through this list from top to bottom and stop at the first match.

• Is it a secret or API key? Keep it out of CLAUDE.md entirely and use environment variables. Files that get committed are an accidental-leak risk (institute.sfeir.com).
• Does it depend on a condition, like "if on the main branch, then..."? CLAUDE.md does not support complex conditional logic (institute.sfeir.com). Rewrite it as an unconditional rule, or enforce it with a hook such as those from the Hooks Preset Generator.
• Is it only about you, on every project? Put it in the user-level file, which is machine-specific and unversioned (institute.sfeir.com).
• Is it only about you, on this project? Put it in CLAUDE.local.md (institute.sfeir.com).
• Does the whole company need it? That is what the managed-policy file is for (institute.sfeir.com).
• Does it only matter inside one directory? Use a nested CLAUDE.md there (news.ycombinator.com).
• Is it one topic that deserves its own file? Use a file in .claude/rules/ (institute.sfeir.com).
• Does the whole team need it on every task? Put it in the project CLAUDE.md and commit it (institute.sfeir.com).

Whatever you choose, remember that none of these placements guarantees compliance. Loaded files are context, and conflicts resolve non-deterministically (institute.sfeir.com). Placement controls what Claude sees, not what it obeys.

What should you write in it so Claude actually follows it?

Brevity is the main lever. One source suggests staying under 200 lines, using clear Markdown headers, and covering only what the model cannot safely work out by itself (readme.com). Length costs you twice: a bloated file takes up more of the context window and tends to lower how well instructions are followed (institute.sfeir.com).

1. Open a blank CLAUDE.md at the repo root, or generate a draft and trim it. Expected result: a file with a few headers such as Commands, Conventions and Do Not Touch.
2. List only what Claude cannot infer. Your test command, a nonstandard build step, the reason a folder is off limits. Skip anything visible from reading the code. Expected result: each line would surprise a new teammate.
3. Point to the source of truth instead of copying it. An OpenAPI spec already defines endpoints and parameters, so the file should cover behavior, workflow rules and where the official spec lives (readme.com). Apply the same idea to any large reference.
4. Count the lines. If you are near 200, move directory-specific material into nested files. Expected result: the root file reads in one screen or two.
5. Commit it and review it with releases. Treat the file like code: keep it in Git and revisit it whenever behavior changes (readme.com). Expected result: the file shows up in pull request diffs, so stale rules get noticed.

For a concrete example, a four-line "Commands" section (install, dev, test, lint) does more work than a page of architecture prose, because Claude cannot guess your package manager reliably. If you want a starting draft, the CLAUDE.md generator produces one you can trim.

Why does Claude ignore or lose CLAUDE.md instructions, and what can you do?

Diagnose in this order.

The file is too long or too general. A Hacker News commenter argued that the more of the file that does not apply to the task at hand, the likelier Claude is to disregard it, and that long files often see Claude Code drop many directions (news.ycombinator.com). Fix: trim, then push area-specific content into nested files.

You cannot tell whether it is being followed. Use a canary. One user has Claude address him by a nickname at all times, and treats the nickname vanishing as the sign that the file has stopped steering the session (news.ycombinator.com). Add a harmless line like that, and the first time it disappears, you know.

The file was never loaded, or dropped mid-session. Another commenter described sessions that began without every CLAUDE.md, skill and command loaded, and cases where Claude lost them partway through (news.ycombinator.com). Their workaround is a /bootstrap command that tells Claude Code to re-read all system and project CLAUDE.md files, skills and commands. You can build the same thing with the Custom Commands Generator. Run /memory first to confirm what is actually loaded (institute.sfeir.com).

The rules contradict each other. Because conflicts resolve non-deterministically (institute.sfeir.com), audit your user, project and local files for overlapping advice.

The file is out of date. ReadMe's 2025 guidance warns that a stale file recreates the very problems it was meant to prevent, such as old authentication patterns and deprecated endpoints (readme.com). Delete rules that no longer apply.

When you need a guarantee: if a rule must hold every time, such as blocking edits to a file, do not rely on prose. Use hooks or permission settings, which are configuration and not context. Our settings guide explains which file wins when two disagree.

Frequently asked questions

What kind of files can Claude Code read?

For memory purposes, Claude Code loads Markdown files: CLAUDE.md, CLAUDE.local.md, nested CLAUDE.md files and each .md file in .claude/rules/. Beyond memory, it reads the files in your project as it works, and that is exactly when nested CLAUDE.md files get pulled in. Which files it may open or edit is governed by your permission settings.

How are you supposed to use the Claude code?

Install it, open a terminal in your project folder and run claude. Before your first real task, create a short CLAUDE.md with your commands and conventions, then run /memory to confirm it loaded. From there, grow the setup only when you notice yourself repeating an instruction, and move each repeated rule into the file where it belongs using the checklist above.

Your next action: open your current CLAUDE.md, count the lines, and move anything specific to one directory into a nested file.

Frequently asked questions

What kind of files can Claude Code read?

For memory purposes, Claude Code loads Markdown files: CLAUDE.md, CLAUDE.local.md, nested CLAUDE.md files and each .md file in .claude/rules/. Beyond memory, it reads the files in your project as it works, and that is exactly when nested CLAUDE.md files get pulled in. Which files it may open or edit is governed by your permission settings.

How are you supposed to use the Claude code?

Install it, open a terminal in your project folder and run claude. Before your first real task, create a short CLAUDE.md with your commands and conventions, then run /memory to confirm it loaded. From there, grow the setup only when you notice yourself repeating an instruction, and move each repeated rule into the file where it belongs using the checklist above.

Your next action: open your current CLAUDE.md, count the lines, and move anything specific to one directory into a nested file.