Where to Put Your CLAUDE.md File (Location Guide)

The short version

Put a CLAUDE.md in your project root for project-specific instructions, and a ~/.claude/CLAUDE.md for instructions you want everywhere. Claude reads both and combines them — the project file layers on top of the global one. If Claude isn't picking up your rules, 90% of the time the file is in the wrong folder or has the wrong name.

The three places Claude looks

1. Project root — ./CLAUDE.md. The main one. A file named exactly CLAUDE.md in your project's top folder, read as standing context for that project; home for stack, conventions, project-specific boundaries.
2. Global — ~/.claude/CLAUDE.md. Applies to every project on your machine; home for durable personal preferences and your universal "never do this" list. Read in addition to the project file.
3. Nested — ./packages/api/CLAUDE.md. Deeper in the tree; picked up on top of root + global when Claude works on files in that subtree. Give a package its own rules without bloating the top-level file.

How the files combine

Additive, not either/or: global → project root → nested, more specific layering on top. Keep universal rules global, project rules in the root, nested only when a subdirectory needs different behavior. Everything stacked is read EVERY conversation, so total length is a real cost — working ceiling under ~2,000 tokens. See how long CLAUDE.md should be and optimize CLAUDE.md.

Monorepos and multiple projects

Shared repo-wide rules in the root CLAUDE.md; each package gets its own nested CLAUDE.md for its unique stack/conventions. Don't cram every package's rules into one giant root file — that's the bloat that makes a CLAUDE.md stop working.

Cowork and the Claude apps

CLAUDE.md isn't only a coding-tool feature. In Cowork mode and the Claude apps it's working memory for non-code work — a job search, consulting clients, your inbox. Same location logic: global for how you work in general, per-project for specifics. See CLAUDE.md in Cowork and what is a CLAUDE.md file.

Common location mistakes

• Wrong filename. Must be CLAUDE.md — not claude.md, Claude.MD, CLAUDE.markdown, or CLAUDE.txt. Capitalization matters on most systems.
• Wrong folder. A file in a random subfolder won't be read for top-level work.
• One bloated global file. Project-specific rules in ~/.claude/CLAUDE.md apply everywhere and eat your token budget on every project.
• Forgetting it's combined. If a rule "isn't working," check whether a global file contradicts your project file — both are loaded.

If the file is placed correctly and still ignored, the problem is usually the content — see CLAUDE.md ignored.

The fastest way to get it right

Describe your role and project in CoworKit's free Builder — it generates a clean, correctly-scoped CLAUDE.md and gives it a Claude Fluency Score across clarity, specificity, format, voice, boundaries, and token count, so you know it fits under budget before you drop it in your project root. Already running one that's ignored? Paste a real chat into Session Review.

FAQ

Where does CLAUDE.md go?

In your project's root folder as CLAUDE.md for project-specific instructions, and/or in ~/.claude/CLAUDE.md for instructions that apply to every project. Claude reads both and combines them.

What's the difference between global and project CLAUDE.md?

Global (~/.claude/CLAUDE.md) applies to all projects; project (./CLAUDE.md) applies only to that project and layers on top of the global one.

Can I have more than one CLAUDE.md?

Yes. A global file, a project-root file, and nested files in subdirectories all combine, with more specific files layering on top.

Why isn't Claude reading my CLAUDE.md?

Most common: wrong filename (must be exactly CLAUDE.md) or wrong location (project root or ~/.claude/). If the path is right, the issue is usually the content.

Does CLAUDE.md location matter in Cowork mode?

Yes — same logic. A global file sets how you work in general; a per-project file holds the specifics.