If you use Claude Code — Anthropic's terminal-based AI coding assistant — you have probably found yourself typing the same instructions over and over at the start of every session. CLAUDE.md files solve exactly that problem. Place a plain-text file named CLAUDE.md in the right folder, write your instructions inside, and Claude Code will read it automatically every time a new session starts. The clever part is that you can have multiple CLAUDE.md files in different locations, each covering a different scope — organisation-wide policies, personal habits, project-specific rules, and even folder-level nuances. This guide walks you through each location, explains the load order, and shows you what to put where.
What is a CLAUDE.md file?
Think of CLAUDE.md as the onboarding note you leave for a new colleague — except the colleague is Claude. It is a plain-text file in Markdown format (Markdown — a lightweight way to format text using symbols like # for headings and - for bullet points). You write your instructions there once; Claude Code reads them automatically at the start of every session. No special import steps are needed — placing the file in the right location is all it takes.
According to the official documentation, Claude treats the contents of CLAUDE.md as context to guide its behaviour, not as hard-enforced commands. The more specific and concise your instructions, the more consistently Claude follows them. A short, focused file works better than a long, sprawling one.
Location equals scope — the core idea
The central principle is simple: where you put the file determines who and what it affects. You can layer files from the broadest scope (the whole organisation) down to the narrowest (a single folder). Claude Code reads them all and combines them into one shared context for the session.
Level 1 — Organisation-wide rules (managed policy file)
Rules that should apply to every developer in your company — security standards, required coding conventions — live in a system-level path managed by IT or DevOps (DevOps — the team that manages developer infrastructure and tooling). According to the official documentation, the exact path differs by operating system (OS — the software that runs your computer, such as macOS, Linux, or Windows).
- macOS:
/Library/Application Support/ClaudeCode/CLAUDE.md - Linux and WSL (WSL — Windows Subsystem for Linux, a way to run Linux inside Windows):
/etc/claude-code/CLAUDE.md - Windows:
C:\Program Files\ClaudeCode\CLAUDE.md
This file affects all users across all projects. Most individuals will never touch it — it is an organisational tool administered centrally.
Level 2 — Personal rules for all your projects (home directory)
Preferences that follow you regardless of the project — "always explain code in plain English", "keep commit messages (Commit message — the short description you attach to a saved code change) under 72 characters" — go in your home directory.
- Path:
~/.claude/CLAUDE.md
The tilde (~) is shorthand for your home directory — the default personal folder for your user account. On macOS that is /Users/yourname/.claude/; on Linux it is /home/yourname/.claude/. This file is not tracked by Git (Git — a version control tool that records the history of code changes), so your teammates never see it.
Level 3 — Project-wide rules (project root)
Rules the whole team should follow belong in the top-level folder of your project, known as the root (Root — the topmost directory of a project). Commit this file to your Git repository so everyone inherits it.
- Path:
./CLAUDE.mdor./.claude/CLAUDE.md
Good candidates include the programming language and version the project uses, how to run the test suite, or PR conventions (PR — Pull Request, a formal proposal to merge code changes into the main codebase). Think of it as "everything a new team member would need to know to be productive on day one."
Level 4 — Folder-specific rules (subdirectory)
Large projects often have areas with different rules. A src/ folder might use TypeScript (TypeScript — JavaScript with added type annotations) while a scripts/ folder uses Python. You can place a CLAUDE.md inside each folder to capture those differences.
- Example paths:
./src/CLAUDE.md,./tests/CLAUDE.md
According to the official documentation, subdirectory CLAUDE.md files are loaded on demand — not at session start, but at the moment Claude Code reads a file inside that folder. This keeps the initial context lean and loads extra rules only when they are relevant.
Level 5 — Personal project notes (CLAUDE.local.md)
Some notes are too personal to share — a local test server address, a preferred set of seed data, a reminder about a quirk only you care about. These go in CLAUDE.local.md.
- Path:
./CLAUDE.local.md(project root)
⚠ Important: You must add this file to .gitignore (.gitignore — a file that tells Git which files to ignore and not upload). Without that step, the file will be committed and shared with your team. Open your .gitignore and add this line:
CLAUDE.local.mdIn what order are the files loaded?
According to the official documentation, Claude Code loads CLAUDE.md files at session start in order from broadest to most specific: org policy → personal rules → project root → local notes. CLAUDE.md files found in any directory above your working directory (the folder you have open) are also loaded in full automatically.
When two files contain conflicting instructions, the more specific (later-loaded) instruction generally takes precedence. However, this is not a hard guarantee — Claude uses the files as context, not a configuration parser. To avoid confusion, keep each file's role distinct and try not to repeat the same instruction in multiple places.
How to create your first CLAUDE.md
CLAUDE.md is just a text file. You can create it with any text editor — Notepad, TextEdit, VS Code, whatever you prefer. The only requirements are that it is saved as plain text and named exactly CLAUDE.md (capital letters matter on macOS and Linux). Here is a minimal example for a project root:
# Project overview
- Language: Python 3.11
- Package manager: poetry
- Run tests: pytest tests/
# Coding conventions
- Use snake_case for function names
- Every function must have a docstring (a short description comment)
# Useful commands
- Start dev server: python main.py --dev
- Lint check: ruff check .Save the file, then start a new Claude Code session (or open a new conversation). Claude Code will pick it up automatically — no import step needed. If it seems like Claude is not following your instructions, check the troubleshooting section below.
Splitting a large CLAUDE.md with .claude/rules/
If your project CLAUDE.md grows unwieldy, the .claude/rules/ folder gives you a way to split instructions into topic-specific files. According to the official documentation, rules in this folder can also be scoped to specific file types or paths — for example, applying a rule only when Claude is editing files inside src/api/. Start with a single CLAUDE.md and graduate to rules only when you feel the file is getting hard to maintain.
Auto Memory — the companion system
Alongside CLAUDE.md files, Claude Code has a second memory mechanism called Auto Memory (auto memory — notes that Claude writes automatically based on corrections you make during a session). While CLAUDE.md is something you write, auto memory is something Claude accumulates on its own. Both are loaded at the start of every session. You can review and edit auto memory at any time by typing /memory inside Claude Code.
Common problems and how to fix them
- Claude is not following my CLAUDE.md. First, verify the file name is exactly
CLAUDE.md— lowercase variants likeclaude.mdwill not be recognised on macOS and Linux. Second, check that the file is in the right location. Third, review the content: the official documentation notes that instructions work best when they are specific and concise. Vague or very long files are less reliably followed. - My subdirectory CLAUDE.md seems to be ignored. Subdirectory files are not loaded at session start. They load when Claude Code actually reads a file in that folder. Ask Claude to look at a file in that directory and the rules will load at that point.
- I accidentally committed CLAUDE.local.md to Git. Add
CLAUDE.local.mdto your.gitignoreimmediately, then untrack the file withgit rm --cached CLAUDE.local.mdand commit the change. If the file contained sensitive information, you will also need to remove it from the Git history. - I am not sure what auto memory has saved. Run
/memoryinside Claude Code to see the current auto memory contents. You can edit or delete entries from that view.
Practical starting point
If you are new to this, start small. Create one CLAUDE.md in your project root and add team-wide rules there. Put personal habits in ~/.claude/CLAUDE.md. Keep private notes in CLAUDE.local.md and add it to .gitignore. Introduce subdirectory files and .claude/rules/ only when a single file starts to feel cluttered. A practical habit: whenever Claude makes the same mistake twice, or whenever you type the same explanation twice in a session, that is your signal to add the information to CLAUDE.md. Build it up gradually rather than trying to capture everything on day one.