CLAUDE.md: The File That Makes Every Claude Code Session Instantly Context-Aware
Every time you start a new Claude Code session, you start from zero.
Claude does not remember your project conventions. It does not know that you never use var, that your API routes follow a specific pattern, or that the payments module should never be touched without a migration file. You have to re-explain all of it, every session.
Or you write it down once in a CLAUDE.md file.
CLAUDE.md is a plain markdown file that Claude Code reads automatically at session start. Everything in it becomes part of Claude's working context before you type a single message. Your conventions, your commands, your architecture notes - all of it, instantly loaded.
Here is how I structure mine and why each section earns its place.
What CLAUDE.md Actually Does
When you open Claude Code in a directory, it looks for a CLAUDE.md file in:
- The current directory
- Parent directories up to the repo root
-
~/.claude/CLAUDE.md(global, loaded in every session)
Each one is read and combined. A project-level CLAUDE.md gives project-specific context. A subdirectory-level CLAUDE.md gives component-specific context. The global one sets defaults you want everywhere.
The content lands in Claude's context before your first message. No prompting. No setup. You open the session, and Claude already knows your stack.
Section 1: Project Overview (4-5 Lines Maximum)
This is not documentation. This is the briefing.
# MyStore - Ecommerce Platform
Shopify headless frontend (Next.js 14) with custom Node.js API layer.
Primary stack: TypeScript, Prisma, PostgreSQL, Redis.
Production: Vercel (frontend) + Railway (API). Staging: same stacks, separate instances.
Owner: [your name]. Primary contact for infra questions: [name].
Four lines. That is all Claude needs to orient itself to your system. More than that and it becomes documentation that nobody reads, including Claude.
The key elements: what it is, what it runs on, where it lives. That context changes how Claude approaches every problem.
If you want a complete CLAUDE.md template I use across multiple projects, it is in the free Claude Code toolkit below.
[Get the CLAUDE.md template + full Claude Code toolkit - free]
Section 2: Commands
The most underused section. Most developers do not put this in CLAUDE.md and then spend two minutes per session reminding Claude how to run the project.
## Commands
- Dev server: `npm run dev` (port 3000)
- Tests: `npm test` (Jest, watch mode by default)
- Test single file: `npx jest path/to/test.spec.ts`
- Build: `npm run build`
- DB migrations: `npx prisma migrate dev`
- DB seed: `npx prisma db seed`
- Lint: `npm run lint` (ESLint + Prettier)
- Type check: `npx tsc --noEmit`
Eight lines. Claude now knows exactly how to run, test, and build your project without asking. It can run these commands on its own during sessions to verify its work.
The pattern that matters most: include the migration command. Claude should run migrations whenever it changes the schema, not assume you will do it manually.
Section 3: Architecture Notes
Not a full architecture document. Just the things that would surprise someone who opened the codebase cold.
## Architecture
- API layer is in `/api` (Express). Frontend in `/app` (Next.js).
- Do not mix frontend and API imports. They deploy separately.
- Auth: JWT stored in httpOnly cookies. Never localStorage.
- Payments: Stripe webhook handler in `/api/webhooks/stripe.ts`. Never touch this without a migration file.
- Feature flags: LaunchDarkly. Never hardcode feature state.
- Caching: Redis for session + rate limiting. Invalidate on user data changes.
Six lines that prevent six categories of mistakes. Claude will not accidentally mix API imports into the frontend. It will not store tokens in localStorage. It will not touch the webhook handler without checking for migration needs.
These notes pay for themselves the first time Claude almost does something you have explicitly said not to do.
Section 4: Code Conventions
Not style preferences. Decisions that need to be consistent across the codebase.
## Conventions
- TypeScript strict mode. No `any`. No `ts-ignore`.
- All API endpoints return `{ data, error, meta }`. Never raw objects.
- Database queries go in `/api/db/` repository files, not in route handlers.
- Error handling: use the `AppError` class in `/api/errors`. Never raw `throw new Error()`.
- All new functions need JSDoc only if the WHY is non-obvious. No mandatory docs.
- Branch names: `feature/`, `fix/`, `chore/`. Never work directly on `main`.
Six conventions. Claude will follow them automatically in every session without being reminded. New files will match your existing patterns.
The most important one for Claude Code specifically: the error handling convention. Claude tends to reach for throw new Error() by default. If you have a custom error class, specify it explicitly.
Section 5: Known Issues / Do Not Touch
This is the safety section. Things that are broken, in progress, or deliberately not fixed.
## Known Issues / Constraints
- `/api/legacy/orders.ts` - do not refactor. Rewrite in progress on `feature/orders-v2`.
- `SearchBar` component has a known re-render issue. Fix tracked in issue #145. Leave it.
- Stripe integration is on API v2023-10-16 intentionally. Do not upgrade without testing webhooks.
- The `utils/date.ts` file looks redundant but it handles the Israeli timezone edge case. Do not delete.
These four lines prevent four debugging sessions. Claude will not helpfully refactor the file that is being rewritten on another branch. It will not upgrade the Stripe API version. It will not delete the utility file that looks unused but handles a real edge case.
This section is worth more than any other section in the file.
The first four sections handle what Claude knows. The fifth handles what Claude should avoid. Together, they make every session coherent from the first message.
Multi-Level CLAUDE.md: The Pattern That Scales
For larger projects, one file in the root is not enough. The solution is multiple CLAUDE.md files at different levels.
my-project/
CLAUDE.md # project-level context
api/
CLAUDE.md # API-specific conventions
frontend/
CLAUDE.md # frontend-specific conventions
payments/
CLAUDE.md # payments module - extra caution notes
When Claude Code is working inside /api, it reads the root CLAUDE.md plus the /api/CLAUDE.md. The subdirectory file adds context without duplicating the root file.
The pattern I use:
- Root
CLAUDE.md: project overview, commands, global conventions - Subdirectory
CLAUDE.md: module-specific conventions, gotchas, known issues - Global
~/.claude/CLAUDE.md: personal preferences that apply everywhere (preferred file structure, output style)
This scales cleanly. New engineers joining the project get full context when they open Claude Code in any directory.
Building Yours: The 30-Minute Version
If you have never written a CLAUDE.md, here is the fastest path.
Open a session with Claude Code and type:
Read through the project structure and the last 20 git commits. Draft a CLAUDE.md covering: project overview, commands, architecture decisions you can infer, and any patterns you see in the codebase.
Claude will produce a draft in three minutes. Review it. Add the "do not touch" section manually - that knowledge lives in your head, not in the codebase. Remove anything that is outdated.
You now have a working CLAUDE.md. The next session will feel different immediately.
The Actual Payoff
A well-written CLAUDE.md does two things.
First, it eliminates the setup tax on every session. No more re-explaining your stack. No more reminding Claude of your conventions. You open a session and go directly to work.
Second, it forces you to articulate things you have been keeping in your head. The constraints, the gotchas, the architectural decisions that felt obvious when you made them but that nobody else would know. Writing them down for Claude makes them available to every new team member and to future-you starting a session months from now.
The file takes 30 minutes to write and pays back that time in the first week.
Want the full template? The Claude Code toolkit includes a CLAUDE.md template for three project types: solo ecommerce, SaaS API, and content operations. All three are tested on real projects.
[Download the Claude Code toolkit with CLAUDE.md templates - free]
What to Read Next
CLAUDE.md is context management. To see what you can build once context is locked in:
- Claude Code Memory Files: The Workflow That Eliminated My Daily Briefing Ritual
- 5 Claude Code Skills That Run My Entire Ecommerce Operation
Context is the foundation. Skills and hooks are what you build on top of it.
Top comments (0)