The Problem
Every time you start a new Claude Code session, Claude starts fresh. It doesn't remember the conversation you had yesterday, your project's coding conventions, or that you always use tabs instead of spaces.
That's where CLAUDE.md files come in. They give Claude persistent memory about your project.
What Is a CLAUDE.md File?
A CLAUDE.md file is a plain markdown file that Claude automatically reads at the start of every session. You put instructions, context, and rules in it, and Claude follows them without you having to repeat yourself.
Think of it as a briefing document. Instead of telling a new team member the same things every day, you write it down once and they read it every morning.
Project Memory
The most common CLAUDE.md file lives in the root of your project:
# My Project
## Build System
- Run `npm run dev` for development
- Run `npm run build` for production
- Tests: `npm test`
## Conventions
- Use TypeScript for all new files
- Components go in src/components/
- Always use named exports, never default exports
## Important Notes
- The API key is stored in .env (never commit this)
- The database schema is in prisma/schema.prismaSave this as CLAUDE.md in your project root. Next time you start Claude Code in that directory, it reads this file automatically and follows your instructions.
Global Memory
You can also create a global CLAUDE.md that applies to all your projects. This lives in your home directory:
~/.claude/CLAUDE.mdUse this for personal preferences that apply everywhere:
# Global Preferences
- Always use single quotes in JavaScript
- Prefer functional components over class components
- Never auto-commit changes without asking me first
- Use bun instead of npmHow Claude Reads Memory
When you start a Claude Code session, here's the order:
- Global CLAUDE.md is loaded first (your personal defaults).
- Project CLAUDE.md is loaded next (project-specific rules override globals).
Project rules take priority. If your global says "use npm" but your project says "use bun," Claude will use bun for that project.
What to Put in CLAUDE.md
Here are the most useful things to include:
- Build commands. How to run, build, and test the project.
- File structure. Where things live and why.
- Coding conventions. Naming, formatting, patterns you follow.
- Important context. Architecture decisions, known issues, things to avoid.
- Workflow rules. "Always run tests before committing" or "never push to main directly."
Auto-Memory
Claude Code can also write its own memory. When you tell Claude to "remember this for next time" or it learns something important about your project, it can save notes to its memory directory at ~/.claude/projects/.
This auto-memory works alongside your CLAUDE.md files. You write the rules, Claude adds the notes it picks up along the way.
A Real Example
Here's a CLAUDE.md from a real Next.js project:
# E-Commerce Store
## Stack
- Next.js 14 with App Router
- Tailwind CSS for styling
- Prisma + PostgreSQL for data
- Stripe for payments
## Commands
- `npm run dev` starts the dev server on port 3000
- `npx prisma studio` opens the database GUI
- `npm run seed` resets and seeds the database
## Rules
- All API routes go in app/api/
- Use server components by default, client only when needed
- Always validate form inputs with Zod schemas
- Product images are stored in public/products/With this in place, Claude knows your stack, your commands, and your rules from the very first message of every session.
What You Learned
CLAUDE.md files are the single most impactful thing you can do to make Claude Code work better for you. Write one for your project, and you'll never have to explain your setup twice.
Ready to build something? Put everything you've learned into practice.
