How to Write a CLAUDE.md File: The 2026 Playbook

If you use Claude Code, one of the most useful files in your repo isn't a config or a CI script. It's CLAUDE.md — the file Claude reads at the start of a session, before any code. Get it right and Claude stops guessing your conventions, stops re-running the wrong test command, and stops asking you the same five questions every session. Get it wrong (or skip it) and you spend your day re-explaining context that should have been written down once.

This is a practical, example-led playbook: what the file is, where it lives, the anatomy of a strong one, a copy-and-adapt example, the mistakes that quietly make it useless, and how it relates to AGENTS.md and Cursor rules.

What is a CLAUDE.md file?

CLAUDE.md is a Markdown file that Claude Code automatically loads into context at the start of every session in your project. It's delivered as instructions Claude reads after its system prompt — persistent project memory that survives between conversations, so you don't have to restate your stack, commands, and conventions each time. Worth being clear: it guides behaviour rather than enforcing it. There's no guarantee of strict compliance, especially for vague or conflicting instructions, which is exactly why specific, checkable rules outperform broad ones.

There is no required schema. It's plain prose and bullets. The whole idea is to write down the things a new teammate would need to be productive: how to build and test, what the code style is, where things live, and the handful of "always do X / never do Y" rules that matter for your project.

Where does CLAUDE.md live?

Claude Code looks in several places and concatenates what it finds. Closer, more specific files are read later in the context, so local rules usually carry more weight than broad ones. The main locations:

When Claude Code starts, it walks up the directory tree from your working directory and loads each CLAUDE.md it finds, concatenated from the filesystem root down to where you are. Subdirectory files are pulled in when Claude actually touches files in those directories, which keeps the active context focused instead of dumping every rule for every part of the codebase into every session. For larger or path-scoped rule sets, you can also split instructions into files under .claude/rules/ so they only load when relevant.

You can also pull in other files with the @path/to/file import syntax. Imported files are expanded inline at launch, and imports can recurse up to four hops deep — handy for keeping one shared standards file and importing it from several places.

Why does CLAUDE.md matter?

Two reasons, both about removing friction:

• It stops the re-explaining. Every fact you'd otherwise type at the top of a prompt — "we use pnpm, run tests with vitest, this is a monorepo, don't touch the generated files" — lives in the file and is present in every session automatically.
• It encodes conventions Claude can't infer from code alone. Your code shows what you do, not the rules behind it: which test to run first, which patterns are deprecated, what "done" looks like, how you want commits formatted. That tacit knowledge is exactly what belongs in CLAUDE.md.

The practical payoff: the better you document your workflows, tools, and expectations, the better Claude performs on routine work, because it can lean on your existing patterns instead of reinventing them.

What goes in a strong CLAUDE.md? (the anatomy)

A good file is short and skimmable. Think of it as a set of sections, each just long enough to be unambiguous:

The fastest way to a first draft is the built-in /init command, which scans your project for its build system, test framework, and patterns, then writes a starter CLAUDE.md you refine by hand. Use /memory at any time to see which instruction files Claude has loaded and to edit them — that's your debugging tool when a rule you expect to be active isn't being followed.

What does a good CLAUDE.md example look like?

Here's a compact, annotated example for a TypeScript web app. Adapt the specifics — the shape is the point, not the contents.

# Project: Acme Dashboard

Next.js + TypeScript admin dashboard. pnpm monorepo; app code in `apps/web`,
shared UI in `packages/ui`.

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`            # runs apps/web on :3000
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`
- Test (single file preferred): `pnpm vitest run path/to/file.test.ts`

## Code style
- ES modules only (import/export), no `require`.
- Components are function components; no class components.
- Prefer named exports. Co-locate tests next to source as `*.test.ts`.

## Rules
- ALWAYS run `pnpm typecheck` after changing code, before saying you're done.
- NEVER edit anything under `packages/api/generated/` — it's codegen.
- Prefer editing an existing file over creating a new one.
- Keep changes surgical: change only what the task needs.

## Architecture
- Data fetching lives in `apps/web/lib/queries/`; UI never calls fetch directly.
- Auth is NextAuth; the session is the source of truth for the user identity.

## Done means
- Typecheck passes, the touched test file passes, and the diff is minimal.

Notice what this file doesn't do: it doesn't say "write clean code" or "follow best practices." Every line is either a concrete command, a concrete "don't," or a checkable definition of done. Vague directives waste context; specific ones change behaviour.

Should you use the viral "Karpathy-style" CLAUDE.md rules?

In 2026 a community-distilled CLAUDE.md went viral by packaging four behavioural principles for coding agents — framed around Andrej Karpathy's public commentary on how LLMs fail at coding (it's a community interpretation, not an official spec he authored): think before coding, keep the implementation simple, make surgical changes, and define success criteria then verify them. It caught on because it names concrete rails instead of platitudes.

