<aside> ℹ️

Difficulty: Beginner • Time: 20 minutes • Tools: Claude Code

</aside>

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.

The starter template

Copy this into a file called CLAUDE.md in the root of your project. Replace the placeholders with your actual details.

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

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.