CLAUDE.md file: set up your first one in Claude Code

You open Claude Code, start a session, and spend the first two minutes explaining how your project works: the framework, the test command, the naming conventions, the deployment target. You did the same thing yesterday, and the day before that.

Every Claude Code session starts with a fresh context window (the text Claude can see at once). Claude reads your files, infers what it can, and guesses the rest. Sometimes the guesses are good, but sometimes it runs npm test on a project that uses bun test, or writes camelCase in a codebase that uses snake_case, or commits directly to main when you always use branches.

CLAUDE.md is a file that Claude reads at the start of every session. Whatever you put in it becomes part of the conversation before you type a word, so you write your conventions, preferences and rules down once. This guide is for people who use Claude Code on a real project, whatever it’s written in. What goes in that first file, and how do you know Claude is reading it? Setting it up takes about half an hour.

Part 1 of 4 Learn

Let /init write the first draft

The quickest way to a first file is to let Claude write it. Type /init in a Claude Code session in your project. Claude reads the codebase and writes a starting CLAUDE.md with the build commands, test instructions and conventions it can find. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.

That draft is a starting point. It can only write down what it finds in the code, so you add the project’s purpose and the corrections you keep making, using the four sections further down.

Where CLAUDE.md lives

The file /init creates sits in the root of your project directory, at the same level as your package.json, Cargo.toml, or whatever marks the top of your project. If you would rather make it yourself, create a file called CLAUDE.md there:

touch CLAUDE.md

When Claude Code starts a session in that directory, it reads this file automatically and needs no configuration.

The project root is the right place for your first file. The table shows it next to three other places that also work:

Claude Code adds every CLAUDE.md it finds to the context, with the most specific read last. It reads the ones above your working directory when the session starts, and a subfolder’s file when Claude first works on a file in that subfolder.

If two of them contradict each other, Claude may follow either one, so keep them consistent. Source: Anthropic’s memory docs, checked 5 November 2026.

You can add a global file later, once you find yourself copying the same rules between projects.

What to put in it

A first file is often either too short (a single line that says “use TypeScript”) or too long (a 2,000-line document that tries to cover every edge case). Both defeat the purpose.

A good first CLAUDE.md has four sections. Each one answers one thing Claude would otherwise guess: what the project is, which tools it uses, what to do or avoid, and which commands to run. The examples use a made-up Next.js project, so swap in your own stack.

Project overview

One paragraph. What is this project, and what does it do? Claude can read your code but not your intentions, so a sentence of context prevents many misunderstandings.

# Project

This is a Next.js 14 app for managing restaurant reservations. It uses the App Router, Prisma with PostgreSQL, and Tailwind CSS. The API serves both the web frontend and a mobile app.

This tells Claude what kind of project this is, so it makes better decisions about everything else. Without it, Claude might treat your full-stack web app like a CLI tool, or your library like an application.

Tech stack and conventions

What frameworks, tools, and patterns does this project use? Be specific about the things Claude would get wrong by defaulting to the most common option.

## Stack

- **Framework:** Next.js 14 with App Router (not Pages Router)
- **Database:** PostgreSQL via Prisma ORM
- **Styling:** Tailwind CSS, no component library
- **Testing:** Vitest for unit tests, Playwright for e2e
- **Package manager:** pnpm (not npm or yarn)

## Conventions

- Use named exports, not default exports
- API routes return `{ data, error }` shape, never throw
- Components go in `src/components/[feature]/`
- Database queries go through service files in `src/services/`, never called directly from routes

The conventions section is the highest-value part of the file. Every time you’ve corrected Claude mid-session (“we use named exports”, “put that in the services folder”), that correction belongs in this section.

Rules

List what Claude should always or never do in this project, and keep each rule short, specific and testable.

## Rules

- Always run `pnpm test` before suggesting a commit
- Never modify files in `src/generated/` — these are auto-generated by Prisma
- Use `async/await`, not `.then()` chains
- All new API routes need input validation with Zod
- Commit messages follow Conventional Commits format

