What is CLAUDE.md? Persistent Memory That Transforms Claude Code Sessions
Discover CLAUDE.md: the persistent memory file that turns Claude Code from a forgetful assistant into a context-aware teammate. Learn the hierarchy, best practices, and how to use /init to generate one.
Update — July 5, 2026: Added coverage of the viral andrej-karpathy-skills CLAUDE.md and how developers like Theo (t3.gg) use CLAUDE.md to route tasks across multiple models — see the two new sections below.
Update — July 9, 2026: Anthropic launched Claude Reflect — usage patterns and 4D AI Fluency in Settings; requires Memory on (same persistence layer CLAUDE.md complements in Claude Code).
One of the most powerful—and underused—features of Claude Code is the CLAUDE.md file. It's the difference between a frustrating session where you constantly repeat yourself and a productive flow where Claude already knows your stack, your conventions, and your preferences.
When you open Claude Code without a CLAUDE.md file, it's like hiring a new contractor every single day. Claude has to:
Re-explore your codebase from scratch
Make assumptions about your dependencies
Guess at features you've already implemented
Figure out your coding style and preferences
But with CLAUDE.md, Claude gets an onboarding script that runs automatically every session.
The Core Problem CLAUDE.md Solves
Every time you start a new Claude Code session without persistent memory:
Context is lost - Claude doesn't remember you're using Next.js 15 with App Router
Assumptions are made - Claude might suggest REST endpoints when you use server actions
Time is wasted - You spend the first 5 messages explaining your stack
Corrections repeat - You tell Claude "use Tailwind, not inline styles" for the 10th time
CLAUDE.md fixes this by appending its contents to your prompt automatically at the start of every session.
What Goes Inside CLAUDE.md
A well-structured CLAUDE.md acts as semantic context that shapes how Claude understands and works with your codebase.
Here's a real-world example from a Next.js 15 project:
markdown
# Project Context## Stack- Next.js 15 (App Router)
- TypeScript
- Tailwind CSS
- Drizzle ORM
- PostgreSQL
## Commands- Dev server: `npm run dev`- Run tests: `npm test`- Lint: `npm run lint`## Code Style- Use two-space indentation
- Prefer named exports over default exports
- All API routes go in `app/api/`- Use server actions instead of API routes where possible
## Architecture Decisions- Authentication uses NextAuth.js v5
- Database migrations run via Drizzle Kit
- Client components marked with "use client" only when necessary
- Prefer server components by default
If Claude Code reads this at session start, it immediately knows:
How to run your dev server
What CSS framework to use for styling
Where API routes live
When to use server actions vs API endpoints
The Memory Hierarchy: Project vs User Level
Claude Code supports two levels of CLAUDE.md files depending on who they're for:
Level
Location
Purpose
Share with team?
Project-level
<project-root>/CLAUDE.md
Stack, conventions, architecture decisions for THIS project
Yes - commit to Git
User-level
~/.claude/CLAUDE.md
Your personal coding preferences across ALL projects
No - keep local
Project-Level CLAUDE.md
Lives in the root directory of your repo alongside README.md and package.json.
What to include:
Project stack and dependencies
Dev/build/test commands
API conventions
Architecture decisions
File structure and organization
Team-wide coding standards
Example:
markdown
# explainx.ai Project## Stack- Turborepo monorepo
- Next.js 15 (App Router) in apps/web
- Tailwind + shadcn/ui components
- Drizzle ORM + PostgreSQL
- Deployed on Vercel
## Commands- Install: `pnpm install`- Dev: `pnpm dev`- Build: `pnpm build`- Test: `pnpm test`## Conventions- Use server actions for mutations (not API routes)
- Components live in `apps/web/components/`- Shared utilities in `packages/utils/`- Database schema in `apps/web/db/schema.ts`
User-Level CLAUDE.md
Lives in ~/.claude/CLAUDE.md (your Claude Code config folder).
What to include:
Your personal coding style preferences
Formatting rules you always want
Tools and libraries you prefer
Your preferred comment style
Personal shortcuts and aliases
Example:
markdown
# Personal Preferences (Yash)## Coding Style- Always use functional components (never class components)
- Prefer const arrow functions over function declarations
- Use descriptive variable names, avoid abbreviations
- Add JSDoc comments for exported functions only
## Libraries I Prefer- Date handling: date-fns (not moment)
- Forms: react-hook-form + zod
- State: React Query for server state, Zustand for client state
- Testing: Vitest + Testing Library
## Never Do- Don't use any/unknown without explicit reason
- Don't add console.logs (use proper logging)
- Don't create barrel exports (index.ts re-exports)
This travels with you across all your projects and keeps your personal style consistent.
The /init Command: Auto-Generate Your CLAUDE.md
Don't want to write CLAUDE.md from scratch? Claude Code has you covered.
Run this command in any Claude Code session:
bash
/init
Claude will:
Analyze your codebase - detect framework, dependencies, file structure
Infer conventions - understand your testing setup, API patterns, styling approach
Generate CLAUDE.md - create a comprehensive file based on what it found
You can then review and refine it before committing to your repo.
Best Practices for Using CLAUDE.md
1. Start Without One (Then Add It)
Counter-intuitive but effective: when starting a new project, don't create CLAUDE.md immediately.
Instead:
Work with Claude Code for a few sessions
Notice when you repeatedly correct Claude
Track what context you keep re-explaining
Then create CLAUDE.md with only the necessary information.
Why? This keeps your CLAUDE.md compact and high-signal. You avoid bloating it with assumptions that may not matter.
2. Explicitly Ask Claude to Save to Memory
When you have to course-correct Claude during a session, say:
"Always use server actions instead of API routes. Save this to memory."
Claude will update your CLAUDE.md file with this preference so it persists across sessions.
3. Reference Docs with the @ Symbol
If you have project docs you want Claude to always reference, add them to CLAUDE.md:
## Stack
We are using Next.js version 15 which was released in October 2024
and includes many new features such as improved caching, better image
optimization, and support for React 19 canary. We chose Next.js because...
[500 more words of rationale]
Claude doesn't need the history lesson—just the facts.
5. Update It as the Project Evolves
CLAUDE.md is living documentation. When you:
Adopt a new library
Change an architecture decision
Add a new convention
Update CLAUDE.md immediately. This keeps it accurate and prevents Claude from working with stale assumptions.
The Karpathy CLAUDE.md Phenomenon
In early 2026, a single CLAUDE.md file became one of the most-starred repositories on GitHub — proof of how much leverage a well-written project instruction file carries.
The story: Andrej Karpathy posted a widely-read thread about recurring LLM coding failures — models making silent assumptions instead of surfacing uncertainty, overengineering simple requests, and making collateral edits to code outside the scope of the task. The next day, developer Forrest Chang packaged a counter-policy as a single CLAUDE.md file (plus a companion Claude Code plugin) under the repo name andrej-karpathy-skills. No code, no dependencies, no build step — just one markdown file with four behavioral rules. It went on to collect well over 100,000 GitHub stars.
The four principles it encodes are a useful template for any project's own CLAUDE.md:
The last one matters most in practice: instead of "add validation," the file pushes you to write "add a failing test that reproduces the invalid-input case, then make it pass." Claude Code is strong at looping until a specific, checkable goal is met — weak instructions waste that strength.
You can install it as a Claude Code plugin (/plugin marketplace add forrestchang/andrej-karpathy-skills) or fold the raw file into your own CLAUDE.md with curl. Our full writeup — Karpathy-inspired Claude Code guidelines — covers install paths, tradeoffs, and how it pairs with domain-specific agent skills.
The lesson generalizes beyond this one repo: CLAUDE.md isn't just a stack-and-commands cheat sheet. It's also the place to encode behavioral defaults — how cautious to be, when to ask versus assume, and what "done" looks like.
CLAUDE.md can also tell Claude Code how to delegate work to other models, not just how to work with Claude itself. Theo (t3.gg) shared a section of his CLAUDE.md that does exactly this — a live example of model-routing logic living directly in project memory instead of being decided ad hoc every session.
The pattern ranks models on three axes — cost, intelligence, and "taste" (UI/UX judgment, code quality, API design, copy) — and then gives explicit rules for which axis wins when they conflict:
markdown
## Picking the right models for workflows and subagents
Rankings, higher = better. Cost reflects what I actually pay (OpenAI has
really generous limits), not list price. Intelligence is how hard a
problem you can hand the model unsupervised. Taste covers UI/UX, code
quality, API design, and copy.
| model | cost | intelligence | taste |
|----------|------|---------------|-------|
| gpt-5.5 | 9 | 8 | 5 |
| sonnet-5 | 6 | 5 | 7 |
| opus-4.8 | 4 | 8 | 8 |
| fable-5 | 2 | 9 | 9 |
How to apply:
- These are defaults, not limits. You have standing permission to
override them: if a cheaper model's output doesn't meet the bar,
rerun or redo the work with a smarter model without asking. Judge the
output, not the price tag. Escalating costs less than shipping
mediocre work.
- Cost is a tie-breaker only; when axes conflict for anything that
ships, intelligence > taste > cost.
- Bulk/mechanical work (clear-spec implementation, data analysis,
migrations): gpt-5.5 — it's very cheap and token efficient.
- Anything user-facing (UI, copy, API design) needs taste ≥ 7.
- Reviews of plans/implementations: fable-5 or opus-4.8, optionally
gpt-5.5 as an extra independent perspective.
- Never use Haiku.
- Mechanics: gpt-5.5 is handled natively via the `openai/codex-plugin-cc`
plugin inside Claude Code, automatically adopting your user-level
configurations from `~/.codex/config.toml`. Avoid writing custom bash
scripts; instead, utilize the plugin's built-in tools and skills:
-`/codex:review` — Run non-destructive, read-only code quality
assessments. Supports `--base <ref>` for branch analysis.
- `/codex:adversarial-review` — Perform a skeptical design review to
pressure-test tradeoffs, auth, and reliability. Append custom focus
text at the end of the command to steer the focus.
- `/codex:rescue` — Subcontract active debugging, multi-file
refactoring, or implementation loops to Codex when a second pass is
required.
- `/codex:status` / `/codex:result` / `/codex:cancel` — Use these to
check, fetch, or abort asynchronous jobs when using the
`--background` flag on heavy tasks.
- Claude models (sonnet-5, opus-4.8, fable-5) run via the Agent/Workflow
model parameter.
Using gpt-5.5 inside workflows and subagents:
- Subagents and automated workflows should call the plugin's native
slash commands or its exposed `codex-cli-runtime` skills to delegate
tasks directly, omitting the need for raw terminal wrappers.
- For closed-loop quality assurance, keep the review gate turned on via
`/codex:setup --enable-review-gate`. This ensures a stop hook
automatically challenges Claude's outputs using Codex before
finalizing, preventing broken code or weak design assumptions from
reaching the main session unvetted.
Two mechanics make this actually work in Claude Code:
Claude Code's own model parameter only accepts Claude models. To route work to a non-Claude model (gpt-5.5 via Codex, in Theo's setup), the cleanest path isn't a hand-rolled bash wrapper — it's a dedicated plugin (openai/codex-plugin-cc) that exposes Codex as native slash commands (/codex:review, /codex:adversarial-review, /codex:rescue) and inherits your existing ~/.codex/config.toml defaults.
The rules live in CLAUDE.md, not in your head. Because the routing logic and the specific commands are written down once, every session — and every subagent Claude Code spawns — inherits the same defaults without you re-deciding it each time. A /codex:setup --enable-review-gate stop hook can even enforce it automatically, having Codex challenge Claude's output before a task is considered done.
This is the same principle behind the Karpathy file applied to a different problem: instead of encoding how carefully to code, it encodes which model should do the coding. Both are examples of CLAUDE.md as a durable policy layer rather than a one-time onboarding doc.
CLAUDE.md vs Other .md Conventions
The .md ecosystem has exploded in 2026. Here's how CLAUDE.md fits in:
CLAUDE.md tells Claude how to work on your codebase
DESIGN.md tells Claude how to apply your design system
SKILL.md tells Claude what reusable workflows are available
README.md tells humans how the project works
Real-World Example: Before and After CLAUDE.md
Without CLAUDE.md (Session 1)
You: "Add a form to create a new blog post"
Claude: "I'll create an API route at /api/posts..."
You: "No, we use server actions, not API routes"
Claude: "Got it, let me create a server action..."
You: "Also, use Tailwind for styling, not inline styles"
Claude: "Updated to use Tailwind..."
Without CLAUDE.md (Session 2 - Next Day)
You: "Add validation to the blog post form"
Claude: "I'll create an API route to handle validation..."
You:[sighs] "We use server actions, remember?"
With CLAUDE.md (Every Session)
You: "Add a form to create a new blog post"
Claude: "I'll create a server action in app/actions/posts.ts with zod validation and use Tailwind for the form styling..."
You: "Perfect."
That's the power of persistent memory.
When NOT to Use CLAUDE.md
CLAUDE.md isn't always necessary. Skip it for:
Quick prototypes - If you're just testing an idea for an hour
Tutorial projects - Following a guide that provides all context
Single-file scripts - No need for project memory on a standalone script
But for any project you'll work on more than once, CLAUDE.md pays for itself immediately.
Getting Started Checklist
Ready to add CLAUDE.md to your workflow? Here's your action plan:
Run /init in your current project
Review the generated CLAUDE.md and refine it
Commit project-level CLAUDE.md to Git
Create user-level CLAUDE.md in ~/.claude/ for personal preferences
During your next session, notice what Claude remembers vs what you need to explain
Update CLAUDE.md when you correct Claude on conventions
Add doc references with @ symbol for key project files
