CLAUDE.md

What CLAUDE.md is

CLAUDE.md is the file that teaches the agent your project. The agent reads it at the start of every session and treats it as standing instructions — conventions to follow, structure to respect, commands to run, and constraints not to violate.

If the agent keeps getting your style wrong, the answer is almost always “add it to CLAUDE.md” rather than “say it again in the chat.”

Where the agent looks

CLAUDE.md-style instructions are loaded from several places, in increasing precedence:

• User memory — ~/.claude/CLAUDE.md. Applies to every project on your machine.
• Project memory — CLAUDE.md at the repo root (and nested ones the agent descends into). Committed, shared with the team.
• Project-local memory — CLAUDE.local.md. Personal overrides, gitignored.

The contents are concatenated. Truncation behavior when the total is too long for context can change between versions — see the official docs rather than assuming a fixed drop order.

What belongs in it

Put in only what the agent cannot infer from the code:

• Build, test, lint commands — the exact invocations (the agent will run them).
• Architecture in brief — where the layers live, what depends on what.
• Non-negotiable conventions — the rules you would reject a PR for breaking.
• Things not to do — files or patterns the agent should never touch.
• Glossary — project-specific terms the agent would otherwise guess wrong.

What does NOT belong

• Secrets of any kind. CLAUDE.md is often committed; never put keys or tokens in it.
• The whole architecture document. If it is long, summarize and link.
• Anything the code already says. “We use TypeScript” is noise; the agent can see it.

When to use it

• You are about to onboard the agent to a new project — run /init to scaffold a first draft from the codebase, then edit it down.
• The agent keeps producing code that breaks a convention you assumed was obvious.
• You want a team-wide standard (e.g. “all new endpoints need a FormRequest”).

Two generic examples

Example A — commands block.

## Commands

- Build: `npm run build`
- Test (single file): `npm test -- path/to/file`
- Lint + fix: `npm run lint -- --fix`

Example B — a constraint.

## Non-negotiables

- Never disable CSRF on a form, even temporarily.
- All new routes must be behind the `auth` middleware.
- Do not commit to `main`; open a PR.

Pitfalls

• Letting it grow without pruning. A 2000-line CLAUDE.md gets truncated and the important parts lost. Review it monthly; delete what the code now says for you.
• Putting client/project secrets in it. It is a committed file. See Security.
• Contradicting the code. If CLAUDE.md says “we use Jest” but package.json says Vitest, the agent has to pick — and you will not like the result. Keep them in sync.