“Always run pnpm test before suggesting a commit” can be checked mechanically. “Write clean code” and “follow best practices” add no information, because Claude already tries to do both. A rule should change what Claude does compared to what it would do without it.

Common commands

The commands you use to build, test, lint, and deploy. Claude can often find these by reading your package.json or Makefile, but listing them stops it guessing wrong or running a slow command when a fast one exists.

## Commands

- **Dev server:** `pnpm dev`
- **Run tests:** `pnpm test`
- **Run single test file:** `pnpm test -- src/path/to/test.ts`
- **Lint:** `pnpm lint`
- **Database migrations:** `pnpm prisma migrate dev`
- **Generate Prisma client:** `pnpm prisma generate`

This is especially useful if your project has non-obvious commands. If deploying requires three steps in a specific order, or if there’s a script that seeds the development database, put it here.

The complete starter

Here’s what those four sections look like together. Copy this, replace the specifics with your project’s details, and save it as CLAUDE.md in your project root.

# Project

[One paragraph: what this project is and what it does.]

## Stack

- **Framework:** [your framework and version]
- **Language:** [language and any relevant version info]
- **Testing:** [test framework and runner]
- **Package manager:** [which one]

## Conventions

- [How you name things]
- [Where different types of files go]
- [Patterns you follow consistently]

## Rules

- [Things Claude should always do]
- [Things Claude should never do]
- [Project-specific constraints]

## Commands

- **Dev:** `[command]`
- **Test:** `[command]`
- **Build:** `[command]`
- **Deploy:** `[command]`

Fifteen to thirty lines is a good target for a first file. You can always add more later, and you will, once you start noticing the corrections you no longer have to make.

Check that it loaded, then that it works

Start a new Claude Code session and run /context all. Your CLAUDE.md should be listed under Memory files (in fullscreen mode, plain /context collapses that list). If it isn’t there, Claude can’t see it: check the file is in the project root and named exactly CLAUDE.md (the name is case-sensitive on Linux).

Then ask Claude to do something your file covers. If you added a rule about test commands, ask it to run the tests. If you specified naming conventions, ask it to create a new component. You should see Claude follow your conventions without being told.

If it loaded and Claude still doesn’t follow an instruction, the instruction is usually too vague. “Follow the project conventions” tells Claude nothing. “Use named exports, not default exports” tells it exactly what to do. Claude treats CLAUDE.md as context, so it follows clear instructions consistently but isn’t forced to; anything that must happen every time at a set point, such as after each edit, belongs in a hook (see the next section). Source: Anthropic’s memory docs, checked 5 November 2026.

---

What goes somewhere else

CLAUDE.md is one of several places Claude Code keeps instructions and knowledge. If an instruction is in the wrong place, Claude may load it when it isn’t needed, or skip it when it is.

Auto memory is on by default in local sessions, so Claude Code may already be saving notes about your project. As you work, Claude saves notes for itself in ~/.claude/projects/<project>/memory/, with an index file called MEMORY.md. It’s local to your machine and isn’t shared through Git.

The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of every session, and Claude reads the other notes when it needs them.

Run /memory to see and edit these files, or to switch auto memory off. When you ask Claude to remember something, it goes into auto memory; to put it in CLAUDE.md instead, say “add this to CLAUDE.md”.

Keep task progress out of CLAUDE.md. “Currently working on the auth refactor” is stale by next Monday, and it would load in every session until you remember to delete it. Auto memory can note ongoing work and deadlines, and Claude updates those notes as things change.

The same table lists skills, which used to be called custom commands. A file in .claude/commands/ still works, but Anthropic now recommends skills for new work. A skill’s folder can also hold supporting files, such as a template or a script. Project skills in .claude/skills/ can be committed so your whole team gets them; personal ones in ~/.claude/skills/ follow you across projects. Sources: Anthropic’s memory and skills docs, checked 26 October 2026.

