The CLAUDE.md File: How to Write Perfect Instructions for Claude Code
CLAUDE.md is the most important file in your project when using Claude Code. This guide shows you how to write one that dramatically improves output quality, with real examples and templates.
What CLAUDE.md does
When you start a Claude Code session, the first thing it reads is your CLAUDE.md file. This gives Claude Code:
- Project context -- what this project is, what it does, what stack it uses
- Coding standards -- your formatting preferences, naming conventions, patterns
- Architecture decisions -- where files go, how components are structured, what patterns to follow
- Rules -- things to always do, things to never do
- Tool preferences -- which testing framework, which package manager, etc.
How to generate one
The fastest way to start:
``
/init
`
Run this command inside Claude Code while in your project directory. It analyzes your codebase and generates a starter CLAUDE.md based on what it finds -- your file structure, package.json, existing configs, etc.
This gives you a solid foundation. Then you customize it.
Structure of a great CLAUDE.md
Project overview
Start with what the project IS:
`markdown
Project Name
This is a Next.js 15 SaaS application for managing customer onboarding workflows.
It uses Supabase for auth and database, Stripe for payments, and deploys to Vercel.
`
Keep it short. Claude Code needs context, not a novel.
Tech stack
List your exact versions and tools:
`markdown
Stack
- Next.js 15 + React 19 + TypeScript
- Tailwind CSS + shadcn/ui
- Supabase (auth + database + RLS)
- Stripe (payments, subscriptions)
- Deployed on Vercel
`Coding rules
This is where CLAUDE.md becomes powerful. Be specific:
`markdown
Rules
- Immutable data -- never mutate, always return new copies
- Files under 400 lines, functions under 50 lines
- Handle errors explicitly, never swallow them
- Validate user input at system boundaries
- Conventional commits: feat:, fix:, refactor:
- No emojis in code, comments, or documentation
`File organization
Tell Claude Code where things go:
`markdown
File Structure
- src/app/ -- Next.js app router pages
- src/components/ -- reusable UI components
- src/lib/ -- utilities, helpers, shared logic
- src/data/ -- data files, constants, types
- supabase/migrations/ -- database migrations (SQL)
`What NOT to do
Negative rules are as important as positive ones:
`markdown
Never
- Never hardcode secrets or API keys
- Never modify database schema without a migration file
- Never skip TypeScript types (no 'any')
- Never commit .env files
- Never use default exports (use named exports)
`Advanced CLAUDE.md patterns
Per-directory rules
You can place CLAUDE.md files in subdirectories for context-specific rules:
`
project/
CLAUDE.md # Global rules
src/
components/
CLAUDE.md # Component-specific patterns
api/
CLAUDE.md # API-specific conventions
`
User-level vs project-level
Project CLAUDE.md -- lives in your project root, committed to git, shared with your team- User CLAUDE.md -- lives in ~/.claude/CLAUDE.md, applies to all your projects, personal preferences
Dynamic instructions
Your CLAUDE.md can reference other files:
`markdown
Design System
See src/styles/theme.css for color tokens and typography.
Follow the exact patterns in src/components/Button.tsx for new components.
`Real-world example
Here's a condensed CLAUDE.md from a production project:
`markdown
CustomerOS -- SaaS Onboarding Platform
Next.js 15 + Supabase + Stripe. Deployed on Vercel.
Rules
- TypeScript strict mode, no 'any'
- All database access through Supabase client (src/lib/supabase.ts)
- All API routes validate input with Zod schemas
- Conventional commits (feat:, fix:, refactor:)
- Tests required for API routes, optional for components
- Tailwind for styling, no CSS modules
- Named exports only
Patterns
- Server components by default, 'use client' only when needed
- Form handling: react-hook-form + zod
- Data fetching: server components for reads, server actions for writes
- Error boundaries on every route segment
Never
- Never expose Supabase service role key to client
- Never skip RLS policies on new tables
- Never use localStorage for auth state (use Supabase session)
`Common mistakes
- Too long -- 5,000 words of instructions creates confusion. Keep it under 200 lines.
- Too vague -- "write good code" means nothing. "Functions under 50 lines, named exports, Zod validation on all inputs" means something.
- Outdated -- review your CLAUDE.md monthly. Remove rules that no longer apply.
- Missing negative rules -- telling Claude Code what NOT to do is as important as what to do.
Getting started
If you don't have a CLAUDE.md yet:
Run/init` inside Claude Code- Review what it generated
- Add your coding rules and patterns
- Add your "never" list
- Commit it to your repo
Frequently asked questions
What is CLAUDE.md?
CLAUDE.md is a markdown file in your project root that provides instructions to Claude Code. It tells Claude Code about your project's tech stack, coding standards, file organization, and rules. It's the most impactful file you can create for improving Claude Code output quality.
How do I create a CLAUDE.md file?
The fastest way is to run /init inside Claude Code while in your project directory. This analyzes your codebase and generates a starter CLAUDE.md automatically. Then customize it with your specific coding rules, patterns, and preferences.
How long should CLAUDE.md be?
Keep it under 200 lines. A good CLAUDE.md is concise and specific. Include project overview, tech stack, coding rules, file organization, and a list of things to never do. Avoid generic advice like 'write clean code' -- be specific about what clean means in your project.
Can I have multiple CLAUDE.md files in one project?
Yes. You can place CLAUDE.md files in subdirectories for context-specific rules. For example, src/api/CLAUDE.md could contain API-specific conventions while the root CLAUDE.md has global rules. Claude Code reads the most relevant CLAUDE.md based on where you're working.
Does CLAUDE.md work with other AI tools?
CLAUDE.md is specific to Claude Code. However, the concept of project instruction files is becoming common -- Cursor uses .cursorrules, and other tools have similar mechanisms. The patterns and thinking behind a good CLAUDE.md apply to any AI coding tool's configuration.
Related guides
Need help implementing this?
//prometheus does onsite AI consulting and implementation in Milwaukee. We set it up, train your team, and make sure it works.
let's talk