In short
CLAUDE.md is a file Claude Code reads at the start of every session. It tells Claude Code what the project is, how to run it, how the code is organised and the rules to follow, so you stop repeating yourself. A good CLAUDE.md is short, specific and written as instructions. Below is the structure that works, a short example, and two complete templates: a full project file and a design rules section.
Updated
Where the file goes
Put CLAUDE.md in the root of your repo. Claude Code also reads CLAUDE.md files in parent folders and in sub-folders when it works there, and a personal one in ~/.claude/CLAUDE.md that applies to all your projects.
CLAUDE.md template: structure
Project
One or two lines: what the product is, who it is for, and the main stack.
Commands
The exact commands to run, build, lint and test. Claude Code runs them to check its work.
Folders
A short map of where things live, so Claude Code edits the right files.
Code style
The conventions that are not obvious from the code: server or client components, where data fetching goes, naming.
Design rules
Which template to follow, colour tokens, type scale and spacing. This is what keeps the UI consistent.
Never
A short list of hard rules: secrets, migrations, generated files.
A short example
# Project [Product] is a [type of app] for [audience]. Next.js, TypeScript, Tailwind. ## Commands - npm run dev / npm run build / npm test ## Folders - app/ routes · components/ shared UI · lib/ data and helpers ## Rules - Reuse components in components/ before creating new ones. - Follow design/template.html for all UI. ## Never - Never commit .env files.
Writing a CLAUDE.md, step by step
Start with /init in Claude Code. It reads your codebase and writes a first CLAUDE.md with the stack, the commands and the folder layout. Treat that as a draft: it describes the project, but it does not yet tell Claude Code how you want it to work.
Next, cut anything Claude Code can see for itself in the code, like a list of every component, and keep what it cannot infer: which commands prove a change works, where new files should go, which patterns you prefer, and which mistakes it keeps making. A rule earns its line when it changes behaviour.
Then add a design section. This is where most CLAUDE.md files are weakest. Point to one design template in the repo, list your colour tokens and type scale, and say to reuse components before creating new ones. That single section is what stops every new page from looking slightly different.
Finally, keep it alive. When you correct Claude Code twice for the same thing, add a line. When a rule stops mattering, delete it. A short file that is always true beats a long one that is half out of date.
Ready-made CLAUDE.md files
Complete files you can copy into your project and fill in. Each one works with the BrowserMoon design templates, so what the tool builds also looks professional.
Full CLAUDE.md template for a SaaS app
A complete CLAUDE.md for a Next.js and Tailwind SaaS: project overview, commands, folder map, code style, design rules, testing and what never to do.
CLAUDE.md (full project file)# Project [Product name] is a SaaS app that helps [audience] [main outcome]. Next.js (App Router), TypeScript, Tailwind CSS, [database] and [auth provider]. ## Commands - npm run dev: start the dev server on port 3000 - npm run build: production build; must pass before any change is done
CLAUDE.md design template
A design section for CLAUDE.md. Claude Code reads it at the start of every session, so every page it builds follows your template, colours and spacing.
CLAUDE.md# Design rules These rules apply to every UI change in this repo. Read them before writing any component, page or style. ## Design source of truth - Match the BrowserMoon template in design/template.html for fonts, spacing, colours, corner radius, shadows and components. When in doubt, open it and copy what it does. - Never invent a new style. If something is not in the template, use the closest thing that is.
Using CLAUDE.md with a design template
A CLAUDE.md tells Claude Code how to work; a design template shows it what to build. Save the template as design/template.html and name it in CLAUDE.md as the source of truth for fonts, spacing, colours and components.
With both in place, every session starts by knowing the design, so a new pricing page or settings screen matches the pages already built, without you pasting the design again.
SaaS landing page · Analytics dashboard · Pricing section · Dark gradient hero · Account settings · AI chat interface
Best practices
- ·Keep it under about 150 lines. Claude Code reads all of it every session, so every line should earn its place.
- ·Write instructions, not documentation: "Use server components by default", not a paragraph about React.
- ·Put the commands first. Claude Code uses them to check its own work.
- ·Add rules when you correct Claude Code twice for the same thing.
- ·Use # in Claude Code to add a line to CLAUDE.md as you work.
Common mistakes and how to fix them
Writing documentation instead of instructions
Replace paragraphs about the architecture with direct rules: "Use server components by default."
Letting it grow past a few hundred lines
Move detailed workflows into skills, which load only when needed, and keep CLAUDE.md for rules that always apply.
No design rules at all
Add a design section that names one template and your tokens; this is the fastest fix for generic UI.
Commands that do not work
Run every command in the file yourself. Claude Code trusts them to check its work.
Secrets or personal paths in a shared file
Keep personal preferences in ~/.claude/CLAUDE.md and secrets out of every CLAUDE.md.
CLAUDE.md vs AGENTS.md vs Cursor rules
These files tell Claude Code how to work. A design template tells it what to build. Use both.
Claude Code templatesFrequently asked questions
What is CLAUDE.md?
A markdown file Claude Code reads at the start of every session. It holds project context and rules, so Claude Code knows how your project works without being told each time.
Where does CLAUDE.md go?
In the root of your repo. You can add more in sub-folders for rules that only apply there, and a personal one in ~/.claude/CLAUDE.md for all projects.
What should I put in CLAUDE.md?
What the project is, the commands to run and test it, a folder map, code style rules, design rules and a short list of things to never do.
How long should CLAUDE.md be?
Short. Under about 150 lines works well. Long files cost context every session and bury the rules that matter.
Can I generate a CLAUDE.md automatically?
Yes. Run /init in Claude Code to create a first version from your codebase, then edit it with the structure on this page.
Should CLAUDE.md be committed to git?
Yes, the project CLAUDE.md should be committed so the whole team and every session share the same rules. Keep personal preferences in ~/.claude/CLAUDE.md instead.
Can I have more than one CLAUDE.md?
Yes. Claude Code reads the root file and any CLAUDE.md in folders it works in, so a monorepo can have one per package with package-specific rules.
How do I add design rules to CLAUDE.md?
Add a Design section that names one design template file, lists your colour tokens, type scale and spacing, and says to reuse components. The design template on this page is ready to paste.
Claude Code templates by category
Related