How to write a CLAUDE.md file Claude Code follows

Claude Code reads a plain text file you place in your project before it answers anything. Write your conventions there once and Claude applies them without being asked, every session, on every request. Get this file right and you stop repeating yourself; get it wrong and your most important rules drown in noise.

Filename: CLAUDE.md (project root) or ~/.claude/CLAUDE.md (global)

# My project
 
## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
 
## Conventions
- TypeScript only, no `any`.
- Use `async`/`await`. Never `.then()` chains.
- Components in `src/components`, one file per component.
 
## Do not
- Commit `.env` files.
- Add `console.log` to production paths.

What is the difference between CLAUDE.md and AGENTS.md?

Claude Code reads CLAUDE.md first. It will also pick up an AGENTS.md at the root if one is present, which is handy when your repo already keeps a generic rules file. The simple rule: put your real conventions in CLAUDE.md. If you also want a vendor-neutral file at the root, keep AGENTS.md short and have it point back at CLAUDE.md rather than duplicating every rule in two places. Two copies drift; one source of truth does not.

What should I put in a CLAUDE.md file?

Write the things you would otherwise have to say on every request.

Good candidates:

Build, test, and lint commands. The agent needs to run them; it should not have to guess.
Coding conventions that differ from obvious defaults: language choice, import style, naming rules, formatter settings.
Architecture notes: where things live, what a folder is for, what to reach for before hand-rolling something.
Explicit do/don't rules: never use .then(), always add a unit test, never commit secrets.
Pointers to docs rather than the docs themselves. A line like "UI components: see docs/design-system.md" is better than copying the whole doc in.

Bad candidates:

Long reference docs pasted verbatim.
Explanations of how the framework works (the agent already knows).
Style preferences you have never enforced (they add noise without value).Common gotchaThe pitfall here is writing aspirational rules ("write clean, maintainable code", "always think carefully") instead of checkable ones. The agent cannot act on a vibe, so it quietly skips them while they still burn tokens and dilute the rules that matter.Write only rules with a verifiable outcome, like "run npm test before claiming done" or "never edit files under src/generated/", and you can confirm at a glance whether they were obeyed.

Does CLAUDE.md cost tokens on every request?

The rules file is prepended to every single request the agent makes, including small ones like "what does this function do?" That means every line you write costs tokens on every turn.

A bloated file raises cost and, more importantly, dilutes the signal. The model gives every section roughly equal weight. Burying your three most important rules in five hundred lines of boilerplate makes them less effective, not more.

Bloated, do not do this

# Engineering Handbook v2.3
 
Welcome to the project! This document contains everything you need to know.
 
## Background
We started this project in 2022 to address the growing need for...
 
## Philosophy
We believe software should be simple. Simple code is easy to read...
 
## TypeScript style guide (full)
### Naming conventions
- Variables: camelCase
- Types: PascalCase
- Enums: PascalCase
- Constants: SCREAMING_SNAKE_CASE
...200 more lines...
 
## Framework guide
React is a JavaScript library for building user interfaces. Components are...

Lean, do this instead

# Conventions
 
Build: `npm run build` · Test: `npm test` · Lint: `npm run lint`
 
- TypeScript. No `any`. No `.then()` chains.
- One component per file in `src/components`.
- Reach for `src/components/` before hand-rolling a button or input.
- Do not commit `.env`. Do not add `console.log` in `src/api/`.
- Full style guide: docs/conventions.md

The lean version says the same things in a fraction of the tokens. Link to deeper docs instead of pasting them.

Aim for under 200 lines. If yours is longer, cut the paragraphs and leave only the rules. Everything that needs explanation probably belongs in a separate linked doc.

How does Claude Code load rules files?

Project root file: loaded for every request when the agent runs inside that directory. Commit it to version control so the whole team gets the same context automatically.

User-level global file: applies across all your projects. Good for personal preferences that do not belong in the shared repo (editor habits, output style, preferred explanation depth). Claude Code uses ~/.claude/CLAUDE.md.

Nested files: Claude Code supports rules files deeper in the tree. A file at src/api/CLAUDE.md only loads when the agent is working inside src/api/. Use this to scope noisy or specialised rules so they do not pollute unrelated sessions.Common gotchaA rule a nested file holds is silent everywhere else, so a project-wide convention tucked into src/api/CLAUDE.md will not apply when the agent edits src/web/.Keep anything that must hold across the repo in the root file, and reserve nested files for rules that are local to that folder.

Load order: global first, then project root, then nested files. A nested rule that contradicts the global one wins because it is more specific.

This guide is about writing the rules file well. For the rest of the memory picture, the auto memory Claude keeps for itself and when to /clear versus /compact, see how Claude Code memory works.

A starter prompt

Try this prompt

Read my CLAUDE.md and tell me which rules you think are redundant or too vague to act on. Suggest cuts.

Running that every few months keeps the file from accumulating drift. The rules that survive should be the ones the agent uses. For the wider discipline of deciding what stays in the model's view at all, see context engineering.

In short