The CLAUDE.md File
Every time you start a Claude Code session, it reads a file called CLAUDE.md from your project root. Whatever is in that file becomes permanent context — your stack, conventions, folder structure, and commands — loaded automatically, every session, without you having to repeat it.
Write once, remembered forever
Without CLAUDE.md, every new session starts blank. You re-explain the stack, remind Claude which folders to use, and clarify naming conventions. With CLAUDE.md, all of that is already there — Claude reads it before your first message.
- No re-explaining the stack on every session
- Consistent file locations and naming
- Conventions followed without repeating yourself
Before vs after CLAUDE.md
Same task, same Claude Code. The difference is entirely in what context is available at the start of the session.
| Without CLAUDE.md | With CLAUDE.md | |
|---|---|---|
| First response | Asks which framework, folder, and styling approach | Goes straight to code using project conventions |
| Component location | May create files in the wrong directory | Uses src/components/ as documented |
| Styling | Guesses CSS variables or Tailwind | Follows the Tailwind + ThemeProvider pattern |
| Session overhead | Several clarifying questions before any code | Context loaded before your first message |
What to put in CLAUDE.md
Six categories cover the information Claude needs most. Add sections as your project grows — add a new entry the first time you find yourself repeating context.
| Section | Purpose | Example |
|---|---|---|
| Stack & framework | What technology the project uses | Next.js 15 App Router, TypeScript, Tailwind CSS, Prisma |
| Folder structure | Where things live | Components: src/components/, API: src/app/api/ |
| Conventions | Naming, formatting, and code style | 'use client' only when needed; PascalCase components |
| Testing | Framework, file location, commands | Vitest in src/__tests__/; npm run test |
| Dev commands | Start, build, lint, type-check | Dev: npm run dev; Lint: npm run lint |
| What to avoid | Patterns or packages you do not want | No any type; do not modify prisma/schema.prisma without asking |
A real CLAUDE.md example
Here is a complete CLAUDE.md for a Next.js SaaS app. Use it as a template and trim what does not apply to your project.
This file sits at the project root alongside package.json. Claude reads it automatically at the start of every session.
Where CLAUDE.md files live
You can have more than one. Claude reads all of them and merges the context.
| Location | Scope | Use for |
|---|---|---|
| CLAUDE.md (project root) | Every session in this project | Stack, conventions, and dev commands |
| src/components/CLAUDE.md | When working inside that folder | Folder-specific rules, e.g. component library conventions |
| ~/.claude/CLAUDE.md | Every project on your machine | Personal preferences: code style, language, response format |
How to create it
Three approaches — all valid. Pick whatever fits your workflow.
- Ask Claude to write it. Open a session in your project and ask it to inspect
package.json, folder structure, and config files, then generate a CLAUDE.md at the root. - Use the /init command. Type
/initin the prompt box. Claude scans the project and creates a first draft you can edit. - Write it by hand. Create
CLAUDE.mdat the project root in any text editor. Plain Markdown — no special syntax.
Keeping it up to date
CLAUDE.md is a living document. The right time to update it is the moment you notice yourself re-explaining something to Claude.
| Signal | What to add |
|---|---|
| You added a new package | Add it to the Stack section with a one-line description |
| You corrected Claude on where to put a file | Update the Folder Structure section with the correct path |
| Claude used a pattern you do not want | Add it to Avoid with the preferred alternative |
| You have a new npm script the team uses daily | Add it to Commands so Claude can run it correctly |
| A new convention was agreed in a code review | Add it to Conventions so Claude follows it from now on |
Before you continue
- CLAUDE.md gives Claude permanent project context on every session.
- Cover stack, folder structure, conventions, commands, and things to avoid.
- Place it at the project root; subdirectory and global files work too.
- Use /init or ask Claude to generate a first draft, then refine by hand.
- Next lesson: Settings and Configuration.
What's Next
CLAUDE.md gives Claude your project context on every session. Next: settings.json — model selection, auto-approval rules, and tool configuration.