Guide · Context & Memory

What is CLAUDE.md and what should you put in it?

Published 1 August 2026

CLAUDE.md is a plain Markdown file that Claude Code reads automatically at the start of every session and treats as standing instructions. It is not a prompt you paste, not documentation for humans, and not a place for architecture essays. It is the working agreement between you and the model: the conventions, commands and hard rules that should hold on every task in this repository, without you restating them.

Where Claude looks for it

Claude Code walks up from your working directory and loads every CLAUDE.md it finds, nearest file last. In practice you get three useful layers:

  • Repository root — ./CLAUDE.md, committed to git. The shared agreement for everyone on the team.
  • Subdirectory — ./packages/api/CLAUDE.md. Rules that only apply inside that package; loaded when work touches it.
  • Personal — ~/.claude/CLAUDE.md for your own habits, and ./CLAUDE.local.md (gitignored) for machine-specific notes.

Because the layers stack, keep each one narrow. If a rule is true for the whole repo it belongs at the root; if it is true only for your laptop it belongs in the local file. Duplicating a rule in both is how contradictions get shipped.

What belongs in it

The test for any line is simple: would the model get this wrong or waste a turn discovering it? If yes, write it down. If the model can read it from the code in one glance, leave it out.

  • Commands that are not guessable. The exact test, lint, typecheck and dev commands, including the package manager. bun test src/foo.test.ts beats "run the tests".
  • Conventions with teeth. "Use the existing Result type instead of throwing", "all timestamps stored UTC", "no new dependencies without asking".
  • Hard prohibitions. Files never to edit (generated clients, migrations already shipped), commands never to run (git push, destructive migrations), directories that are read-only.
  • Non-obvious architecture. The two or three facts that explain the layout — "every DB write goes through src/db/mutations", "edge functions cannot import from src/".
  • Definition of done. What must pass before work is reported complete: typecheck clean, tests green, no new console warnings.

What should never be in it

CLAUDE.md is loaded into context on every session, so every line you add is a permanent tax on the context window and a permanent competitor for the model's attention. That makes three things actively harmful:

  • Secrets. API keys, connection strings, staging passwords. The file is committed, and its contents flow into model context and logs. Reference the env var name instead.
  • Content that goes stale. Long file trees, function-by-function API listings, changelogs. When the code moves, the file lies — and a lying CLAUDE.md is worse than none, because the model trusts it over the repository.
  • Essays. A 2,000-line CLAUDE.md does not make the model more obedient; it dilutes the ten rules that actually matter. Treat 100–200 lines as a ceiling and cut something whenever you add.

A concrete example

This is a complete, working root file for a Vite + Supabase project. Note that every line is either a command, a constraint or a hard prohibition — nothing is descriptive prose:

# CLAUDE.md

## Commands
- Install: `bun install`
- Dev: `bun run dev` (port 8080, already running — do not restart)
- Typecheck: `bunx tsgo --noEmit`
- Test one file: `bunx vitest run src/lib/money.test.ts`

## Conventions
- Money is stored in integer minor units. Never floats.
- All dates are UTC ISO strings at the boundary; format only in components.
- Colours come from CSS tokens in `src/index.css`. Never `text-white`, never hex.
- New tables need RLS policies AND grants in the same migration.

## Never
- Never edit `src/integrations/supabase/types.ts` (generated).
- Never edit a migration that is already applied — add a new one.
- Never run git commands that change state (commit, push, reset).

## Done means
- Typecheck passes, affected tests pass, no new console errors at 375px width.

Roughly thirty lines, and it removes the four questions that otherwise cost a turn each at the start of every session.

Why it drifts, and how to keep it honest

The common failure is not a bad first draft — it is a file nobody maintains. Two habits fix that. First, edit CLAUDE.md at the moment you correct the model: if you had to say "no, use the existing helper" once, that correction belongs in the file so you never say it again. Second, review it like code. When a convention changes in a pull request, the CLAUDE.md line that describes it changes in the same pull request, or the reviewer blocks it.

A useful signal: if you find yourself repeating the same instruction in chat across sessions, your CLAUDE.md is missing a line. If the model follows a rule you no longer believe in, your CLAUDE.md has a line too many.

Review checklist

  • Can a new contributor run tests using only this file?
  • Is every line still true against today's code?
  • Are there zero secrets and zero generated listings?
  • Does each rule say what to do, not just what to avoid?
  • Is it short enough that you would read it yourself?

Where this fits

Standing configuration sits in the Context & Memory part of the track. The recurring judgement is which layer a rule belongs to: a system prompt for a single API call, Project instructions for a shared workspace, CLAUDE.md for repository work, or retrieval when the material is too large and too volatile to pin. Scope and lifetime decide — how many sessions the rule must survive, and how often it changes.

Related in this track

Keep going