CLAUDE.md Mastery
The most important file in your entire project. What it is, what to put in it, and how to write one that makes Claude 10x more useful from session one.
Every time you start a new Claude Code session, Claude reads this file first. Before it touches a single line of your code. Before it answers your first question. It reads CLAUDE.md.
This is the most important file you will write in any project.
The "Why First" Scenario
You hire a junior associate at your CA firm. Smart, qualified, eager to work. On their first day you give them a client file and say "help with the GST reconciliation."
Do they know your firm's billing format? No. Do they know you always keep backup copies before modifying any client document? No. Do they know your partner signs off on any figure above ₹10 lakhs before it goes to the client? No. Do they know to CC the partner on all client emails? No.
You could explain all of this every single morning. Or you could write an induction manual — a document that answers every "how do we do things here?" question before work begins.
CLAUDE.md is Claude's induction manual for your project.
Without it, every session starts cold. Claude has to guess your patterns, re-learn your tech stack, re-discover what you've already decided. With a good CLAUDE.md, every session starts warm — Claude already knows your project's structure, your rules, your decisions, and your preferences.
The Excel Analogy
In Excel, you can protect a workbook with a password and set permissions for which cells are editable. You can lock the template so no one accidentally changes the formulas. CLAUDE.md is similar — it's the protected configuration layer that tells Claude what the rules are before it starts touching things.
But it's more than a lock. It's also the documentation that lives alongside your project. Every decision you made — why you chose this library, what the database tables are, which routes exist — lives in CLAUDE.md. Future you, opening this project in three months, benefits from it too.
Two Levels: Global and Project
CLAUDE.md exists at two levels, and both are read by Claude Code.
Global (~/.claude/CLAUDE.md)
This lives in your home directory and applies to every project on your machine. It contains things that are true about you as a developer, regardless of which project you're working on.
What belongs here:
- Your preferred coding style (tabs vs spaces, named exports vs default exports)
- Your core tech stack (React, Supabase, Tailwind, TypeScript — always these)
- Universal rules (never use
anyin TypeScript, always useasync/awaitnot.then()) - Response style preferences (concise, no trailing summaries, no emojis)
- Tools you always have available (lucide-react for icons, zod for validation)
What does NOT belong here:
- Anything project-specific (database tables, API keys, routes)
- Things that change per project (which router you're using, which date library)
Project-Level (./CLAUDE.md at the project root)
This lives in the root folder of a specific project, alongside your package.json. It contains everything about this particular project.
What belongs here:
- What the app does and who uses it
- The tech stack for this project (especially where it deviates from your global defaults)
- Key commands (
npm run dev,npm run build, etc.) - Database tables and their purpose
- User roles and routes
- Environment variables needed
- Known issues and technical debt
- Decisions already made (so Claude doesn't re-suggest what you already rejected)
A Complete Minimal CLAUDE.md for a Trainee's First Project
Here is a real CLAUDE.md template for a personal portfolio website — your Project 1. Copy this structure, fill in the gaps marked with [brackets], and put it at the root of your project. It should have: a project description, quick commands section, tech stack table, project structure notes, and a rules section.
How to Write Effective Rules
Rules in CLAUDE.md are only useful if they are specific and actionable. Vague rules produce vague results.
| Weak rule | Strong rule |
|---|---|
| "Write clean code" | "Max 150 lines per component — split into smaller files if larger" |
| "Handle errors" | "Always show an error message in the UI when a query fails — never a blank screen" |
| "Use TypeScript properly" | "Never use any. Use unknown when the type is genuinely unknown. No @ts-ignore." |
| "Keep it simple" | "Don't add new npm packages without asking me first" |
| "Good naming" | "Props interfaces always named [ComponentName]Props. Hooks always prefixed with use." |
The goal is: if Claude follows every rule in your CLAUDE.md to the letter, the output should look like what you would have written yourself.
The Self-Update Rule
Your CLAUDE.md should update itself as your project evolves. Every time you make a significant decision — "we're going to use date-fns instead of dayjs", "we decided to add a contact form backend", "the mobile nav is being replaced with a drawer" — that decision should go into CLAUDE.md.
In practice, this means:
- At the end of any session where you made a real architectural decision, update CLAUDE.md
- When you encounter a pattern that's working well, document it
- When you try something and decide it's wrong, add it to the "What NOT To Do" section
A CLAUDE.md that hasn't been updated in two weeks is getting stale. A CLAUDE.md that grows with the project is genuinely valuable.
At the start of every session, ask Claude: "Read CLAUDE.md and tell me what this project is about." If Claude's answer matches your mental model of the project, your CLAUDE.md is working. If it's missing something important, add it right then.
What NOT to Put in CLAUDE.md
Some things do not belong in CLAUDE.md:
- API keys and secrets — Never. Ever. Use environment variables and
.envfiles. CLAUDE.md is committed to Git. Secrets in Git are a security incident. - Constantly-changing implementation details — CLAUDE.md is for stable facts about the project, not a daily changelog.
- Code patterns and boilerplate — These belong in skill files (next section), not CLAUDE.md. CLAUDE.md should tell Claude what the project is. Skills tell Claude how to do specific things.
- Explanations for Claude about what Claude is — Claude already knows it's an AI. Don't waste lines on this.
The First Thing Claude Does Every Session
When you type claude in your project folder, Claude's first action — before responding to anything you've typed — is to look for and read CLAUDE.md. If it exists, everything in it becomes Claude's working context for the entire session.
This is why a good CLAUDE.md makes every session better. You're not starting from zero. You're starting from a shared foundation that took time to build.