CLAUDE.md Mastery — The Game Changer

There is a single file that separates developers who get consistent, high-quality output from Claude from developers who get variable, generic output. That file is CLAUDE.md.

This page teaches you what it is, why it matters more than any prompt, and how to write one that transforms every Claude session in your project.

What CLAUDE.md Is

CLAUDE.md is a plain Markdown file that you place at the root of your project. Claude Code reads it automatically at the start of every session, before you type a single message.

It is your project's permanent context document. Everything Claude needs to know about your project — your stack, your conventions, your rules, your patterns — lives here.

The simple version: Without CLAUDE.md, every Claude session starts blank. With CLAUDE.md, every Claude session starts knowing exactly what kind of project this is and how it should behave.

The Excel analogy: Imagine you hire a new accountant every single day and they work on your Excel model. Without a briefing document, you spend the first hour every day explaining your chart of accounts, your naming conventions, your formula patterns, and your client's specific requirements. With a briefing document, they pick it up and start working immediately. CLAUDE.md is that briefing document — except Claude reads it perfectly, every time, in milliseconds.

Why It Matters — The Memory Problem

Claude Code has no persistent memory between sessions. When you close Claude and reopen it tomorrow:

• It does not know your project is built with Supabase
• It does not know you use React Query for data fetching
• It does not know your button component lives in a specific file
• It does not know you never use any in TypeScript
• It does not know you soft-delete instead of hard-delete
• It does not know you commit with imperative mood messages

Without CLAUDE.md, you re-explain all of this every session. You get inconsistent output. Components do not match your style. Patterns contradict each other. The 50th session is no better than the first.

With CLAUDE.md, all of this knowledge is loaded at session start. Claude inherits your project's DNA. The 50th session builds on everything that came before.

The Self-Update Rule — The Most Powerful Feature

The best CLAUDE.md files are not written once. They are maintained by Claude itself.

Add an instruction to your CLAUDE.md that tells Claude to update the file whenever a new architectural decision is made, a new convention is established, or a new pattern is introduced.

With this rule in place, as you build your project:

• Every architectural decision gets recorded automatically
• Every convention you establish gets documented
• Your CLAUDE.md grows richer with every session
• Future sessions benefit from every previous session's learning

This is compounding knowledge. Every session makes the next one better.

The Structure of a Good CLAUDE.md

Here is the anatomy of a CLAUDE.md that actually works. A strong one has: a Quick Commands section (the exact terminal commands to start the dev server, run the build, and check types), a Tech Stack table, a Project Structure summary, User Roles and Routes, and a set of Hard Rules Claude must never break.

A Real Example: Udyogaseva's CLAUDE.md

The Udyogaseva platform — the real-world platform used throughout this training — has a CLAUDE.md that demonstrates everything above in production use. Here is what it contains and why each section exists:

Hard Rules section (first thing Claude reads): Eight non-negotiable rules that Claude must follow on every task. These include: always use matching skill files, never ask the user to run Supabase migrations (Claude does it directly), backend deploys before frontend always, cross-platform parity is mandatory (web and mobile must match). These rules prevent the most expensive mistakes before they happen.

Skill Protocol table: A lookup table mapping task keywords to skill files. "Build, add, create, implement" → use the /new-feature skill. "Fix, bug, broken, error" → use the /bug-fix skill. Every task type has a pre-written instruction set that Claude loads before starting.

Tech Stack table: Every layer of the stack listed with exact version numbers — React 18.3, TypeScript 5.8, Vite 5.4. Claude uses these to know which APIs and patterns are appropriate for the exact versions in use.

Project Structure diagram: A folder tree showing where everything lives — all 50+ UI components, all 13 admin hooks, the mobile app directory, the edge functions, the migrations folder. Before reading a file, Claude knows where to look.

User Roles and Route Map: A table showing which routes are accessible to which roles and what guards are applied. When Claude writes a new page, it knows whether to add a role guard and which roles it should accept.

