CLAUDE.md: project memory

What you’ll be able to do

Create and maintain a CLAUDE.md that makes every session in your project start with the right knowledge.

What it is

CLAUDE.md is a Markdown file Claude Code reads automatically at the start of each session. Think of it as the onboarding note you’d give a new teammate: short, practical, and about this project.

Location	Scope	Commit it?
./CLAUDE.md or ./.claude/CLAUDE.md	This project, everyone	Yes
./CLAUDE.local.md	This project, just you	No (gitignore it)
~/.claude/CLAUDE.md	All your projects	n/a
subfolder/CLAUDE.md	Loaded when Claude works in that folder	Yes

Already using other coding agents? If your repo has an AGENTS.md and no CLAUDE.md, Claude Code reads AGENTS.md as its project instructions. To use both, put @AGENTS.md inside your CLAUDE.md to import it.

CLAUDE.md vs auto memory

Claude Code has a second, automatic memory. Auto memory is notes Claude writes itself as it learns your corrections and preferences. It’s stored per repository and loaded at the start of each session.

	CLAUDE.md	Auto memory
Written by	You	Claude
Contains	Rules and instructions	Learnings and patterns
Best for	Things that must always be true	Preferences picked up along the way

Open /memory to edit your CLAUDE.md files, view auto memory entries, or turn auto memory on and off. Neither one is enforced: for hard guarantees, use permissions and hooks (Module 4).

Step 1: Generate a starting point

In a real project:

/init

Claude explores the repo and drafts a CLAUDE.md. Don’t accept it blindly. It’s a first draft. (If /init finds configuration from another coding agent, it offers to carry it over.)

Step 2: Edit it down to what matters

A good CLAUDE.md is usually under a page. Keep:

• Commands: build, test (including a single test), lint, run locally
• Conventions Claude can’t infer: “use zod for validation”, “prefer named exports”
• Gotchas: “the legacy/ folder is frozen”, “migrations must be reversible”
• Workflow: “always run typecheck after changes”, “branch names: feat/...”

Cut:

• Anything obvious from reading the code
• Long explanations (link to docs instead)
• Secrets. Never put credentials in CLAUDE.md.

Example:

# Project: storefront-api

## Commands
- `pnpm dev`: run locally on :3000
- `pnpm test`: all tests · `pnpm test -- path/to/file`: one file
- `pnpm typecheck && pnpm lint`: run before saying a task is done

## Conventions
- Validation with zod schemas in `src/schemas/`, never ad-hoc checks
- DB access only through repositories in `src/repos/`
- No new dependencies without asking

## Gotchas
- `src/generated/` is produced by `pnpm codegen`. Never edit it by hand.

Step 3: Keep it alive

When you catch yourself correcting the same thing twice, add it. You can ask Claude to do it:

Add to CLAUDE.md: integration tests need `docker compose up -d db` first.

Or open the memory files with /memory. To find contradictions and stale rules across all your instruction files, run /doctor prompt-audit.

Emphasis works. If a rule keeps getting missed, make it stand out: “IMPORTANT: never edit src/generated/”. Use it sparingly, because if everything is important, nothing is.

Exercise

1. Run /init in a real project you work on.
2. Cut the draft by at least a third while keeping what matters.
3. Add one gotcha that only you know about.
4. /clear, then ask: “How do I run a single test file here, and what must I never edit?” Claude should answer from CLAUDE.md without searching.

Verify it worked

• Your project has a CLAUDE.md under ~60 lines
• It includes test commands and at least one gotcha
• After /clear, Claude answers project-convention questions correctly