CLAUDE.md: what to put in it, with a template

CLAUDE.md is a plain Markdown file that Claude Code reads at the start of every session. It holds what Claude can't work out from your code: the exact commands to run, your project's conventions, and the things it must never do. Put it at the root of your repository and keep it under 200 lines.

Below: where Claude Code looks for the file, what to put in it and leave out, how it fits with AGENTS.md, a template to copy and a filled-in example for a Next.js and Supabase SaaS. Everything was checked against Anthropic's memory docs in October 2026.

What is a CLAUDE.md file?

A CLAUDE.md file is a set of standing instructions for Claude Code that you write once and that loads into every session. It replaces the notes you would otherwise retype at the start of each chat.

Claude treats it as context, not as configuration it must obey, and Anthropic's docs say the more specific and concise your instructions, the more consistently Claude follows them. If something has to happen every single time, such as running a formatter after each edit, use a hook instead. Hooks run as shell commands at fixed points, whatever Claude decides.

It is also different from auto memory, the notes Claude writes for itself from your corrections. Those are Claude's. CLAUDE.md is yours, and it is the one you commit.

Where does Claude Code look for CLAUDE.md?

Claude Code reads CLAUDE.md files from four scopes: your organization's managed file, your user file, the project file and a personal local file. It loads every one it finds and joins them together, so none replaces another.

Three rules decide what loads and when:

1. Parent folders load at launch. Start Claude in apps/web and it reads apps/web/CLAUDE.md, the root CLAUDE.md, and any CLAUDE.local.md beside them, top of the tree first, so the closest file is read last.
2. Subfolders load on demand. A CLAUDE.md in a folder below where you started loads the first time Claude reads or edits a file there. That is how a monorepo gives each package its own rules.
3. Rules can be scoped by path. Markdown files in .claude/rules/ load like the project file. Give one a paths list in its frontmatter, such as "src/api/**/*.ts", and it loads only when Claude works on matching files.

To see what actually loaded, run /context and look under Memory files. /memory lists every location and opens the file you pick in your editor.

How do imports work in CLAUDE.md?

Write @ followed by a path anywhere in the file, and Claude Code loads that file into context at launch, next to the CLAUDE.md that mentions it. Relative paths resolve from the file containing the import, not from the folder where you started Claude.

See @README.md for the project overview and @package.json for the scripts.

## Git workflow
- Follow @docs/git-workflow.md

Three details are worth knowing:

• Imported files can import other files, up to four hops deep.
• Imports organize a long file but don't shrink it. Everything imported loads at launch and uses context like the rest.
• The first time Claude Code meets an import that points outside your project, such as a file in your home folder, it asks you to approve it. That protects you from imports someone else committed to a shared repository.

What should you put in CLAUDE.md?

Put in what Claude would get wrong without being told: commands it can't guess, conventions that differ from the defaults, and boundaries. Anthropic's test for every line is a single question: would removing this cause Claude to make mistakes? If not, cut it.

Six kinds of line pass:

• Commands, exactly as you type them. Dev server, type check, lint, the full test suite and a single test file. "Run pnpm test before committing" works. "Test your changes" doesn't.
• Conventions that differ from the defaults. Where server-only code lives, how migrations are named, which component library to use.
• Decisions Claude can't infer from the code. In a SaaS the big one is how customers' data is kept apart: every row has an account_id, and row-level security enforces it.
• Gotchas. The environment variable that must be set, the generated file never to edit, the command that must run after a schema change.
• Boundaries. What Claude must never do, and what it must ask you about first.
• A definition of done. The checks to run before Claude says it has finished.

Write each line so you could check it in a code review. "Use 2-space indentation" gets followed, "format code properly" doesn't. Group lines under short headings, since organized sections are easier to follow than a dense paragraph.

What should you leave out of CLAUDE.md?

Leave out anything Claude can learn from the code, anything that changes often, and anything it needs only now and then. Anthropic recommends under 200 lines per file: longer files use more context and their rules get lost.

One more detail: block-level HTML comments in a CLAUDE.md are stripped before Claude sees the file, so notes for maintainers cost no context.

CLAUDE.md vs AGENTS.md: do you need both?

If everyone on the project uses Claude Code, CLAUDE.md alone is enough. If your team also uses Codex, Cursor, Copilot or another agent, keep the shared rules in AGENTS.md and make CLAUDE.md a one-line import of it, so every agent reads the same file.

AGENTS.md is the open format most other coding agents read. As of October 2026, Claude Code reads it too, from v2.1.277, with one condition: only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your folder or any folder above it.

The import works everywhere: on older versions, in sessions that can't read AGENTS.md directly, and in repositories that keep a CLAUDE.md. Claude-only notes go below it:

@AGENTS.md

## Claude Code only
- Use plan mode for any change under `supabase/migrations/`.

Write the import, not a sentence. "Read AGENTS.md first" works only if Claude decides to open the file, while @AGENTS.md loads it every time. A symlink also works, but Anthropic recommends the import if anyone works on Windows, where a committed symlink can check out as a one-line text file.

Starting from nothing? The free AGENTS.md generator writes the AGENTS.md and the one-line CLAUDE.md pointer for you. The AGENTS.md guide covers how the other agents find the file.

A CLAUDE.md template you can copy

Replace each placeholder, delete any section you don't need, and keep the result short.

# CLAUDE.md