Database Schema: Every table with its purpose. When Claude writes a query, it knows the table name and what it stores. No guessing at table names or column structures.

Test Accounts: Real credentials for each role. Claude uses these to actually sign into the app and verify that features work end-to-end, not just that the code compiles.

Architecture and Data Flow: A description of how data moves through the system — Supabase → React Query → AuthContext → Components. Claude always follows this pattern when writing new data-fetching code.

Decision Log: A running log of every significant decision made during development, with dates and reasoning. When a new session starts, Claude can read the history of why things are the way they are.

The Udyogaseva CLAUDE.md is approximately 400 lines. That investment in documentation pays back every single session — a session that would take 30 minutes of re-explaining takes 2 minutes because Claude already knows everything.

Global vs Project CLAUDE.md

You have two levels of CLAUDE.md:

Global (~/.claude/CLAUDE.md): Applies to every project on your machine. This is where your personal developer profile lives — your preferences, your universal rules, your skill file list, your credential lookup process. It is loaded for every Claude session, regardless of which project you are in.

Project ([project-root]/CLAUDE.md): Applies only to the specific project. This is where project-specific context lives — your stack choices, your table names, your routes, your conventions for this app specifically.

How they interact: Both are loaded at session start. Project rules override global rules when they conflict. Global rules fill in everything not covered by project rules.

For beginners: Start with a project-level CLAUDE.md. You can add a global one later once you understand what belongs at each level. For now, put everything in the project file.

What Goes in CLAUDE.md vs What Does Not

Put in CLAUDE.md:

• Project description and goals
• Tech stack with versions
• File structure notes (where things live)
• Coding conventions and rules
• Database tables and their purpose
• User roles and route structure
• Quick commands to run the project
• Decisions you have made and why
• Test accounts (not passwords if the file is public — use placeholder text)
• Known issues and technical debt

Do NOT put in CLAUDE.md:

• API keys or secrets (these go in .env)
• Passwords (even test ones, if the repo is or might become public)
• Sensitive client data
• Large blocks of code (these go in skill files)
• Entire files pasted in (Claude can read files directly)

Exercise: Write Your First CLAUDE.md

You are about to start Project 1 — your personal profile website. Before you write a single line of code, create a CLAUDE.md at the root of your project.

As you build, add to this file. Every convention you establish, add it. Every decision you make, log it. By the time you finish Project 1, your CLAUDE.md will be a real document that reflects real decisions you made.

Common Mistakes

Mistake 1: Writing CLAUDE.md after the project is done

The value compounds over the lifetime of the project. Write it before you start. A CLAUDE.md written at the end captures decisions already made — it does not shape the decisions being made.

Mistake 2: Being vague

"Use React" tells Claude nothing useful. "React 18.3, functional components only, hooks not classes, React Query for all data fetching" gives Claude everything it needs.

Mistake 3: Never updating it

An outdated CLAUDE.md is worse than no CLAUDE.md — it gives Claude wrong information. Add the self-update rule and let Claude maintain it.

Mistake 4: Putting everything in the global file

If you put project-specific details in your global CLAUDE.md, every project inherits them — including wrong ones. Global = universal principles. Project = project-specific context.

Mistake 5: Treating it as optional

The developers who skip CLAUDE.md re-explain their project every session and wonder why Claude's output is inconsistent. The developers who invest in it wonder how everyone else tolerates the inconsistency.

• I understand what CLAUDE.md does — it gives Claude a persistent memory of my project across sessions
• I know the self-update rule: at the end of every session, ask Claude to update CLAUDE.md with today's decisions
• I know what belongs in CLAUDE.md: stack, conventions, rules, decisions, routes, tables
• I know what NEVER goes in CLAUDE.md: API keys, passwords, secrets — those go in .env only
• I understand global CLAUDE.md (~/.claude/) vs project CLAUDE.md (project root) and what goes in each
• I have written a CLAUDE.md for Project 1 before writing any code