The catch, called out by the people who popularised it: copying it unchanged is the fastest way to misuse it. Steal the shape — numbered, falsifiable rules — then rewrite each one with your own commands, file paths, and test gates. A rule like "make surgical changes" only earns its place when you pair it with what "surgical" means in your repo and how you'd check it. If, after a week, your diffs aren't smaller and your rewrites aren't fewer, the file isn't working — tune it.

What are the most common CLAUDE.md mistakes?

• Making it too long. A sprawling file buries the rules that matter and burns context budget. Keep it tight — many practitioners aim for well under a couple hundred lines and push the rest into imported, scoped files.
• Dumping the whole README. The README is for humans onboarding; CLAUDE.md is for the rules Claude needs in every session. Marketing copy, install prose, and history don't belong here.
• Being vague. "Write good code" and "follow conventions" are unactionable. Replace them with the actual command, the actual path, the actual constraint.
• Letting it go stale. When you change a test command or deprecate a pattern, update the file in the same change. A CLAUDE.md that lies is worse than none — Claude will confidently do the wrong thing.
• Writing prose, not rules. Headers, bullets, and imperatives retrieve better than paragraphs. Lead each rule with a verb.

How does CLAUDE.md relate to AGENTS.md and Cursor rules?

Different tools read different files. Claude Code reads CLAUDE.md; AGENTS.md is a cross-tool format supported by a growing set of agents (including OpenAI's Codex); Cursor uses its own rules files. Claude Code does not read AGENTS.md directly. If your team keeps a single shared AGENTS.md as the source of truth, the clean bridge is to import it from CLAUDE.md and add only Claude-specific overrides below:

@AGENTS.md

## Claude-specific overrides
- <anything that only applies to Claude Code>

A symlink (ln -s AGENTS.md CLAUDE.md) also works, but the import is more portable across operating systems and survives a fresh clone without anyone needing special permissions. For a full side-by-side of the three formats — including what each tool reads and how to keep them in sync — see our breakdown of AGENTS.md vs CLAUDE.md vs Cursor rules.

How do you keep a CLAUDE.md useful over time?

• Write in imperatives. "Run typecheck before finishing" beats "the project values type safety."
• Keep it tight and scoped. Put broad rules in the root file; push directory-specific detail into a nested CLAUDE.md so it only loads when relevant.
• Update it as you learn. When you catch Claude doing something wrong twice, add the rule that prevents it. Use /memory to edit, and /init to bootstrap a new repo.
• Make rules checkable. Pair every "do X" with how Claude can verify it — a command to run, a test that should pass.

If you want to go deeper on the tools that consume these files, our guide to AI coding agents and Cursor IDE guide cover the wider workflow around them.

Frequently asked questions

Where should I put my CLAUDE.md file?

Put the main one in your project root and check it into git so the whole team shares it. Add personal, cross-project preferences in ~/.claude/CLAUDE.md, directory-specific rules in a nested CLAUDE.md, and untracked personal overrides in CLAUDE.local.md (which you gitignore).

How long should a CLAUDE.md file be?

Short. The file competes for context, so concise and skimmable beats exhaustive. A common rule of thumb is to keep the root file well under a couple hundred lines and move anything longer into scoped, imported files. Optimise for the rules Claude needs every session, not coverage.

Does Claude Code read AGENTS.md?

Not directly — Claude Code reads CLAUDE.md. If you maintain a shared AGENTS.md, bridge it by importing it from CLAUDE.md with @AGENTS.md (or by symlinking), then add any Claude-specific overrides below the import.

How do I create a CLAUDE.md quickly?

Run the /init command inside Claude Code. It analyses your project — build system, test framework, code patterns — and writes a starter CLAUDE.md you then refine by hand. Use /memory afterward to view and edit the loaded instruction files.

Should I copy a viral CLAUDE.md template?

Use it as a menu, not a template. Borrow the structure — short, numbered, checkable rules — but rewrite each rule with your own commands, paths, and definitions of done. A copied file full of generic advice won't change Claude's behaviour the way project-specific rules will.

What's the difference between CLAUDE.md and the README?

The README onboards humans; CLAUDE.md gives Claude the rules it needs in every session. Don't paste your README into CLAUDE.md — keep the latter focused on commands, conventions, guardrails, and verification steps.

A strong CLAUDE.md is a low-effort way to make an AI coding workflow more reliable: write it once, keep it honest, and Claude spends its effort on your problem instead of relearning your project. If you're scaling up agentic development and want experienced engineers who already work this way, Codersera can help you extend your team with vetted remote developers.