What Is CLAUDE.md and How to Write One
By Tyler Cyert
CLAUDE.md is the main instruction file that Claude Code reads at the start of every session. It tells the agent what your project is, how it should behave, what conventions to follow, and where things live. If you have ever wondered "what is CLAUDE.md?" — it is the single most important file in your Claude Code setup. Everything else (agents, rules, skills, hooks) extends from it.
Think of it as a contract between you and your coding agent. Without it, Claude Code starts every session blind, guessing at your stack, your style, and your intentions. With a well-written CLAUDE.md, the agent knows all of that before it writes a single line of code.
Why CLAUDE.md Matters
Claude Code loads your CLAUDE.md file into context automatically. You do not need to paste instructions into a chat window or re-explain your project every time. This makes it fundamentally different from prompt engineering — it is persistent, version-controlled, and shared across your team.
A good CLAUDE.md does three things:
- Reduces mistakes — The agent knows your conventions before it starts. No more fixing import styles, wrong directories, or mismatched naming patterns.
- Saves tokens — Clear instructions up front mean fewer correction rounds. Fewer corrections mean lower cost and faster results.
- Creates consistency — Every developer on your team gets the same agent behavior, because the instructions live in the repo, not in someone's clipboard.
A Practical CLAUDE.md Template
Here is a CLAUDE.md template you can adapt for most projects:
# Project Name
Brief description of what the project does and its current state.
## Stack
- Runtime: Node.js 22 + TypeScript 5.7
- Framework: Next.js 15 (App Router)
- Database: Postgres via Drizzle ORM
- Styling: Tailwind CSS v4
- Testing: Vitest + Playwright
## Build & Run
- `npm run dev` — start dev server
- `npm run build` — production build
- `npm run test` — run unit tests
- `npm run lint` — check linting
## Architecture
- `src/app/` — Next.js App Router pages and layouts
- `src/lib/` — Shared utilities, DB client, and business logic
- `src/components/` — React components
- `src/db/` — Drizzle schema, migrations, and seed scripts
## Code Style
- Use `@/` import alias for all src/ imports
- Prefer server components. Only add 'use client' when you need interactivity.
- Name files in kebab-case. Name components in PascalCase.
- Never commit .env files. Use .env.example for documentation.
## Important Rules
- Always run tests before marking a task as done
- Do not modify migration files that have already been applied
- Keep API route handlers thin — business logic belongs in src/lib/The 200-Line Rule
Anthropic recommends keeping your CLAUDE.md under 200 lines. This is not an arbitrary limit — it is about context efficiency. When your instruction file grows beyond 200 lines, two things happen:
- Important instructions get diluted. The agent has to sift through noise to find what matters.
- You are wasting context window. Every line of CLAUDE.md is loaded into every session, whether or not it is relevant.
The fix is simple: split. Claude Code gives you rules, skills, and agents for exactly this purpose.
What Goes Where
| Content | Where It Goes | Why |
|---|---|---|
| Project overview, stack, architecture | CLAUDE.md | Needed every session |
| Build commands, dev workflow | CLAUDE.md | Needed every session |
| Tool permissions (allow/deny) | settings.json | Structured config, not prose |
| Hooks (pre/post tool, stop) | settings.json | Lifecycle events need JSON schema |
| File-type-specific style rules | .claude/rules/ | Only loaded when matching files are touched |
| On-demand procedures | .claude/skills/ | Only loaded via /slash command |
| Agent-specific instructions | .claude/agents/ | Scoped to one agent's role |
The pattern: if the agent needs it every session, it goes in CLAUDE.md. If it is scoped, it goes in rules. If it is on-demand, it goes in a skill.
CLAUDE.md vs CLAUDE.local.md
CLAUDE.md is committed to your repo — everyone on the team gets the same instructions. CLAUDE.local.md is gitignored — it is for your personal preferences like verbosity level, editor-specific paths, or local environment quirks.
Generating Your CLAUDE.md with DotBox
Writing a CLAUDE.md from scratch is straightforward for small projects, but gets tricky as complexity grows — especially when you need to coordinate it with agents, rules, skills, and hooks. DotBox lets you build your entire Claude Code configuration visually, including the CLAUDE.md, and exports the complete directory as a zip.
Getting Started
- Create a CLAUDE.md in your project root. Start with the template above.
- Keep it focused. If you are over 150 lines, start moving scoped content into rules or skills.
- Test it. Start a Claude Code session and give it a task. If it asks questions your CLAUDE.md should have answered, add that information.
- Version control it. Commit your CLAUDE.md alongside your code.
The best CLAUDE.md files are living documents. They evolve as your project does.