<One line: what this project is and its main stack.>

## Commands
- Install: `<install command>`
- Dev server: `<dev command>` (<local URL>)
- Type check: `<typecheck command>`
- Lint: `<lint command>`
- All tests: `<test command>`. One file: `<single-file test command>`

## Where things live
- `<folder>/`: <what goes here>
- `<folder>/`: <what goes here>
- `<generated folder>/`: generated. Do not edit.

## Rules
- <A convention that differs from the default, written so a reviewer can check it>
- <How data, money or state must be handled>

## Ask before
- <Adding a dependency>
- <Changing the database schema>

## Never
- <Commit `.env` files or print secret values>

## Before you finish
1. <Your checks> pass.
2. Summarise what changed and anything you could not verify.

Example: CLAUDE.md for a Next.js and Supabase SaaS

Here is the template filled in for a multi-tenant SaaS built on the Next.js App Router and Supabase, with pnpm and the Supabase CLI.

# CLAUDE.md

Invoicing SaaS. Next.js App Router, Supabase (Postgres, Auth), Stripe. pnpm.

## Commands
- Dev: `pnpm dev` (http://localhost:3000). Local database: `supabase start`
- Type check: `pnpm typecheck`. Lint: `pnpm lint`
- Unit tests: `pnpm test`. One file: `pnpm test src/lib/tax.test.ts`
- Database tests (pgTAP): `supabase test db`
- New migration: `supabase migration new <name>`, then `supabase db reset`
- After any schema change: `supabase gen types typescript --local > src/lib/database.types.ts`

## Where things live
- `src/server/`: server-only code. Every file starts with `import 'server-only'`.
- `supabase/migrations/`: one SQL file per change. Never edit one that has been applied.
- `src/lib/database.types.ts`: generated. Do not edit.

## Data and security
- Every customer table has `account_id`, and its migration enables row-level security.
- Policies check membership with `public.is_member(account_id)`. Don't rewrite the check inline.
- Every new table gets a pgTAP test that signs in as a user from another account and fails to read or write.
- Use the normal server client so policies apply. The service-role client is only for webhooks in `src/server/webhooks/`.

## Ask before
- Adding a dependency, changing a policy, or editing `src/server/billing/`.

## Never
- Import the service-role key or anything in `src/server/` into a client component.
- Commit `.env*` files or print secret values.
- Run commands against the production project.

## Before you finish
1. `pnpm typecheck && pnpm lint && pnpm test` pass, plus `supabase test db` if the schema changed.
2. Tell me what changed and anything you could not check.

Every command is exact, every security rule can be checked against a diff, and the service-role client, which skips row-level security, has one fixed home. What Claude can read for itself, such as the folder tour and the dependency list, stays out.

The last "Never" line matters more once Claude has database tools. If you connect the Supabase MCP server, point it at a development project. The reasoning behind the security lines is in Supabase RLS explained.

How do you keep CLAUDE.md accurate?

Treat it like code: review it when Claude goes wrong, prune it regularly, and check that each change actually shifts Claude's behaviour.

1. Start with /init. It scans the codebase and writes a first CLAUDE.md with build and test commands, or suggests improvements if one exists. Cut what Claude could have found on its own and add what it couldn't.
2. Add a line when Claude makes the same mistake twice, or a code review catches something it should have known. Remove one the day a command or folder changes: Claude trusts an out-of-date command.
3. Run an audit. As of October 2026, /doctor prompt-audit (v2.1.283 and later) checks your CLAUDE.md, CLAUDE.local.md and AGENTS.md files, plus your rules and skills, for references to files or commands that don't exist and for files that contradict each other. It proposes edits and changes nothing until you ask it to.
4. Use emphasis sparingly. If Claude keeps skipping one rule, add "IMPORTANT" to that line alone. Emphasise many lines and none of them stands out.

The file is one part of a wider workflow. Claude Code best practices for building a SaaS covers the rest: planning, checks, permissions and reviews.

How shipanysaas sets it up

shipanysaas, the SaaS starter kit this blog belongs to, uses the import pattern throughout. The root CLAUDE.md is the single line @AGENTS.md, and every app and package with its own AGENTS.md has a nested CLAUDE.md, such as apps/web/supabase/CLAUDE.md, that does the same for its folder. The rules themselves live once, in the AGENTS.md files that Codex, Cursor and the other agents read too.

The root AGENTS.md is under 150 lines and ends with the checks every agent must run, from pnpm typecheck to /rls-review after any database change. Coding agents lists every file, and pricing shows what each plan includes.

FAQ

Where should CLAUDE.md go?

At the root of your repository, as CLAUDE.md or .claude/CLAUDE.md, committed to git. Preferences you want in every project go in ~/.claude/CLAUDE.md, and personal notes for one project go in CLAUDE.local.md, which you add to .gitignore.

How long should a CLAUDE.md be?

Under 200 lines per file is Anthropic's target. Claude Code loads a file of up to 4 MiB in full, but longer files use more context and are followed less closely. Move procedures into skills and folder-specific rules into nested files.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277, but by default only when there is no CLAUDE.md in your folder or above it. If you have both, start CLAUDE.md with @AGENTS.md and Claude reads the two together.

Does CLAUDE.md survive /compact?

The project-root file does: Claude Code re-reads it from disk after /compact. Nested files reload the next time Claude works in their folder. An instruction you only typed in chat can be lost.