Try it on six things you might tell Claude.

Made-up example for illustration. The project and its instructions are invented.

Which file does it go in?

How to read this

Six things you’ve had to tell Claude in a project. Choose where each one belongs, and you’ll see where the guide puts it.

1. “Always run pnpm test before suggesting a commit.”

   CLAUDE.mdAuto memoryA rule fileA skillA hook

   CLAUDE.md. It’s a rule Claude needs in every session, and you can check it was followed.

2. “Run the formatter after every edit.”

   CLAUDE.mdAuto memoryA rule fileA skillA hook

   A hook. Claude Code runs a hook’s command at that point every time, and Claude can skip a CLAUDE.md instruction.

3. “Remember that I prefer short answers.”

   CLAUDE.mdAuto memoryA rule fileA skillA hook

   Auto memory. It’s your preference, and when you ask Claude to remember something, it goes into auto memory.

4. “In the API folder only: every new route validates its input with Zod.”

   CLAUDE.mdAuto memoryA rule fileA skillA hook

   A rule file. It applies to one part of the codebase, and a paths line makes the rule file load only for files in the API folder.

5. “Our twelve-step deploy procedure.”

   CLAUDE.mdAuto memoryA rule fileA skillA hook

   A skill. It’s a multi-step workflow, and a skill loads only when you run it.

6. “We’re currently working on the auth refactor.”

   CLAUDE.mdAuto memoryA rule fileA skillA hook

   Auto memory. Task progress goes stale, and in CLAUDE.md it would load in every session until you deleted it. Auto memory can note ongoing work, and Claude updates those notes as things change.

Nothing placed yet.

Start over

This page sends nothing anywhere. Your choices stay in your browser.

How to read this

CLAUDE.md is one of several places Claude Code keeps instructions and knowledge. If an instruction is in the wrong place, Claude may load it when it isn’t needed, or skip it when it is.

CLAUDE.md

Facts and rules Claude needs in every session.

Auto memory

Your preferences and corrections, and project context Claude can’t get from the code. Claude writes it.

A rule file

Instructions for one part of the codebase, in .claude/rules/.

A skill

A multi-step workflow you run now and then.

A hook

Something that must happen every time at a set point.

Got it

How to evolve it over time

Your CLAUDE.md should grow, but slowly, and the best additions come from real sessions rather than from sitting down to anticipate every scenario.

The pattern: you’re working with Claude when it does something wrong, and you correct it. Then ask yourself: will this come up again? If it will, add a line to CLAUDE.md. If it’s a one-off, don’t bother.

A few maintenance habits help:

• Review it monthly. Remove rules that no longer apply. A convention you’ve abandoned actively misleads Claude, because it will keep following it.
• Keep it under 200 lines. That’s Anthropic’s target: longer files use more context and get followed less reliably. If it’s longer, you’re probably specifying things Claude can infer from your code, or things that belong in a rule file or a skill.
• Use headings and bullet points. A well-structured file is easier for Claude to follow, just as it’s easier for a person to skim.
• Run /doctor prompt-audit (Claude Code 2.1.283 or later). Claude checks your CLAUDE.md, rules and skills for outdated instructions, references to files or commands that no longer exist, and files that contradict each other. It proposes edits and changes nothing until you say so.

Using other coding tools too

Other coding assistants read their own instruction file, and AGENTS.md is the one several of them share:

If you use more than one, keep your shared instructions in AGENTS.md. Claude Code (version 2.1.277 or later) reads it when there’s no CLAUDE.md or CLAUDE.local.md in the project or the folders above it. If you want Claude-specific instructions as well, make a CLAUDE.md that starts with @AGENTS.md and add them below it. Running /init in a project that already has Cursor or Copilot rules pulls the relevant parts into the CLAUDE.md it writes. Sources: Anthropic’s AGENTS.md docs, Cursor, OpenAI, GitHub, Anthropic’s page checked 5 November 2026, the others 26 October 2026.

