If you use Claude Code, the single most impactful thing you can do is write a good CLAUDE.md file. It is the system prompt for your codebase. Every time Claude Code reads your project, it reads CLAUDE.md first, and everything it does afterward is shaped by what it finds there.
This guide covers what CLAUDE.md is, why it matters, how to structure it, and what patterns the best open-source projects use. Every example here comes from real repositories.
What Is CLAUDE.md?
CLAUDE.md is a Markdown file placed at the root of your repository (or in subdirectories) that gives Claude Code persistent instructions about your project. Think of it as a README that is written for your AI coding assistant instead of for human developers.
When you run Claude Code in a directory that contains a CLAUDE.md file, Claude reads it automatically at the start of every session. Unlike conversation context that disappears, CLAUDE.md persists. It is always there, always loaded, always influencing how Claude behaves.
Anthropic introduced CLAUDE.md as part of Claude Code’s agentic coding workflow. It has since become one of the most widely adopted standards for AI coding configuration, alongside .cursorrules and AGENTS.md.
Why CLAUDE.md Matters
Without a CLAUDE.md, Claude Code makes reasonable guesses about your project. With one, it can follow your exact conventions, avoid patterns you dislike, and produce code that fits your codebase on the first try.
Here is what a well-written CLAUDE.md eliminates:
- Repeated corrections. If you keep telling Claude “use single quotes” or “don’t use classes,” that belongs in CLAUDE.md.
- Style inconsistencies. Your CLAUDE.md can specify formatting conventions, naming patterns, and import ordering that Claude follows automatically.
- Wrong architectural decisions. Tell Claude which patterns to prefer (e.g., server components over client components) and it will default to them.
- Wasted context window. Instead of spending tokens re-explaining your project every session, CLAUDE.md handles it once.
The Vercel Next.js CLAUDE.md (138K stars) is a perfect example. It specifies everything from the monorepo structure to the preferred testing framework, and contributors report dramatically fewer review cycles when Claude follows it.
File Placement and Hierarchy
CLAUDE.md files can live at multiple levels:
- Repository root (
/CLAUDE.md) — Loaded for every session in the project. This is where project-wide rules go. - Subdirectories (
/packages/api/CLAUDE.md) — Loaded only when Claude is working in that directory. Use this for package-specific rules in monorepos. - User-level (
~/.claude/CLAUDE.md) — Loaded for every project you work on. Good for personal preferences like editor settings or formatting habits.
Claude reads them in order: user-level first, then root, then subdirectory. More specific files take precedence.
Structure of an Effective CLAUDE.md
After analyzing dozens of CLAUDE.md files from top repositories on The Prompt Shelf , a clear pattern emerges. The best files share these sections:
1. Project Overview
Start with a brief description of what the project is and its tech stack. This gives Claude the context it needs to make architecture decisions.
# Project
This is a Next.js 14 application using the App Router, TypeScript,
Tailwind CSS, and Drizzle ORM with PostgreSQL.The LangChain CLAUDE.md opens with a clear description of the project’s purpose and its core abstractions, so Claude understands the domain before writing any code.
2. Code Style and Conventions
This is the section that saves you the most time. Be specific and prescriptive.
## Code Style
- Use functional components with arrow functions
- Prefer named exports over default exports
- Use TypeScript strict mode; no `any` types
- Imports: React first, then third-party, then local (with blank lines between groups)
- File naming: kebab-case for files, PascalCase for componentsThe Excalidraw CLAUDE.md is particularly thorough here, specifying not just formatting but architectural preferences like component composition patterns and state management approaches.
3. Architecture and Patterns
Tell Claude which patterns to prefer and which to avoid.
## Architecture
- Server Components by default; only use 'use client' when necessary
- Data fetching happens in Server Components, never in client components
- Use Server Actions for mutations
- Keep components small; extract to separate files at ~50 linesThe Dan Abramov / Overreacted CLAUDE.md demonstrates how to encode strong architectural opinions that keep the codebase consistent.
4. Project-Specific Commands
If your project has unusual build steps, test commands, or development workflows, document them.
## Commands
- `pnpm dev` — Start development server
- `pnpm test` — Run Vitest in watch mode
- `pnpm lint` — ESLint + Prettier check
- `pnpm db:push` — Push schema changes to databaseThe Deno CLAUDE.md includes detailed build and test instructions because the project has a non-standard build system that Claude would not know about otherwise.
5. What NOT to Do
Negative instructions are surprisingly effective. Telling Claude what to avoid is often more impactful than telling it what to do.
## Do NOT
- Do not use `class` components
- Do not use `any` type
- Do not add dependencies without asking
- Do not modify the database schema directly
- Do not use inline stylesThe CockroachDB CLAUDE.md includes explicit constraints about which subsystems Claude should not modify and which testing patterns to avoid.
6. File Organization
In larger projects, tell Claude where things live.
## File Structure
- `src/components/` — Reusable UI components
- `src/app/` — Next.js App Router pages
- `src/lib/` — Utility functions and shared logic
- `src/db/` — Database schema and migrations7. Testing Expectations
Specify how and when tests should be written.
## Testing
- Every new component needs a test file in __tests__/
- Use Testing Library for component tests
- Use Vitest, not Jest
- Integration tests go in tests/integration/
- Run `pnpm test:unit` before committingReal-World Examples Worth Studying
Here are CLAUDE.md files from notable projects, all available on The Prompt Shelf:
Vercel Next.js — The gold standard for monorepo CLAUDE.md files. Covers the entire Next.js framework codebase with detailed testing and contribution guidelines. 138K stars.
LangChain — Shows how to document a complex Python library with multiple packages. Strong focus on import conventions and testing patterns. 128K stars.
Excalidraw — A great example for React applications. Specifies component patterns, state management, and UI conventions. 118K stars.
Deno — Demonstrates CLAUDE.md for a Rust-based runtime. Covers build system quirks and cross-platform considerations. 106K stars.
Zed Editor — Shows how to document a Rust application using the GPUI framework. Includes detailed instructions about the custom UI framework. 76K stars.
Anthropic’s Official Guide — Anthropic’s own recommendations for writing CLAUDE.md. Concise and principled.
Freek Van der Herten / Spatie Laravel — An excellent example for PHP/Laravel projects. Shows that CLAUDE.md works well beyond the JavaScript ecosystem.
Best Practices
After reviewing hundreds of CLAUDE.md files, these patterns consistently produce better results:
Be specific, not abstract. “Use Tailwind CSS for styling” is better than “Follow modern CSS practices.” “Use cn() from @/lib/utils for conditional classes” is better still.
Keep it under 500 lines. Claude reads the entire file every session. If it is too long, the important rules get diluted. Move detailed documentation to separate files and reference them.
Use examples. Show Claude what good code looks like in your project. A 5-line code example is worth 50 lines of description.
Update it regularly. Your CLAUDE.md should evolve with your codebase. If you find yourself repeatedly correcting Claude about something, add it to the file.
Test your rules. After changing CLAUDE.md, start a fresh Claude session and ask it to perform a common task. Verify it follows the new rules.
Do not duplicate your README. CLAUDE.md is for AI-specific instructions. Setup steps that a human developer needs but Claude does not should stay in README.md.
Use subdirectory files for monorepos. A single massive CLAUDE.md for a monorepo with 20 packages will be less effective than a root file with shared rules plus package-specific files.
CLAUDE.md vs Other Formats
CLAUDE.md is specific to Claude Code. If your team uses multiple AI tools, you may also need:
- .cursorrules — For Cursor AI editor. Similar concept, different format.
- AGENTS.md — A broader standard for multi-agent systems, used by Codex, Claude Code, and others.
- .github/copilot-instructions.md — For GitHub Copilot.
The good news is that these formats are similar enough that you can maintain one source of truth and adapt it. See our comparison guide for a detailed breakdown.
Getting Started
If you do not have a CLAUDE.md yet, start small:
- Create a
CLAUDE.mdfile at your project root. - Add a one-paragraph project description.
- List your 5 most important coding conventions.
- Add 3 things Claude should never do.
- Include your most common development commands.
That is enough to see a noticeable improvement. Expand the file as you discover patterns that need documentation.
Browse our full collection of CLAUDE.md files for inspiration, or check the complete rules gallery to see how other projects configure their AI coding assistants.