CLAUDE.md File: Locations, Examples and Best Practices
November 11, 2026 · 12 min read
CLAUDE.md File: What It Is, Where It Lives and How to Write One
A CLAUDE.md file is a plain Markdown file of standing instructions that Claude Code reads at the start of every session. It holds your build commands, code style and project quirks, so you stop repeating them in chat. Below you'll find where each file lives, how several files stack, a copyable example and the habits that make Claude follow it.
What Is a CLAUDE.md File?
Every Claude Code session starts with a fresh context window. Yesterday's conversation doesn't carry over, so anything Claude needs to know about your project has to be written down somewhere it will read again. Claude Code's auto memory keeps notes Claude writes for itself, while CLAUDE.md is the file you write.
The file is ordinary Markdown with headings and bullet lists, nothing more. If you're new to the format, our explainer on what a Markdown file is covers the .md basics. Claude Code finds the file by name and location, loads it into context and treats its contents as instructions from you.
Why Markdown rather than JSON or YAML? Headings and bullets are plain text with light structure, which people and language models both read easily. Our post on Markdown in AI tools explains why AI tools read and write it so often.
One distinction matters before anything else. The official Claude Code memory docs describe CLAUDE.md as context, not enforced configuration. Claude reads it and tries to follow it, but nothing stops it from ignoring a vague or contradictory line. Keep that in mind when you decide what goes in the file.
Where Does the CLAUDE.md File Go? Global, Project and Local Locations
You can keep instructions at four scopes. Each one has a fixed path, and Claude Code checks all of them. Here they are in load order, from broadest to most specific:
| Scope | Path | Who sees it |
|---|---|---|
| Managed policy | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md, Linux and WSL: /etc/claude-code/CLAUDE.md, Windows: C:\Program Files\ClaudeCode\CLAUDE.md | Every user on the machine |
| User (global) | ~/.claude/CLAUDE.md | Only you, in every project |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Your team, through Git |
| Local | ./CLAUDE.local.md | Only you, in this project |
The global CLAUDE.md file at ~/.claude/CLAUDE.md is where personal habits go, such as your preferred package manager or commit message style. The project file is the one you commit, so it should hold team conventions rather than personal taste.
CLAUDE.local.md is for things like your own sandbox URL or test account. Add it to .gitignore so it never lands in the repo. The managed policy file is for IT or platform teams pushing company-wide guidance through MDM or similar tools. Unlike the other scopes, developers can't skip it with the claudeMdExcludes setting covered below.
How Does Claude Code Use the CLAUDE.md File When There Are Several?
Claude Code doesn't pick one file and ignore the rest. It concatenates every file it finds, so a project rule sits alongside a user rule rather than replacing it. Nothing is overridden, which means two conflicting instructions leave Claude free to follow either one.
At launch, Claude Code walks from your working directory up to the filesystem root and loads each CLAUDE.md and CLAUDE.local.md it meets. Content is ordered from the root down, and within each folder the local file comes after the shared one. Files in subdirectories below where you started load later, on demand, the first time Claude reads, writes or edits a file in that folder.
The diagram reads top to bottom in the order the text reaches Claude. Here's how that plays out in a monorepo:
shop/
├── CLAUDE.md
├── CLAUDE.local.md
└── packages/
├── api/
│ └── CLAUDE.md
└── web/
└── CLAUDE.md
Start Claude Code in shop/packages/api and it loads shop/CLAUDE.md, shop/CLAUDE.local.md and shop/packages/api/CLAUDE.md straight away. The web file doesn't load, because it isn't above or below your working directory. Start in shop/ instead, and the api file waits until Claude opens something inside packages/api.
To see what actually loaded, run /context all in a session and look under Memory files. If another team's file keeps getting picked up in a large monorepo, the claudeMdExcludes setting skips it by path or glob. The project-root file also survives /compact, because Claude re-reads it from disk afterwards.
How to Create a CLAUDE.md File with /init
The quickest start is the /init command inside Claude Code. Claude analyzes your codebase and writes a starter file with the build commands, test instructions and conventions it can discover. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.
After that, you edit the file like any other text. Run /memory to list your CLAUDE.md and CLAUDE.local.md locations across user and project scopes, then pick one to open it in your editor. Picking a file that doesn't exist yet creates it. You can also tell Claude "add this to CLAUDE.md" during a session.
If you'd rather start outside a terminal, you can generate a CLAUDE.md in the browser. You describe the project in a form, and the tool renders CLAUDE.md, AGENTS.md, .cursorrules and .github/copilot-instructions.md from that one description. It doesn't read your repository, so it only knows what you type in. Whichever route you take, trim the result to what Claude can't work out from the code itself.
A CLAUDE.md File Example You Can Copy
Here's a starter for a small web app. It's under 30 lines and every bullet is specific enough to check:
# CLAUDE.md
Next.js storefront backed by a Postgres database.
## Commands
- `npm run dev` starts the dev server on port 3000
- `npm test` runs the unit tests
- `npm run lint` must pass before every commit
## Code style
- TypeScript strict mode, no `any`
- Use 2-space indentation
- API handlers live in `src/api/handlers/`
## Testing
- Put new tests next to the file they cover, named `*.test.ts`
- Integration tests need a local Postgres on port 5432
## Gotchas
- Never edit files in `src/generated/`; they're rebuilt on deploy
- Prices are stored in cents as integers
## More context
- Architecture notes: @docs/architecture.md
The summary line tells Claude what kind of project this is. The Commands section saves it from guessing script names, and Code style turns taste into rules it can verify. Gotchas holds the things that cost you an afternoon once. The last line is an import: Claude Code pulls docs/architecture.md into context alongside this file.
Try editing it below. Rewrite the commands and paths for your own project, and the live preview shows the heading and list structure Claude will read.
The @docs/architecture.md line is plain text in our editor's preview. Imports only resolve inside Claude Code. When you're happy with the draft, copy the text into a file named CLAUDE.md at your project root.
Importing Other Files with @path and Splitting Rules into .claude/rules/
Writing @path/to/file anywhere in a CLAUDE.md file pulls that file into context. Relative paths resolve from the file that contains the import, not from your working directory. Absolute paths and ~ paths work too, and imported files can import others up to four hops deep.
Two details trip people up. Wrapping a path in backticks keeps it literal, so you can mention a file without loading it. And the first time a project imports a file from outside the working directory, Claude Code shows a one-time approval dialog before loading it.
Imports help you organize a long file, but they don't save context, because the imported text loads with the file that imports it. For that, use .claude/rules/. Every .md file in that folder is discovered recursively. A rule without a paths field loads at launch, while a rule with one loads only when Claude reads, writes or edits a matching file:
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Validate every request body before it reaches a handler
- Return errors in the shared error format
Claude Code strips that frontmatter before the rule reaches Claude, so only the heading and bullets land in context. This rule stays out of the way while Claude works on the front end, and loads the moment it opens an API file.
CLAUDE.md Best Practices That Make Claude Follow It
The docs suggest keeping each file under 200 lines. Longer files use more context and Claude follows them less reliably. Here's what we've found matters most:
- Write rules you can check. "Use 2-space indentation" beats "format code properly", and "run
npm testbefore committing" beats "test your changes". - Group with headings and bullets. Claude follows organized sections more reliably than dense paragraphs. Our Markdown style guide covers clean heading and list habits.
- Remove contradictions. If two lines disagree, Claude may pick either one. Review nested files and rules along with the root file.
- Add a line when a mistake repeats. The docs' own trigger is Claude making the same mistake twice, or you typing the same correction you typed last session.
- Leave human notes in HTML comments. Block-level comments are stripped before the file reaches Claude, so they cost no context.
- Prune it like code. Review CLAUDE.md changes in pull requests, and delete lines about scripts or folders that no longer exist. Stale instructions waste context and can point Claude at the wrong place.
We prefer a short root file plus a few path-scoped rules over one long file. The root stays readable, and each rule only appears when it's relevant.
The limitation is real, though. CLAUDE.md arrives as a user message after the system prompt, and the docs say there's no guarantee of strict compliance. Anything that must always happen, such as a lint run after every edit, belongs in a hook. Tools, commands or file paths Claude must never touch belong in a permissions.deny rule. Both are configured in settings files, which our Claude folder structure guide maps out.
Famous CLAUDE.md Examples: Boris Cherny, the Karpathy-Inspired File and Anthropic's Repo
Three real files show up whenever people look for CLAUDE.md examples, and each one teaches something different.
Boris Cherny's team file. In a January 2026 thread on X, the creator of Claude Code described how his team works. They share a single CLAUDE.md for the Claude Code repo and add to it whenever Claude gets something wrong. During code review he tags @claude on coworkers' pull requests to add a lesson to the file, using the Claude Code GitHub Action. Other teams at Anthropic keep their own files.
The Karpathy CLAUDE.md. Andrej Karpathy didn't write this one. It's a community repo, forrestchang/andrej-karpathy-skills, derived from Karpathy's January 2026 post on X about LLM coding pitfalls. The file boils those observations down to four principles: Think Before Coding, Simplicity First, Surgical Changes and Goal-Driven Execution. It's behavioral guidance with no project facts, so merge it with your own commands and conventions rather than using it alone.
Anthropic's own repo. The CLAUDE.md in anthropics/claude-code-action was under 60 lines when we checked in November 2026. Its sections are Commands, What This Is, How It Runs, Key Concepts, Things That Will Bite You, Code Conventions and a security section for GitHub Actions. That "Things That Will Bite You" heading is the most useful idea to borrow.
A note on AGENTS.md: recent versions of Claude Code read a repo's AGENTS.md when there's no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If you have both, put @AGENTS.md at the top of your CLAUDE.md so Claude and your other coding agents share one file. Our AGENTS.md guide covers which coding agents read that file.
Quick Answers About CLAUDE.md Files
A good CLAUDE.md file is short, specific and kept up to date. Start with /init, cut what Claude can work out from the code, and add a line each time it repeats a mistake. Push hard rules into hooks or permission settings. To draft or tidy one by hand, paste it into the editor to check the structure in the live preview, or fill in the form on our CLAUDE.md generator.