Part 2 of 4 Practise

Try it on your own work

1. Run /init in a Claude Code session in your project.Result a CLAUDE.md in the project root with the commands and conventions Claude found.

2. Add what /init couldn’t know: one paragraph on what the project is, and the corrections you’ve typed more than once, using the four sections above.Result a file of fifteen to thirty lines with an overview, stack and conventions, rules and commands.

3. Start a new session and run /context all.Result CLAUDE.md is listed under Memory files.

4. Ask Claude to do something one of your rules covers, such as running the tests.Result it uses your command without being told.

5. Take three things you’ve had to tell Claude recently and decide where each belongs, using the table under “What goes somewhere else”.Result you’ve decided which one each goes in: CLAUDE.md, auto memory, a rule file, a skill or a hook.

6. Run /memory.Result a list of your CLAUDE.md files and the auto memory folder, with the option to open any of them.

7. A month later, prune the file. Run /doctor prompt-audit, or read the file yourself, and remove or update anything that’s out of date.Result no line in the file contradicts how the project works now.

Part 3 of 4 Check

Check yourself

You ran /init on a four-year-old project. The draft lists `npm test`, but your team switched to `bun test` last spring and nobody remembers why the `legacy/` folder is off limits. What do you do before relying on the file?

Correct the test command, then add what Claude can’t see in the code: a paragraph on what the project is for, a rule such as “never edit legacy/”, and the conventions it keeps getting wrong. Add the corrections you’ve typed more than once.

You added a rule to CLAUDE.md, but Claude ignores it in a new session. What do you check first?

Run /context all and look under Memory files. If CLAUDE.md isn’t listed, Claude can’t see it: check the file’s location and name. If it is listed, make the rule more specific, and check that no other CLAUDE.md or rule file says the opposite.

You keep reminding Claude to run the formatter after every edit, and sometimes it forgets. Where does that instruction belong?

In a hook that runs after each file edit. Claude Code runs a hook’s command at that point every time, and Claude can skip a CLAUDE.md instruction.

Your CLAUDE.md has reached 450 lines. It includes a twelve-step deploy procedure, rules that only apply to the API folder, and a line saying to use Jest, though you moved to Vitest last year. What do you do with each?

Move the deploy procedure into a skill, so it loads only when you run it. Move the API rules into a file in .claude/rules/ with a paths line for the API folder. Change the Jest line to Vitest, or delete it if Claude can tell from the project. That brings the file back towards Anthropic’s target of under 200 lines.

Your team uses Cursor and you use Claude Code. Where do the shared project conventions go?

In AGENTS.md, which Cursor reads. Claude Code reads it too when there’s no CLAUDE.md or CLAUDE.local.md in the project or the folders above it. If you want Claude-only instructions as well, add a CLAUDE.md that starts with @AGENTS.md.

Part 4 of 4 Keep

Keep this

Add a line when a correction will come up again

A first CLAUDE.md is fifteen to thirty lines covering what the project is, its stack and conventions, its rules and its commands, and /context all shows whether Claude loaded it.

• When you correct Claude and it’ll come up again, add a line to CLAUDE.md.
• After changing the file, start a new session and run /context all to check it loaded.
• Keep CLAUDE.md for what Claude needs every session, and move the rest to rule files, skills or hooks.
• Let auto memory hold your preferences, and look through it with /memory now and then.
• Once a month, prune CLAUDE.md or run /doctor prompt-audit.

After your next session, open CLAUDE.md and add the one correction you typed twice.

In the Kit Library, members can get a ready-to-fill CLAUDE.md with the four sections, plus a worked example.

Print this card

Read next

• How to Audit Your AI Usage Patterns: /insights suggests CLAUDE.md lines based on the corrections you keep typing.
• Connecting MCP Servers to Claude Code: once Claude knows your project, give it access to your other tools.
• What claude doctor and /doctor check: when Claude Code itself is behaving oddly.