How to Write a CLAUDE.md File That Actually Works

If you've been using Claude Code for more than a week, you've probably noticed something: Claude is only as good as the context it has. Give it a vague project and it makes vague decisions. Give it clear constraints and it executes like a senior engineer who's been on your team for months.

That's exactly what a CLAUDE.md file does — it's persistent context that Claude reads before every single session. Get it right and you'll spend less time correcting Claude and more time shipping. Get it wrong and you'll fight your AI tool instead of working with it.

This guide covers what to put in your CLAUDE.md, what to leave out, how to structure it for larger projects, and the most common mistakes developers make.

What Is a CLAUDE.md File?

Think of it less as documentation and more as a system prompt for your codebase. It answers questions Claude would otherwise have to guess at:

• How do I run this project?
• What coding conventions does this team follow?
• What am I allowed to change vs. what's off-limits?
• What tools and MCP servers should I use?

Without a CLAUDE.md, Claude starts every session at zero — reading files, inferring patterns, sometimes getting it wrong. With a well-written one, Claude walks in already knowing your project like it's been there all along.

To generate a starter file, run:

bash/init

This creates a baseline CLAUDE.md from your project structure. But the default output is a starting point, not a finished product. The real work is in refining it.

The 5 Things Every CLAUDE.md Must Include

1. Bash Commands (Build, Test, Lint)

Claude needs to know how to run your project. Don't make it guess. Include the exact commands it should use:

markdown## Commands

- **Dev server:** `npm run dev`
- **Build:** `npm run build`
- **Lint:** `npm run lint`
- **Tests:** `npm test` (never run `npm test` without `-- --testPathPattern` to scope it)
- **Database migrations:** `npx prisma migrate dev`

Be specific. If there's a command Claude must never run in production (DROP TABLE, git push --force, a seed script that resets data), say so explicitly.

2. Code Style Rules

If your team follows specific conventions that aren't obvious from the code, spell them out:

markdown## Code Style

- TypeScript strict mode — never use `any`
- Components: functional only, no class components
- CSS: Tailwind utility classes only, no custom CSS files
- Imports: absolute paths via `@/` alias
- File naming: kebab-case for files, PascalCase for components

Claude is good at inferring style from existing code — but explicit rules eliminate edge cases and prevent regressions on files it hasn't read yet.

3. Architecture Overview

A two-paragraph summary of how your project is structured saves Claude from reading 50 files to understand the layout:

markdown## Architecture

This is a Next.js 15 App Router project. Pages live in `src/app/`, shared components in `src/components/`, 
database queries in `src/lib/db/`. We use Prisma with a Neon PostgreSQL database.

API routes follow the pattern `src/app/api/[resource]/route.ts`. All DB calls go through `src/lib/db/*.ts` 
— never write raw SQL in components or route handlers.

This is especially valuable for monorepos, multi-package workspaces, or projects with non-standard folder structures.

4. Workflow Rules and Permissions

Tell Claude what it's allowed to do autonomously vs. what requires your approval:

markdown## Workflow

- Ask before creating new files in `src/app/` (new routes need discussion)
- Never modify `prisma/schema.prisma` without explicit instruction
- Always run `npm run lint` before marking a task complete
- Prefer editing existing files over creating new ones
- When unsure between two approaches, implement the simpler one and ask

This is where you recover hours of wasted back-and-forth. Claude defaults to doing more, not less — if you don't specify boundaries, it will fill the space.

5. Domain-Specific Vocabulary

Every project has jargon. Define it so Claude uses your terminology, not generic substitutes:

markdown## Domain Terms

- **CapturedItem** — a user-submitted idea stored in the DB, not a "suggestion" or "submission"
- **Brain Task** — an async LLM job routed through our internal queue, not an "AI request"
- **Phase Gate** — a shipping milestone check, not a "stage" or "checkpoint"

This sounds minor until you're reading a 200-line diff and Claude has renamed all your domain objects to something more "intuitive."

The 3 Things You Should Never Put in CLAUDE.md

1. Content That's Already in the Code

If your codebase uses TypeScript, you don't need CLAUDE.md: "Use TypeScript." If you have ESLint configured, you don't need to duplicate every rule. CLAUDE.md is for context Claude cannot infer from reading your files. Anything derivable from the code itself is noise.

