Setting Up Your First CLAUDE.md File

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.

Claude Code doesn’t remember previous sessions. Every conversation starts from zero — it reads your files, infers what it can, and guesses the rest. Sometimes the guesses are good. 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.

There’s a fix for this, and it takes about twenty minutes to set up. 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. Your conventions, your preferences, your rules — stated once, followed every time.

What you’ll need

• Claude Code — installed and working. If you haven’t set it up yet, follow Anthropic’s installation guide.
• A project directory — any codebase you’re actively working on. An existing project works better than an empty folder because you already know what you keep repeating.

Where CLAUDE.md lives

Create a file called CLAUDE.md in the root of your project directory — the same level as your package.json, Cargo.toml, or whatever marks the top of your project.

touch CLAUDE.md

When Claude Code starts a session in that directory, it reads this file automatically. No configuration, no flags. If the file exists, Claude sees it.

There are actually three levels where you can place these files:

• ~/.claude/CLAUDE.md — global. Loaded for every project on your machine. Good for personal preferences that apply everywhere.
• CLAUDE.md in your project root — project-level. Loaded when you work in that directory. This is where most of your instructions belong.
• CLAUDE.md in subdirectories — scoped. Loaded when Claude works with files in that subdirectory. Useful for monorepos where different packages have different conventions.

If all three exist, Claude reads them all — global first, then project root, then the most specific subdirectory. Instructions are additive: all three files contribute, with project-level rules taking precedence when they conflict with global ones.

For your first file, start with the project root. You can add a global one later if you find yourself duplicating rules across projects.

What to put in it

Here’s where people go wrong: they either write too little (a single line that says “use TypeScript”) or too much (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 a question Claude would otherwise have to guess about.

Project overview

One paragraph. What is this project, and what does it do? Claude can read your code, but it can’t read your mind. A sentence of context prevents entire categories of misunderstanding.

# 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 isn’t documentation for humans — it’s calibration for Claude. You’re telling it what kind of project this is so it makes better decisions about everything else. Without this, 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 — “no, we use named exports” or “put that in the services folder, not here” — that correction belongs in this section. Write it once, never repeat it.

Rules

Things Claude should always do or never do in this project. Keep these short, specific, and testable. A good rule can be checked mechanically. A bad rule is too vague to act on.

## 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

Compare those to rules like “write clean code” or “follow best practices.” Those rules mean nothing because Claude already tries to do both — they add no information. A rule should change what Claude does compared to what it would do without the rule.

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 having them explicitly listed prevents it from guessing wrong or running a slow command when a fast alternative 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.

See the difference

The fastest way to verify your CLAUDE.md is working: start a new Claude Code session and 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 doesn’t, check two things:

1. Is the file in the right place? It needs to be in the project root, named exactly CLAUDE.md. The name is case-sensitive on Linux; macOS is usually case-insensitive but CLAUDE.md is the expected convention regardless.
2. Are your instructions specific enough? “Follow the project conventions” tells Claude nothing. “Use named exports, not default exports” tells it exactly what to do.

How to evolve it over time

Your CLAUDE.md should grow, but slowly. The best additions come from real sessions, not from sitting down and trying to anticipate every scenario.

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

Over a few weeks, you’ll build up a file that precisely matches how you work. It’s personal documentation — not a template someone else wrote, but a record of your actual preferences, discovered through use.

A few maintenance habits that help:

• Review it monthly. Remove rules that no longer apply. A convention you’ve abandoned is worse than no convention — it actively misleads Claude.
• Keep it under 500 lines. If it’s longer, you’re probably specifying things Claude can infer from your code. CLAUDE.md is for the things that aren’t obvious from reading the codebase.
• Use headings and bullet points. Claude parses markdown. A well-structured file is easier for Claude to follow, just like it’s easier for a human to skim.

Other tools, same idea

This concept isn’t unique to Claude Code. If you use other AI coding assistants, the same principle applies with a different filename:

Tool	File	Location
Claude Code	CLAUDE.md	Project root or ~/.claude/
Cursor	.cursor/rules/	Project root (.cursorrules is the legacy format)
Windsurf	.windsurfrules	Project root
GitHub Copilot	.github/copilot-instructions.md	Project root

The format varies between tools, but the content is the same: your conventions, your commands, your rules. Write it once per tool.

Where to go from here

• Add a global file — once your project CLAUDE.md is working, create ~/.claude/CLAUDE.md for preferences that apply to every project on your machine: preferred language, commit message format, tools you always use.
• Connect Claude to external tools — once Claude knows your project conventions, the next step is giving it access to your APIs and services through MCP servers.
• Read Anthropic’s CLAUDE.md documentation — the official reference covers additional options like @ imports for pulling in other files and the full loading order in detail.