Stop re-explaining the same things to Claude Code every session. There is a single file that fixes this permanently — and once you set it up, everything changes.

🎯 What Is CLAUDE.md?

CLAUDE.md is a markdown file that acts as permanent memory for your project. Every time you start a new Claude Code session, Claude automatically reads this file before doing anything else.

Think of it as a brain that persists between sessions.

Inside it you can store:

  • Your tech stack and frameworks
  • Coding preferences and conventions
  • Architecture decisions
  • Naming conventions
  • Folder structure
  • Common patterns you use
  • Mistakes to avoid
  • Project-specific rules

Anything you would normally have to repeat every time you open a new chat — it goes in here.

💡 Why It Matters

Without CLAUDE.md, every session starts from scratch. Claude has zero memory of what you told it yesterday. That means you waste tokens, repeat yourself, and run into the same mistakes over and over.

With CLAUDE.md, Claude picks up exactly where you left off. No re-explaining. No wasted tokens. No repeated errors.

It is the difference between working with a brand new assistant every day versus working with someone who already knows your entire project inside and out.

📂 Where Does It Go?

The file lives in the root of your project directory.

your-project/
├── CLAUDE.md       ← right here
├── src/
├── package.json
└── ...

Claude Code reads it natively from this location. No configuration needed. No setup flags. Just drop the file in the root and it works.

🛠️ How To Set It Up

You do not need to write this file manually. In fact, you should not. Here is the better way.

Step 1: Start a Plan Mode Conversation

Open your project in Claude Code, Cursor, Antigravity, or whatever IDE you are using. Start a plan mode conversation where you go back and forth with Claude about what you are building.

Discuss the architecture. Talk through the stack. Explain the goals. Go back and forth until you have a solid plan.

Step 2: Tell Claude To Create the CLAUDE.md File Itself

Once you have a solid plan, say something like:

"Now create a CLAUDE.md file based on everything we just discussed. Include the tech stack, architecture, conventions, and any decisions we made."

Claude already knows your entire codebase and everything you just discussed. It writes a far better memory file than you ever could manually because it has full context of the project.

Step 3: Review and Refine

Open the file and scan through it. If anything is missing or off, tell Claude to update it. The file is yours to shape — Claude just gives you a massive head start.

🔧 How It Works in Claude Code

Claude Code reads CLAUDE.md automatically at the start of every session. You do not need to reference it or attach it. It just works.

You can also use these built-in slash commands to manage it:

  • /init — Creates a starter CLAUDE.md file for your project
  • /memory — Opens your CLAUDE.md for direct editing inside Claude Code

Every session starts smarter because Claude already knows your project before you type a single word.

🖥️ How It Works in Cursor, Antigravity, and Other Tools

If you are using an AI IDE like Cursor or Antigravity instead of the Claude Code terminal, the same concept applies.

  • In Cursor, you can reference CLAUDE.md as context in your prompts or add it to your project rules so the AI assistant picks it up automatically every session.
  • In Antigravity, the file sits in your project root and you can point the assistant to it as persistent context.
  • In any other AI coding tool, CLAUDE.md works as a universal project reference file. Just include it in your context window or rules configuration.

The file is not locked to Claude Code. It is a standard markdown file that any AI tool can read. The conventions and context inside it make any AI assistant smarter about your project.

🔄 How To Update It During Your Project

This is the real unlock.

CLAUDE.md is not a static file you write once and forget. It is a living document that evolves with your project.

Here is how it works in practice:

When Claude Makes a Mistake

Let's say Claude uses the wrong import path. Or it structures a component in a way that breaks your pattern. You catch it and Claude fixes it.

At that point, just say:

"With that fix you just created, update your CLAUDE.md so you don't make that same mistake twice."

Claude will open the file, add the lesson, and save it. Next session, it already knows. The mistake never happens again.

When You Make a New Decision

Switched from REST to GraphQL? Changed your folder structure? Decided on a new naming convention? Just tell Claude:

"Update CLAUDE.md to reflect that we are now using GraphQL instead of REST for all API calls."

The file stays current with every decision you make.

When You Learn Something New About Your Project

Maybe you discover that a certain library has a quirk. Or a specific API endpoint behaves differently than expected. Tell Claude to log it:

"Add to CLAUDE.md that the Stripe webhook endpoint requires idempotency keys or it will duplicate charges."

Now every future session knows this before touching that part of the code.

⚡ What a Good CLAUDE.md Looks Like

Here is a simplified example structure:

# Project: ClientFlow CRM

## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Supabase (auth + database)
- Stripe (payments)

## Architecture
- All API routes in /app/api/
- Server components by default, client components only when needed
- Zustand for client state management

## Conventions
- Use named exports, not default exports
- All components in PascalCase
- All utility functions in camelCase
- Error handling with custom AppError class

## Known Issues
- Supabase RLS policies must be updated manually after schema changes
- Stripe webhook requires idempotency keys
- Do NOT use dynamic imports for auth-related components

## Recent Fixes
- Fixed: Was importing from @/lib/utils instead of @/utils — always use @/utils
- Fixed: Tailwind dark mode classes must use 'class' strategy, not 'media'

Yours will be longer and more detailed. That is the point. The more context Claude has, the better it performs.

🚀 Start Now

The fastest way to set this up:

  1. Open your project in Claude Code or your AI IDE
  2. Have a plan mode conversation about what you are building
  3. Tell Claude to create the CLAUDE.md file based on everything discussed
  4. Every time Claude makes a mistake and fixes it, tell it to update the file
  5. Watch the file evolve and your sessions get smarter over time

One file. Permanent memory. No more repeating yourself.

Want more Claude Code tips? Follow @promptible for daily AI tutorials.