CLAUDE.md is the memory file Claude Code reads at the start of a session to learn how to work in your project — its stack, key commands, conventions, what not to do, and the definition of done. It lives at the repo root (checked into git so the team shares it). Claude Code also reads a user-level ~/.claude/CLAUDE.md that applies across all your projects, and supports @path imports so one file can pull in others.

What should go in a CLAUDE.md file?

A one-line project overview, the stack, the key commands (build/test/lint/deploy), conventions the agent must follow, explicit don't-dos, and your definition of done. Keep it lean — research found bloated, dump-everything context files lowered task success ~3% and raised cost 20%+, while short curated ones improved success ~4%. Use @imports rather than pasting long docs inline.

Where does CLAUDE.md go, and what about ~/.claude/CLAUDE.md?

The project file goes at the repo root and is checked into git. The user-level ~/.claude/CLAUDE.md holds your personal, cross-project preferences and is read in addition to the project file. Claude Code reads CLAUDE.md files up the directory tree, and a subdirectory CLAUDE.md applies to work in that subtree (nearest-file-wins).

Is CLAUDE.md the same as AGENTS.md?

The content is the same; CLAUDE.md is just where Claude Code looks, with Claude-specific extras (@imports, the user-level file). AGENTS.md is the open standard read by 28+ tools. The clean setup is one source of truth — keep AGENTS.md and run ln -s AGENTS.md CLAUDE.md, or make CLAUDE.md a one-line @AGENTS.md import. See AGENTS.md vs CLAUDE.md for the full breakdown.

CLAUDE.md

CLAUDE.md is the memory file Claude Code reads at session start to learn your project — stack, commands, conventions, what not to do, definition of done. It lives at your repo root, supports @imports, and pairs with a user-level ~/.claude/CLAUDE.md.

Generate your CLAUDE.md free →

What is CLAUDE.md?

A plain-Markdown file Claude Code loads into context automatically when you start working in a repo. Its job is to give the agent the context a new teammate would need. It's the Claude-Code-native version of the same idea as AGENTS.md — same content, with two Claude-specific extras: @path imports and a user-level file.

What goes in a CLAUDE.md file?

Overview — one line on what the project is.
Stack — languages, framework, database, key libraries.
Commands — build, test, lint, dev, deploy.
Conventions — the decisions the agent must follow.
Don't — explicit anti-patterns and off-limits areas.
Definition of done — what must be true before a change ships.

CLAUDE.md example

# Acme Web

> Senior full-stack engineer. Small, reviewable diffs. Tests with every change.

@docs/architecture.md

## Stack
Next.js 15 (App Router) · TypeScript · Tailwind · Drizzle ORM · Postgres

## Commands
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint && pnpm typecheck`

## Conventions
- Server components by default; "use client" only when needed.
- All DB access through src/db/ (Drizzle) — never raw SQL in routes.

## Don't
- Don't add dependencies without asking.
- Don't commit secrets — use .env.local (see .env.example).

## Definition of done
- Lint + tests pass; new UI works at 375px.

Make one for your project →

Claude-specific features

@ imports. Reference other files instead of pasting them: @docs/architecture.md, @README.md, even @~/.claude/my-prefs.md. Keeps CLAUDE.md short and the source single.
User-level file. ~/.claude/CLAUDE.md holds your personal, cross-project preferences and is read in addition to the project file.
Hierarchy. Claude Code reads CLAUDE.md files up the directory tree; a subdirectory CLAUDE.md applies to work in that subtree (nearest-file-wins) — handy in monorepos.

Best practices

Keep it lean. ETH Zurich's Evaluating AGENTS.md found dump-everything files lowered task success ~3% and raised cost 20%+, while short curated ones improved success ~4%. Use @imports instead of inlining long docs.
Be specific. "DB access through src/db/" beats "write clean code."
One source of truth. If you also run other agents, keep AGENTS.md canonical and ln -s AGENTS.md CLAUDE.md (or @AGENTS.md) — don't maintain copies that drift.
Check it into git so the team shares the project file; keep personal prefs in ~/.claude/CLAUDE.md.

CLAUDE.md vs AGENTS.md

Same guidance, different readers — AGENTS.md is the open standard (28+ tools), CLAUDE.md is Claude Code's (with @imports + the user-level file). Full breakdown + the one-source setup: AGENTS.md vs CLAUDE.md →

Generate CLAUDE.md (and AGENTS.md, Cursor, Copilot, Gemini) — free

Fill in your project's rules once and get every file, correctly formatted, with a token-budget warning so they stay lean. No signup.

Open the Agent Memory Compiler →

Keep it in sync with your work

Generated files drift the moment your project changes. In TaskPrio your rules live in one place and your agents pull them over MCP with get_next_task — the memory and the task queue become one source of truth. Edit once; every agent stays current. See the MCP queue →

FAQ

What is CLAUDE.md?

Claude Code's memory file, auto-loaded at session start — stack, commands, conventions, don't-dos, definition of done. Lives at repo root; supports @imports + a user-level ~/.claude/CLAUDE.md.

What goes in it?

Overview, stack, commands, conventions, don't-dos, definition of done — kept lean; use @imports for long docs.

Is it the same as AGENTS.md?

Same content, different reader. Keep one source: ln -s AGENTS.md CLAUDE.md or @AGENTS.md.

Generate your CLAUDE.md → AGENTS.md vs CLAUDE.md →