What Is a CLAUDE.md File? (And How to Set One Up)

You open Claude Code. You explain your stack. You explain your naming conventions. You explain that you never want it to delete files without asking. Claude nods along and helps you build.

Next session, you open Claude Code. You explain your stack. You explain your naming conventions. You explain that you never want it to delete files without asking.

Sound familiar? This is the "repeating yourself" tax — and CLAUDE.md is how you stop paying it.

The Problem: Claude Forgets Everything Between Sessions

Why Claude starts fresh every time you open a project

Claude Code has no persistent memory between sessions by default. Every time you start a new conversation, the model starts with a blank slate. It has no idea what framework you're using, what your file structure looks like, or what rules you've set in previous sessions.

This is by design — language models don't retain information across separate context windows. But it creates real friction for developers working on the same project day after day.

The "repeating yourself" tax — what it costs beginners

For experienced developers, repeating context is annoying. For beginners, it's worse — you often don't know what context matters, so you either over-explain or under-explain, and Claude gives you answers that don't fit your actual project.

Every session spent re-orienting Claude is time not spent building. CLAUDE.md solves this by giving Claude a permanent briefing document it reads at the start of every session — automatically.

What Is a CLAUDE.md File?

Plain-English definition

CLAUDE.md is a plain text Markdown file that Claude Code reads at the start of every session. It contains instructions, context, and rules specific to your project. Think of it as a standing brief you write once — Claude reads it every time without you having to ask.

It's just a .md file. No special syntax, no configuration schemas. You write it in plain English, save it in the right place, and Claude treats it as the foundation of every conversation in that project.

Where Claude looks for it

Claude Code scans for CLAUDE.md files in a few locations, in order of specificity:

• Project root — the most common location. Drop CLAUDE.md at the top level of your repo and Claude reads it for every session in that directory.
• Home directory — a global CLAUDE.md at ~/.claude/CLAUDE.md acts as a fallback that applies to all projects on your machine. Useful for global preferences like your preferred language or formatting rules.
• Subfolders — CLAUDE.md files in subdirectories are read when Claude is working in that part of the project, letting you set context specific to a module or package.

When multiple CLAUDE.md files exist, Claude reads them all and combines the context.

How it becomes part of Claude's context automatically

You don't prompt Claude to read the file. You don't attach it. Claude Code detects and loads CLAUDE.md as part of its startup process — it becomes part of the system context before you type your first message.

This means your rules and conventions are active from the very first line you write in a session, without any extra steps on your part.

What Goes Inside a CLAUDE.md File?

Your tech stack and project structure

Start with the basics: what you're building, what tools you're using, and how the project is organized. Claude doesn't need a novel — a few lines is enough.

## Stack
- Next.js 14 (App Router), TypeScript, Tailwind CSS
- Supabase for auth and database
- Deployed on Vercel

## Project Structure
- `app/` — routes and pages
- `components/` — shared UI components
- `lib/` — utilities and data fetching

Coding style and conventions

Tell Claude how you write code — file naming, function style, import order, whatever matters to your project. Claude will follow these conventions when it generates or edits code.

## Conventions
- Use named exports, not default exports
- File names: kebab-case (e.g., `user-profile.tsx`)
- No inline styles — use Tailwind classes only
- Prefer `const` arrow functions over `function` declarations

Common commands

If you want Claude to run your dev server, tests, or build process without asking you every time, list the commands.

## Commands
- Dev server: `npm run dev`
- Tests: `npm test`
- Build: `npm run build`
- Lint: `npm run lint`

Things Claude should never do

This is one of the most valuable sections for beginners. Claude will respect hard constraints you set here.

## Rules
- Never delete files without asking me first
- Never modify files in `public/` without confirmation
- Always ask before running database migrations

What to leave out — keeping it under 500 words

There's no hard enforced limit on CLAUDE.md length, but longer is not always better. Every line in CLAUDE.md is added to Claude's context window for every session. Long files use up tokens that could be used for actual work.

Keep it practical. Document what actually repeats across sessions — not everything about your project. If you find yourself writing paragraphs of background, trim it down to bullet points. The goal is a fast briefing, not a full spec document.

A good target is 200–500 words. If you go over 800, audit what's actually needed.

How to Create Your First CLAUDE.md File

Option 1: Use /init — the 30-second method

Claude Code ships with an /init command that scans your project and generates a CLAUDE.md automatically. Open your project in Claude Code and run:

/init

Claude will inspect your project structure, detect your stack, and write a starter CLAUDE.md for you. Review what it generates, remove anything that doesn't apply, and add anything it missed. You now have a working CLAUDE.md in under a minute.

If you already have a CLAUDE.md, /init will update it based on the current codebase rather than overwrite it — your existing content is preserved and extended.

Option 2: Create it manually — a starter template

If you prefer to write it yourself, create a file called CLAUDE.md in your project root and start with this template:

## Project
[One sentence: what this project is and what it does]

## Stack
- [Framework, language, runtime]
- [Database or backend service]
- [Deployment target]

## Structure
- `src/` — [what goes here]
- `components/` — [what goes here]

## Conventions
- [Naming convention]
- [Import style]
- [Any formatting rules]

## Commands
- Dev: `[your dev command]`
- Test: `[your test command]`
- Build: `[your build command]`

