What is CLAUDE.md? Persistent Memory That Transforms Claude Code Sessions

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:

1. Context is lost - Claude doesn't remember you're using Next.js 15 with App Router
2. Assumptions are made - Claude might suggest REST endpoints when you use server actions
3. Time is wasted - You spend the first 5 messages explaining your stack
4. 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:

# 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:

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:

# 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:

# 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:

/init

Claude will:

1. Analyze your codebase - detect framework, dependencies, file structure
2. Infer conventions - understand your testing setup, API patterns, styling approach
3. 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:

## Documentation References

- API conventions: @/docs/api-guide.md
- Component patterns: @/docs/component-library.md
- Database schema: @/docs/database-schema.md

When Claude sees this, it knows to pull context from those files when relevant.

4. Keep It Focused and Scannable

CLAUDE.md isn't a dump of every possible detail. Think of it as a cheat sheet for Claude.

Good:

## Stack
- Next.js 15 (App Router)
- Tailwind CSS
- Drizzle ORM

Bad:

## 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.

Real-World Pattern: Routing Models Inside CLAUDE.md

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:

## 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:

1. 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.
2. 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:

Use them together:

• 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

Related Reading on explainx.ai

• OpenAI Codex plugin for Claude Code — full setup guide — /codex:review, /codex:rescue, and Theo-style model routing from CLAUDE.md
• Karpathy-inspired Claude Code guidelines - The viral 100k-star CLAUDE.md and its four behavioral principles
• What is MEMORY.md? The Long-Term Brain for AI Agents - Deep dive on the broader agent memory pattern
• DESIGN.md: the open spec that teaches AI design intent - How to give Claude semantic design system knowledge
• What are agent skills? A complete guide - Understanding SKILL.md and reusable workflows
• What is MCP? Model Context Protocol explained - How agents connect to tools and data

Bottom Line

CLAUDE.md is the difference between treating Claude Code as a chatbot and treating it as a teammate.

Without it, every session starts from zero. With it, Claude remembers your stack, follows your conventions, and works the way you work.

The investment is 5 minutes to run /init and refine the output. The return is never having to re-explain your project again.

If you're using Claude Code on a real project, you owe it to yourself to add CLAUDE.md today.

Explore CLAUDE.md in action: Check out explainx.ai's open-source codebase to see how we use project-level and user-level memory files in production.