What is CLAUDE.md?
CLAUDE.md is a Markdown file that Claude Code loads at the start of every session to give it standing instructions: build and test commands, conventions, project layout, rules to always follow. It can live at the project root, in your home directory, or in a managed location for an organization, and the files stack rather than replace each other.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
Run /init in a project and Claude Code drafts a CLAUDE.md from what it finds: build commands, test instructions, conventions.
At launch, Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it, plus ~/.claude/CLAUDE.md.
Files are concatenated from broadest to most specific. Nothing is overridden, so a contradiction between two files is a bug to fix.
A CLAUDE.md in a subdirectory loads only once Claude touches a file there. @path imports pull other files in, up to four hops deep.
Keep it under about 200 lines. Move topic rules into .claude/rules/ with a paths field so they load only for matching files.
Where CLAUDE.md files live
There are four places, and Claude Code loads them in this order. A managed file, deployed by an organization to a fixed system path, comes first and cannot be excluded by a developer. Your own ~/.claude/CLAUDE.md holds preferences that follow you into every project. The project file, ./CLAUDE.md or ./.claude/CLAUDE.md, is the one you commit and share. CLAUDE.local.md sits beside it for notes that are yours alone and belongs in .gitignore. Broad to specific, so the project's instructions appear after your personal ones, and within a directory the local file is appended last.
Two details trip people up. Claude Code walks up from your working directory and loads every CLAUDE.md it finds above it, so launching inside a subfolder of a monorepo still picks up the root file. And a CLAUDE.md in a subdirectory below you is not loaded at launch; it loads the first time Claude reads or edits a file in that folder.
Example: splitting a long file
A project file grows past 200 lines and you notice Claude following it less reliably. The docs recommend that limit and explain why: a longer file costs context and dilutes adherence. The fix is .claude/rules/, a folder of topic files such as testing.md or api-design.md. A rule without frontmatter loads every session like the main file. A rule with a paths field, say src/api/**/*.ts, loads only when Claude works on a matching file. The root CLAUDE.md shrinks to what is true everywhere, and the API rules show up when they are relevant.
Imports help organize but do not save context. @docs/git-workflow.md pulls that file in alongside the one importing it, up to four hops deep. If the path leaves the project, Claude Code asks you once before loading it, because someone else may have committed that line.
Why it matters
Every session starts with an empty context window. Whatever you explained last time is gone unless it is written down somewhere Claude reads automatically. The docs give four signals that something belongs in the file: Claude makes the same mistake twice, a review catches something it should have known, you type the same correction you typed last session, or a new teammate would need the same context. That last one is the test. CLAUDE.md is the onboarding doc for a colleague who forgets everything overnight.
The pattern reaches beyond a repository. When several people's agents edit one Intraface board, its collab.md carries the board's house rules and design language, and each agent reads it when it pulls, regardless of which tool it is. Standing instructions belong next to the thing being changed.
Common mistakes
- Treating it as configuration. CLAUDE.md is delivered as context, and Claude may not follow a vague or conflicting line. To block an action outright, use a permission deny rule or a PreToolUse hook; to run something at a fixed point, use a hook.
- Vague rules. "Use 2-space indentation" works. "Format code properly" does not.
- Contradictions. Two files that disagree leave Claude to pick one. User rules and project rules do not override each other either.
- Adding CLAUDE.local.md to an AGENTS.md repo. Any CLAUDE.md on the path, including the local one, stops Claude from reading AGENTS.md unless you change the Project instructions setting.
- Symlinking on Windows. A committed symlink checks out as a one-line text file unless core.symlinks is on. Use an
@AGENTS.mdimport instead.
FAQ
- What is the difference between CLAUDE.md and CLAUDE.local.md?
- CLAUDE.md is committed and shared with the team. CLAUDE.local.md sits in the same folder, is meant for your own notes such as sandbox URLs or preferred test data, and belongs in .gitignore. Both load at launch, the local one after the shared one.
- Is a CLAUDE.md file enforced?
- No. Claude Code delivers it as context after the system prompt, and Claude tries to follow it. Permission rules and PreToolUse hooks are enforced by the client whatever Claude decides, so use those for anything that must hold.
- Can a CLAUDE.md file import AGENTS.md?
- Yes. Put @AGENTS.md on its own line and Claude reads that file first, then the rest of CLAUDE.md. Use this when a project has both files or when you want Claude-specific additions below the shared ones.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.