How to Write a CLAUDE.md File for Claude Code

5 min read · Claude Code configuration

Claude Code reads a file called CLAUDE.md from your project root at the start of every session. Whatever you put in it, Claude treats as ground truth about your project — your stack, your conventions, what it should never touch, how you write tests.

Without a CLAUDE.md, Claude has no project context. It guesses at your patterns, picks libraries based on popularity rather than what you actually use, and makes decisions you'll disagree with. With a good one, those problems mostly disappear.

The basic structure

A CLAUDE.md file is plain Markdown. Claude reads it as context, not as instructions to execute. There's no required format — but effective ones typically cover six areas:

# CLAUDE.md

## Stack
What technologies are actually in use. Be specific — "React" is less useful than
"Next.js 15 with App Router, TypeScript strict mode, Tailwind CSS, Supabase."

## Code Style
Your conventions. Named vs default exports. Where tests live. How you name things.
Rules Claude should follow without being asked.

## Architecture
Where things go. /app vs /components vs /lib. Which files own what.
If Claude doesn't know this, it'll create files wherever it thinks is right.

## What NOT to Touch
Files or directories Claude should never modify without asking.
next.config.ts, database migrations, auth middleware — list them explicitly.

## Testing
Your test framework, where tests live, what you do and don't test.
"Test behavior the user sees, not implementation details" changes everything.

## Commit Style
Your convention. feat/fix/chore. One concern per commit. Whatever your standard is.

A minimal working example

Here's a CLAUDE.md for a Next.js project. Copy and adapt it.

# CLAUDE.md

## Stack
- Next.js 15 (App Router), TypeScript strict, Tailwind CSS
- Supabase (auth + database), Prisma ORM
- Vitest + React Testing Library

## Code Style
- Functional components only, no class components
- Named exports for components, default for pages
- Co-locate tests: Component.test.tsx next to Component.tsx
- No inline styles — Tailwind utilities only

## Architecture
- /app — routes and layouts only, no business logic
- /components — shared UI, no data fetching
- /lib — utilities, shared logic
- /hooks — custom React hooks
- Server Components by default, "use client" only when needed

## Never Touch Without Asking
- next.config.ts
- /app/api/** (coordinate changes)
- supabase/migrations/
- Any file in /lib/auth/

## Testing
- Vitest + RTL for components and hooks
- Test user-visible behavior, not internals
- No snapshot tests
- Mock at network layer (MSW), not at import level

## Commits
- feat / fix / chore / test
- One concern per commit

The most important section: "Never Touch Without Asking"

This is the section most people skip, and it causes the most pain. Without it, Claude will make changes to configuration files, database migrations, and auth code that seem locally reasonable but break things globally.

Think about what in your project would cause an outage or data loss if changed incorrectly, and list it.

Testing instructions matter more than you'd expect

Without explicit testing instructions, Claude defaults to writing tests that test implementation details — checking that a specific function was called, asserting on internal state, using snapshot tests that break on every UI change.

Adding a single line like "Test behavior the user sees, not implementation details" changes the quality of generated tests dramatically.

What to do when your stack isn't in a template

The structure above works for any stack. Swap out the technology names, keep the six sections. A Go + Gin backend, a Flutter mobile app, a Rails monolith — the CLAUDE.md looks the same, just with different specifics.

The most important thing is that it's specific. Generic instructions get generic results.

Keeping it up to date

Treat CLAUDE.md like documentation — update it when your stack or conventions change. An outdated CLAUDE.md is worse than none because Claude will confidently follow instructions that no longer apply.

A good time to review it: when onboarding a new tool, when changing your testing setup, or when you notice Claude repeatedly making the same wrong decision.

Where CLAUDE.md can live

The pattern above covers the most common case: a project's CLAUDE.md at the repo root. Claude Code actually reads from three scopes in order of precedence:

• Managed — enterprise-deployed policy files (org-wide, highest precedence).
• Project — ./CLAUDE.md or ./.claude/CLAUDE.md at your repo root. Nested CLAUDE.md files in subdirectories load lazily when Claude reads files in that subdirectory.
• User — ~/.claude/CLAUDE.md, read for every project on your machine. Good for personal preferences like "use short commit messages" or "run tests before claiming work complete" that you don't want to repeat in every repo.

There's also CLAUDE.local.md for project-specific preferences you want gitignored (sandbox URLs, local test data). And Claude Code's /init command auto-generates a starter CLAUDE.md by analyzing your repo.

Frequently asked questions

Once you have a solid CLAUDE.md, the next multipliers are custom slash commands, workflow hooks, MCP servers for external data sources, and your settings.json for permission profiles, hook wiring, and model defaults.

Using GitHub Copilot too? Copilot's equivalent workspace file is .github/copilot-instructions.md — see the Copilot Customization Starter Kit for drop-in templates plus per-path .instructions.md rules and reusable .prompt.md files.