A CLAUDE.md file is a single Markdown file you put in the root of your project that Claude Code reads before every task. It is the difference between an AI that guesses at your codebase and one that already knows your stack, your conventions, and the mistakes you never want it to make again. Get it right and every session starts with your AI engineer already briefed. Get it wrong, or skip it, and you spend your day re-explaining the same things.
We run a CLAUDE.md file on every production codebase at Vaylo Studios, the ones behind our own products and the ones we build for clients. This is what we have learned actually belongs in it.
What a CLAUDE.md File Is (and Is Not)
When Claude Code starts working in a project, it looks for a file named CLAUDE.md in the root and reads it first, before it touches a single line of your code. Whatever is in that file shapes every decision it makes for the rest of the session: which patterns it follows, which libraries it reaches for, how it names things, what it refuses to do.
Most people treat it like a README, a description of the project for a human who might show up later. That is the wrong mental model. A README explains the project. A CLAUDE.md file instructs the AI. Every line should change what Claude Code does, not just describe what exists. If a sentence would not change a single decision the AI makes, it does not belong in the file.
The other common mistake is skipping it entirely and just prompting harder. You can get away with that on a throwaway script. On anything you intend to maintain, the CLAUDE.md file is the highest-leverage 30 minutes you will spend, because it pays off on every task afterward instead of just the current one.
What to Actually Put in It
Here is the structure we use. You do not need all of it on day one, but each section earns its place.
1. What the project is, in two sentences
Start with what the thing does and who it is for. Not marketing copy, the operational truth. "A booking platform for service businesses: customers book appointments, staff manage schedules, payments run through Stripe." Now the AI knows the domain, and its assumptions get dramatically better.
2. The stack, with versions and the specific choices
Do not just write "Next.js." Write "Next.js 15 App Router, TypeScript, Tailwind, Prisma with MySQL, NextAuth." Versions matter because APIs change between them, and the AI will confidently write code for the wrong one if you leave it guessing. Include the deliberate choices too: which state library, which form library, which patterns you have standardized on. Every choice you document is a choice the AI stops making wrong.
3. Conventions and structure
Where things live and how they are named. "API routes in src/app/api. Shared components in src/components. Database access only through the prisma client in src/lib. Server components by default; add 'use client' only when you need interactivity." This is the section that stops the AI from scattering files in the wrong places and inventing a fourth way to do something you already do three consistent ways.
4. The "never do this" rules
This is the highest-value section, and the one most people skip. Every codebase has landmines: the thing that broke production last month, the pattern that looks fine but causes a subtle bug, the library you migrated away from. Write them down as hard rules. "Never write to the production database directly, use the admin API. Never use em dashes in user-facing copy. Never introduce a new date library, we use date-fns." Claude Code will follow explicit prohibitions reliably. The rules you keep in your head, it cannot follow at all.
5. How you want it to communicate
Tell it how to behave when it hits uncertainty. "Ask before making an assumption that would be expensive to reverse" or "make a decision, do the work, and document why." Tell it whether to run the tests, whether to commit, how verbose to be. This section shapes the working relationship, not just the code.
6. External services and gotchas
What it connects to and the non-obvious operational facts: which environment variables matter, which service has a quirk, how deploys work, what is safe to run locally versus what hits a live system. This is the institutional knowledge that usually lives in one person's head. In the file, the AI has it too.
The Rules That Make It Work
Three habits separate a CLAUDE.md file that compounds from one that rots.
Be specific, not aspirational. "Write clean code" instructs nothing. "Functions do one thing; extract a helper when a function passes 40 lines; no default exports" instructs everything. The AI acts on concrete rules and ignores vague sentiment, so every vague line is wasted space.
Keep it current. A stale CLAUDE.md is worse than none, because the AI trusts it. When you change a pattern, update the file in the same breath. When a "never do X" rule bites you a second time, that is the signal it was missing from the file. Treat the file as living documentation that the whole team, human and AI, reads first.
One source of truth. Do not scatter the same rules across the file, code comments, and your memory. If it matters, it goes in CLAUDE.md, once, where the AI reads it every time.
A Minimal Starting Template
If you are staring at an empty file, start here and grow it as the project teaches you what belongs:
# [Project Name] ## What this is [One or two sentences: what it does, who it is for.] ## Stack [Framework + version, language, styling, database, auth, key libraries.] ## Structure and conventions [Where things live. Naming. The patterns you have standardized on.] ## Never do this - [The thing that broke prod.] - [The pattern you migrated away from.] - [Your hard style rules.] ## How to work [Ask vs decide. Run tests? Commit? Communication style.] ## Services and gotchas [External services, env vars that matter, deploy notes, local vs live.]
That is enough to make the very next session noticeably better. The file gets sharper every time you catch yourself re-explaining something, that is the moment it should have been in CLAUDE.md.
Want the CLAUDE.md template we actually run?
Our free Vibe Coder Starter Kit includes the exact CLAUDE.md template and the copy-paste prompts we use on every build. No cost, just an email to send it to.
Frequently Asked Questions
Where does the CLAUDE.md file go?
In the root of your project, next to package.json. Claude Code finds it automatically. You can also add nested CLAUDE.md files in subdirectories for context specific to that part of the codebase, and a personal one in your home directory for preferences that apply across all your projects.
How long should a CLAUDE.md file be?
As long as it needs to be and no longer. Every line should change a decision the AI makes. A small project might need 30 lines; a large one with lots of conventions and landmines might run several hundred. Length is not the goal, signal is. If a section is not affecting the output, cut it.
Do I need a CLAUDE.md file for a small project?
For a throwaway script, no. For anything you plan to maintain or return to, yes, and it pays off faster than you would expect. Even 15 lines of stack, conventions, and "never do this" rules noticeably improves every session.
What is the difference between CLAUDE.md and a README?
A README describes the project for humans. A CLAUDE.md file instructs the AI. They can overlap, but their jobs are different: the README explains, the CLAUDE.md file directs. Write the CLAUDE.md file as commands and constraints, not documentation.
The Bigger Picture
The CLAUDE.md file is the single highest-leverage habit in AI-assisted development, because it is the one piece of work that improves every future task instead of just the current one. The people getting real output from Claude Code are not prompting harder. They are the ones who briefed their AI once, thoroughly, and stopped having to re-explain themselves. That is the whole game: an AI that reads before it acts.
