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, clarify naming conventions. With CLAUDE.md, all of that is already there — Claude reads it before your first message.
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.
What to Put in CLAUDE.md
Six categories cover the information Claude needs most. Add sections as your project grows — a new entry the first time you find yourself repeating context.
Stack & framework
What technology the project uses. Claude won't guess the wrong library or framework.
Stack: Next.js 15 App Router, TypeScript, Tailwind CSS
Database: PostgreSQL via Prisma
Auth: NextAuth.js v5Folder structure
Where things live. Prevents Claude from creating files in the wrong place.
Components: src/components/
API routes: src/app/api/
Types: src/types/
Utils: src/lib/
Tests: src/__tests__/Conventions
Naming, formatting, and code style rules. Claude follows them without being asked.
Use 'use client' only when component needs state or browser APIs
No console.log in production code
All async functions should handle errors with try/catch
Component names: PascalCase. Hooks: useCamelCaseTesting
Framework, file location, and any testing conventions to follow.
Tests: Vitest, colocated in src/__tests__/
Run: npm run test
Watch: npx vitest --watch
Coverage: npx vitest --coverageDev commands
The commands to start, build, and lint the project — so Claude can run them correctly.
Dev server: npm run dev
Build: npm run build
Lint: npm run lint
Type check: npx tsc --noEmitWhat to avoid
Patterns, packages, or approaches you don't want Claude to use.
Do not use: any type, default exports from API routes
Do not install: moment.js (use date-fns)
Never modify: prisma/schema.prisma without asking firstA Real CLAUDE.md Example
Here is a complete CLAUDE.md for a Next.js SaaS app. It covers every category in one file. Use this 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.
CLAUDE.mdProject root (most common)
Read for every session in this project. Put your main stack, conventions, and commands here.
src/components/CLAUDE.mdSubdirectory
Read only when Claude is working inside that folder. Use for folder-specific rules — e.g. component library conventions that only apply to src/components/.
~/.claude/CLAUDE.mdHome directory (global)
Read in every project on your machine. Use for personal preferences that apply everywhere — preferred code style, language, response format.
How to Create It
Three approaches — all valid. Pick whatever fits your workflow.
Option 1 — Ask Claude to write it for you
Open a Claude session in your project and ask it to inspect the project and generate a CLAUDE.md. Claude reads your package.json, folder structure, and existing config files to produce an accurate file.
Option 2 — Use the /init command
Type /init in the Claude Code prompt box. Claude scans the project and creates a CLAUDE.md automatically. You can then edit it to add anything it missed.
Option 3 — Write it by hand
Create a CLAUDE.md file at the project root in VS Code. It is plain Markdown — any text editor works. Use the template from the section above as a starting point and trim what does not apply.
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 to the project | Add it to the Stack section with a one-line description of what it does |
| You corrected Claude on where to put a file | Add or update the Folder Structure section with the correct path |
| Claude used a pattern you do not want | Add it to the Avoid section with a note on the preferred alternative |
| You have a new npm script the team uses daily | Add it to the Commands section so Claude can run it correctly |
| A new convention was agreed on in a code review | Add it to the Conventions section so Claude follows it from now on |
CLAUDE.md Quick Reference
Place at project root
Alongside package.json — not inside src/
Use /init to generate it
Claude scans the project and writes the first draft
Plain Markdown
## headings, - bullets — no special syntax needed
Commit it to git
Shared with the whole team automatically
Subdirectory files work too
Folder-specific rules in that folder's CLAUDE.md
Update when you repeat yourself
That's the signal a new entry is needed
What's Next
CLAUDE.md gives Claude your project context on every session. The next lesson covers settings.json — model selection, auto-approval rules, and tool configuration.