Rule of thumb: if Claude would figure it out after reading two or three files, leave it out.

2. Long Documentation or Explanatory Prose

3. Instructions That Only Apply Sometimes

If a rule only applies in one specific situation (e.g., "when working on the auth module, use X pattern"), either put it in a sub-file for that module or skip it. Conditional instructions in a flat file are hard for Claude to apply reliably.

Instead, create a CLAUDE.md in the relevant subdirectory. Claude reads directory-level CLAUDE.md files when working in those directories.

CLAUDE.md Architecture for Larger Projects

For projects beyond a few dozen files, a single root CLAUDE.md often isn't enough — but overstuffing it causes its own problems.

The pattern that works best: a lean root file + scoped sub-files.

project-root/
├── CLAUDE.md                    # ≤150 lines — project-wide rules only
├── .claude/
│   ├── rules/
│   │   ├── database.md          # DB conventions, Prisma patterns
│   │   ├── api.md               # API design rules
│   │   └── testing.md           # Test patterns, what to mock vs. not
│   └── agents/
│       └── content-writer.md    # Agent-specific system prompt
├── src/
│   ├── app/
│   │   └── CLAUDE.md            # Route-level conventions
│   └── components/
│       └── CLAUDE.md            # Component patterns

The root CLAUDE.md stays under 150 lines and handles project-wide context. Specialized rules live in sub-files and are referenced:

markdown## Rules

@.claude/rules/database.md
@.claude/rules/api.md
@.claude/rules/testing.md

Claude loads these on demand. This keeps the main context lean while making specialized guidance available when needed.

A Complete Minimal Example

Here's a stripped-down CLAUDE.md that hits every essential section without bloat:

markdown# Project: AiA — AI for Anything

## Commands
- Dev: `npm run dev`
- Build: `npm run build`  
- Lint: `npm run lint` (run before every commit)
- DB: `npx prisma migrate dev` (never run without local DB connection)

## Architecture
Next.js 15 App Router. Pages → `src/app/`. Components → `src/components/`. 
DB queries → `src/lib/db/`. API routes → `src/app/api/[resource]/route.ts`.
Neon PostgreSQL via Prisma. PostHog for analytics.

## Code Style
- TypeScript strict, no `any`
- Tailwind only — no custom CSS
- Absolute imports via `@/`
- Functional components only

## Workflow
- Ask before adding new routes or DB tables
- Prefer editing over creating new files
- Run lint before marking tasks done
- Never seed the DB (launchd handles that)

## Off-Limits
- `prisma/schema.prisma` — only edit on explicit instruction
- `src/app/api/payments/` — payment routes require review

That's it. Under 30 lines of actual instructions. Concrete, actionable, complete.

Common Mistakes and How to Fix Them

Your README explains your project to humans. CLAUDE.md injects context into an AI agent. They serve different purposes. Don't copy-paste your README into CLAUDE.md.

The best use of CLAUDE.md is fixing recurring mistakes. Every time Claude does something you have to correct twice, add a rule. Over time, your file becomes a living record of your project's most important constraints.

Use directory-level CLAUDE.md files. Claude respects them when working in those directories. A root file that tries to cover every package in a monorepo will either be too long or too vague to be useful.

Key Takeaways

• CLAUDE.md is a context injection file, not documentation. Write for Claude, not humans.
• Keep it under 200 lines at the root level. Use sub-files and directory-level files for scoped rules.
• Include: commands, code style, architecture summary, workflow permissions, domain vocabulary.
• Exclude: content derivable from code, conditional rules, long explanatory prose.
• Generate a baseline with /init, then refine over time based on what Claude keeps getting wrong.
• Update it whenever your project conventions change.

Go Deeper: Become a Certified Claude Architect

If you're investing in Claude as a core part of your development workflow, consider formalizing that expertise with the Claude Certified Architect (CCA-F) certification from Anthropic.

The CCA exam tests your understanding of Claude's capabilities, prompt engineering, agent architecture, safety considerations, and production deployment patterns — exactly the skills that separate developers who use Claude from developers who build with Claude.

Or start with our free Claude Certification Roadmap to understand the full landscape of AI credentials worth pursuing in 2026.