CLAUDE.md best practices

A CLAUDE.md file is a plain Markdown file of standing instructions that Claude Code reads at the start of every session. Good ones are short. They hold how your team builds, and nothing that changes weekly. For the basics, see what a CLAUDE.md file is.

TL;DR

• Keep it under about 200 lines. Anthropic's docs say longer files use more context and reduce how well Claude follows them.
• Write what Claude cannot guess and would otherwise hear from you every session: commands, conventions, project layout, things not to touch.
• Leave out this week's priorities and customer evidence. Keep those in a shared plan.
• If you run more than one agent, put shared rules in AGENTS.md. Claude Code now reads it directly, so add a CLAUDE.md only for Claude-specific lines.

When to use it: any repository you work on with Claude Code more than once. When not: a throwaway script does not need one.

What belongs in a CLAUDE.md?

Anthropic's docs say to keep it to "facts Claude should hold in every session: build commands, conventions, project layout, 'always do X' rules." In practice that is five things.

1. Commands. How to install, run, build, test and lint. "Run npm test before committing" does more than "test your changes".
2. Conventions. Naming, formatting, how you write tests, how you name branches and commits.
3. Project layout. Where things live. "API handlers live in src/api/handlers/" saves a search every session.
4. Things not to touch. Generated files, the migrations folder, a vendored library. An agent that is not told where the edge is will tidy past it.
5. Decisions that stand. "We use Postgres, not a second database, because we are a team of two." Otherwise the agent reopens them.

Write each line so you could check it. Anthropic's docs give the pairs: "Use 2-space indentation" instead of "Format code properly", and "API handlers live in src/api/handlers/" instead of "Keep files organized".

What doesn't belong in it?

This week's priorities. What to build next changes every few days. A rules file is read at the start of every session, so a stale priority is read every session too, and nobody notices it is wrong.

Customer evidence. Quotes, accounts and revenue back a decision about what to build. They belong with the priority they support, in a plan every agent can read, not in a file that describes how you code.

One job's spec. The why, the files and the Done When lines for one piece of work go in that job's spec. See how to write a PRD for Claude Code.

Long procedures. Anthropic's docs say a multi-step procedure, or something that matters for only one part of the codebase, belongs in a skill or a path-scoped rule instead.

A simple test: if it will be false in a month, it does not belong here.

How long should it be?

Anthropic's docs target under 200 lines per CLAUDE.md file. Imports do not help with size: they organize a long file, but "imported files also load at launch", so they still cost context.

If you are over, do not compress the wording. Cut the lines that Claude would get right anyway, and move the rest. Two good signs a line can go: it describes something the code already shows, or no one has needed it in a month.

A CLAUDE.md template

Copy this, replace the angle brackets and delete any section you do not need. Run /init in Claude Code first if you want it to draft a starting point from your code, then trim it to this shape.

# <Project name>

<One line: what this is and who uses it.>

## Commands
- Install: <command>
- Run locally: <command>
- Test: <command>. Run it before every commit.
- Lint and format: <command>

## Project layout
- <folder>: <what lives there>
- <folder>: <what lives there>

## Conventions
- <Naming, formatting or test style, as a rule you can check>
- Branches: <pattern>. Commits: <pattern>.

## Do not touch
- <generated folder, vendored code, applied migrations>
- <anything that needs a person's yes first>

## Decisions that stand
- <Decision> because <reason>. Do not reopen.

## Working agreements
- Ask before adding a dependency.
- When a check fails, say which one and what you saw.

## Shared rules
@AGENTS.md

How do I add to it over time?

Treat it as the place you write down what you would otherwise re-explain. Anthropic's docs suggest adding a line when:

• Claude makes the same mistake a second time.
• A code review catches something Claude should have known about this codebase.
• You type the same correction in chat that you typed last session.
• A new teammate would need the same context.

Then remove a line each time you add one that replaces it. If two instructions contradict each other, Claude may pick one arbitrarily, so review the file when you review the code. Commit it, so the whole team edits one file.

How do I use a shared AGENTS.md?

If you also use Cursor, Codex or Grok, do not keep a second copy of your rules. AGENTS.md is an open Markdown format that these tools document reading, so put the shared rules there.

Claude Code now reads AGENTS.md too. When there is no CLAUDE.md in your working directory or above it, Claude reads your AGENTS.md as the project instructions (Claude Code v2.1.277 or later). So one AGENTS.md can be the only file you need.

If you want Claude-specific lines as well, make your CLAUDE.md import the shared file. Anthropic's docs show this:

• Create a CLAUDE.md next to your AGENTS.md.
• Put @AGENTS.md on the first line.
• Add any Claude-specific instructions below it.

Claude reads the imported file first, then the rest. Run /context in your next session and confirm CLAUDE.md appears under Memory files. The full comparison is in CLAUDE.md vs AGENTS.md.

How do I keep it current?

• Review it when you review code. A rule that no longer matches the code is worse than no rule.
• Date nothing. If a line needs a date, it is a priority, not a rule.
• Ask Claude to check it. Anthropic's docs describe a prompt audit that looks for outdated and conflicting instructions.
• Keep the moving parts elsewhere. What to build next, and why, lives in a plan your agents read, so the rules file can stay still.

Where does Annsa fit?

Your rules file holds how you work. Annsa holds what to build next and why. It is the source of direction for your agents.

• Ranked priorities. Requests come in from Slack, Intercom, call transcripts, surveys, imports, GitHub, the API or by hand, each with the customer's exact words, the account and its revenue. Inside your bets, in your order, what a person marked broken comes first, then what customers asked for, then ideas. You choose.
• Specs. Each priority has a spec with the why, the evidence and Done When lines. Your agent or Ask writes it.
• One list for every agent. Claude Code, Cursor, Codex and Grok connect over MCP (remote, nothing to install), claim the work, read the spec and record evidence against each Done When line.
• Decide once. A decision saved as a principle is read by every agent.

Annsa does not write your CLAUDE.md or AGENTS.md. See how to give AI coding agents product context, context engineering and the spec.

Sources: How Claude remembers your project, Anthropic, on CLAUDE.md, imports and AGENTS.md. AGENTS.md, the open format for guiding coding agents.