## Rules
- [What Claude should never do]
- [What requires confirmation]

Fill in the blanks, save the file, and open a new Claude Code session. Claude will read it automatically.

Where to save it

For most projects: save CLAUDE.md in the root of your repo — the same directory as your package.json or README.md. That's it.

If you want global rules that apply to every project on your machine, create ~/.claude/CLAUDE.md. These rules apply everywhere, so keep them general (language preferences, communication style, never-delete rules).

If you haven't installed Claude Code yet, see the setup guides for Mac or Windows first.

CLAUDE.md vs. Other Claude Code Config Files

CLAUDE.md is one piece of a larger system. Here's how it fits with the other tools Claude Code gives you.

CLAUDE.md vs. Skills — instructions vs. specialist knowledge

CLAUDE.md gives Claude standing instructions about your project. Skills give Claude reusable specialist knowledge — how to do a type of task well, across any project. Think of CLAUDE.md as your project handbook and Skills as Claude's professional training.

You can use both. CLAUDE.md tells Claude about this project. A Skill tells Claude how to, say, write great code reviews or generate pixel art prompts — regardless of what project it's in. Check out how to make Claude Code Skills auto-activate once you're ready to level up.

CLAUDE.md vs. Hooks — context vs. automation

Claude Code Hooks are triggers that run code automatically when certain events happen — like linting your file after every edit, or logging every command Claude runs. CLAUDE.md is passive context; Hooks are active automation.

You'd use CLAUDE.md to tell Claude "always use Tailwind, never inline styles." You'd use a Hook to automatically run a linter that enforces that rule after every file edit. They complement each other. See how to use Claude Code Hooks to keep your code clean for practical examples.

CLAUDE.md vs. Agents — not the same thing

Claude Code Agents are sub-agents Claude can spin up to handle specific tasks in parallel or sequentially. CLAUDE.md is a context file, not an agent. Don't confuse them — agents run tasks, CLAUDE.md provides the briefing.

A Real CLAUDE.md Example (Copy and Adapt This)

Here's an annotated CLAUDE.md for a beginner Next.js project. Each section explains why it's there.

## Project
A personal portfolio site built with Next.js and Tailwind.
Deployed to Vercel. No backend — all content is static MDX files.

## Stack
- Next.js 14 (App Router), TypeScript
- Tailwind CSS for styling
- MDX for blog content via next-mdx-remote
- Deployed on Vercel

## Project Structure
- `app/` — routes (App Router)
- `components/` — shared React components
- `content/` — MDX articles and project pages
- `public/` — static assets (images, fonts)

## Conventions
- Use named exports only — no default exports
- File names: kebab-case for files and directories
- Component props: always define a TypeScript interface above the component
- No inline styles — Tailwind classes only

## Commands
- Dev server: `npm run dev` (runs at http://localhost:3000)
- Build: `npm run build`
- Type check: `npx tsc --noEmit`

## Rules
- Never delete any file without asking me first
- Never modify files in `public/` without confirmation
- If you're unsure about a destructive action, ask — don't guess
- Keep responses focused on the task — no lengthy explanations unless I ask

This fits in under 200 words, covers what repeats every session, and leaves room in the context window for real work.

What Happens After You Add It?

Testing that Claude actually reads it

Open a new Claude Code session in your project and ask Claude something that should be answered differently because of your CLAUDE.md — for example: "What's our dev server command?" or "How should I name new component files?"

If Claude answers based on what's in your CLAUDE.md, it's working. If it gives a generic answer, double-check that your file is saved in the project root with the exact filename CLAUDE.md (capital letters, .md extension).

Iterating — CLAUDE.md is a living document

Your first CLAUDE.md won't be perfect. That's fine. Update it whenever Claude does something you didn't want — add a rule. Update it when you catch yourself explaining the same thing twice — add it to the file. Over time your CLAUDE.md becomes a precise, low-noise brief that makes every session faster.

Some developers review their CLAUDE.md at the start of each week and trim anything that's no longer relevant. Treat it like code: refactor regularly, delete what doesn't pull its weight.

FAQ

Does CLAUDE.md work in Cursor or Windsurf too?

CLAUDE.md is a Claude Code-specific convention. Cursor and Windsurf have their own equivalents — Cursor now uses .cursor/rules/*.mdc files (the older .cursorrules format is deprecated), and Windsurf uses .windsurfrules or the newer .windsurf/rules/ directory format. Neither reads CLAUDE.md natively. If you switch editors, you'll need to translate your CLAUDE.md content into the format that editor expects.

Can I have more than one CLAUDE.md?

Yes. You can have a global one at ~/.claude/CLAUDE.md for machine-wide preferences and a project-level one at your repo root. You can also place CLAUDE.md files in subdirectories for module-specific context. Claude reads all of them and combines the context.

Is there a size limit?

There's no hard enforced character or token limit on CLAUDE.md that Claude Code will reject. The practical limit is your context window — an extremely long CLAUDE.md eats into the tokens available for your actual conversation. Keep it focused and under 500 words for best results.

---

The fastest way to write a good CLAUDE.md is to use /init and then spend five minutes editing the output. You'll never re-explain your stack in a session opener again.

If you haven't set up Claude Code yet, start with the Mac setup guide or Windows setup guide.