Teach Claude Code your project with CLAUDE.md

Every time you start Claude Code, it begins with a blank slate: it doesn't remember last week's chat. That's why you end up repeating yourself ("we use tabs", "run tests with this command", "never touch the legacy folder").

CLAUDE.md fixes that. It's a plain text file of instructions that Claude Code reads automatically at the start of every session. Think of it as a one-page briefing for a new colleague.

This guide shows you how to create one, what to put in it, and how to keep it useful. It assumes you've already installed Claude Code.

What CLAUDE.md is (and isn't)

• It's a normal Markdown file. Markdown is plain text with simple formatting, like # for headings and - for bullet points. You can edit it in any text editor.
• Claude reads it at the start of a session and treats it as standing context.
• It is guidance, not a hard lock. If you need something to be strictly enforced (for example, blocking a dangerous command), use Claude Code's permission settings or hooks instead.

Where the file lives

Claude Code looks in several places. From the official memory docs:

Files in folders above your working directory load when Claude starts. Files in subfolders load on demand, when Claude works in them. That lets a big project have a short root file and extra notes where they're needed.

For most people, one file at the root of the project is all you need.

Step 1: Let Claude draft it with /init

The easiest start is to let Claude look at your project and write a first version.

1. Open a terminal in your project folder.
2. Run claude.
3. Type /init and press Enter.

Claude analyses your codebase and creates a CLAUDE.md with build commands, test instructions and conventions it discovered. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it.

Open the new file and read it. It's a draft: Claude can only describe what it can see, so it will miss your preferences and the reasons behind decisions.

Step 2: Add what Claude can't guess

The best CLAUDE.md content is things that aren't obvious from the code. Here's a template you can adapt:

# My Project

A small shop website for a bakery. Built with Astro and plain CSS.

## Commands
- Start the dev server: `npm run dev`
- Build for production: `npm run build`
- There is no test suite yet. Check changes by running the build.

## Conventions
- Use British English in all visible text.
- Keep CSS in `src/styles/`. Don't add inline styles.
- Prices are stored in pence, not pounds.

## Rules
- Never edit anything in `src/generated/`. It is rebuilt automatically.
- Ask before adding a new dependency.
- Don't change the logo or brand colours without asking.

## Where things are
- Page templates: `src/pages/`
- Reusable pieces: `src/components/`

Notice the pattern:

• Commands save Claude from guessing how to run things.
• Conventions keep its edits consistent with your style.
• Rules draw clear lines about what's off-limits.
• Where things are speeds up exploring.

Be specific

Vague instructions get vague results. Compare:

If a person couldn't follow the instruction without asking a question, Claude can't either.

Step 3: Keep it short

Anthropic's guidance is to aim for under 200 lines per CLAUDE.md. Every line is loaded into each session, so a long file takes up more of Claude's working memory and buries the instructions that matter.

A useful test for each line: "Would Claude make a mistake without this?" If not, cut it. Things Claude can read directly from the code, such as which framework you use, rarely need to be written down.

Step 4: Split big files with imports

If your file is growing, you can point to other files using @ imports:

See @README for a project overview.
Available npm commands are listed in @package.json.

## Style guide
@docs/style-guide.md

Claude pulls those files in when it loads your CLAUDE.md. Relative paths are resolved from the file that contains the import, and imports can chain up to four levels deep. Imports inside code blocks are ignored, and files outside your project need a one-time approval.

Step 5: Add to it as you go

You don't have to write it all at once. When you catch yourself correcting Claude for the second time ("no, we don't use that library"), that's a sign it belongs in the file.

You can ask Claude to do it for you:

Add to CLAUDE.md: always run the build before saying a task is finished.

Or run /memory inside Claude Code to see which memory files are loaded and open them in your editor.

Step 6: Personal preferences go in your user file

Some instructions are about you, not the project: "explain technical terms in plain English", "keep answers short". Put them in ~/.claude/CLAUDE.md so they apply everywhere without cluttering the project's shared file. In that file, a non-coder might write:

# About me
- I'm not a developer. Explain technical terms the first time you use them.
- Before changing many files, tell me the plan in plain English.
- After each change, tell me how I can check it myself.

For things that only apply to this project and only to you, such as a local test URL, use CLAUDE.local.md and add it to .gitignore.

Checking that it works

Start a new session and ask something your file should answer:

How do I run this project, and what are the rules about dependencies?

If the answer reflects your file, it's loaded. If not, check that the file is named exactly CLAUDE.md (capital letters matter on many systems) and sits in the folder where you launched claude.

Common mistakes

• Writing an essay. Claude does better with short, scannable bullets than paragraphs.
• Contradictions. If one section says "use tabs" and another says "2 spaces", expect inconsistent results. Re-read the file occasionally.
• Stale instructions. Commands change. If you rename a script, update the file.
• Secrets. Never put passwords, tokens or API keys in CLAUDE.md, especially if you commit it.
• Treating it as security. It's a nudge, not a lock.

A quick checklist

• [ ] Run /init to get a first draft
• [ ] Add the commands you use daily
• [ ] Add the three rules you'd tell a new teammate on day one
• [ ] Keep it under about 200 lines
• [ ] Commit it so your team shares it
• [ ] Update it whenever you correct Claude twice

Where to go next

Once CLAUDE.md covers the basics, the next step up is packaging repeatable jobs as skills. Our guide on writing your first Claude Code skill shows how.