Set Up CLAUDE.md: Project Memory That Stops the Repetition

If you find yourself telling Claude Code the same things at the start of every session — the build command, where the tests live, the conventions you follow, the directory it should never touch — that’s what CLAUDE.md is for. It’s a markdown file Claude Code reads as context when a session starts, so the project’s standing facts are always present without you typing them.

This is the highest-return, lowest-effort feature in Claude Code. Five minutes on a good CLAUDE.md saves you re-explaining your project in every conversation, and it makes the agent’s output match your project instead of generic defaults. This guide covers where the file goes, what belongs in it, the project-versus-user distinction, and how to keep it from bloating your context.

It’s the first thing to set up in any repo you’ll use regularly — start here before MCP servers or subagents, as the power-user guide recommends.

Where it lives#

There are two files, and they stack:

On Windows the user file is C:\Users\YourName\.claude\CLAUDE.md. When both exist, both load — the project file for repo-specific facts, the user file for your personal preferences. Put team conventions in the project file so everyone benefits; keep your own habits in the user file so they follow you without being forced on teammates.

What to put in it#

The test for any line: is this a durable fact about the project that you’d otherwise repeat? If yes, it belongs. If it’s a one-off task note, it doesn’t.

A solid project CLAUDE.md covers:

# Project: Acme API

## Commands
- Build: `npm run build`
- Test: `npm test` (run before every commit)
- Lint: `npm run lint`
- Dev server: `npm run dev` (port 3000)

## Stack
- Node + TypeScript, Express, PostgreSQL
- Tests: Vitest, in `__tests__/` next to source

## Conventions
- Conventional Commits for messages
- No raw SQL string interpolation — use the query builder
- All new endpoints require an auth check

## Don't
- Don't edit anything in `generated/` — it's built
- Don't touch the migration files in `db/migrations/` without asking

Short, specific, and all of it the kind of thing you’d otherwise say out loud. The “Don’t” section earns its place fast — it’s how you stop the agent wandering into generated code or rewriting migrations.

Keep it lean#

Here’s the discipline. CLAUDE.md loads every session, so its length is a standing context cost — the same kind of cost connected MCP servers carry. A bloated memory file quietly shrinks the window you have for actual work.

So write it tight. Durable facts only. Resist the urge to paste your whole architecture doc into it. If the agent needs deep detail occasionally, that’s what references are for.

Reference other files instead of inlining#

When you have detailed material — a long style guide, an architecture overview, API conventions — keep it in its own file and reference it from CLAUDE.md. That way the main file stays short and the detail loads when it’s relevant rather than every session.

## Detailed guides
See @docs/architecture.md for the system overview.
See @docs/api-conventions.md for endpoint standards.

The exact import syntax and how referenced files are pulled in can change, so confirm it in the memory documentation. The principle holds regardless: short core file, detail behind references.

User-level memory for personal preferences#

Your ~/.claude/CLAUDE.md is for things that are about you, not any one project — your preferred commit style, that you want concise explanations, tools you always reach for. Because it applies everywhere, keep it to genuine cross-project preferences. Project-specific facts belong in the project file, not here, or they’ll leak into repos where they don’t apply.

Keep it current#

A CLAUDE.md that’s out of date is worse than none, because the agent trusts it. When the build command changes, the test framework moves, or a convention is dropped, update the file. Treat it like code: when it’s a project file, review changes to it in pull requests, the same as any other shared configuration.

Wrapping up#

CLAUDE.md is the cheapest big win in Claude Code. A short, accurate file at your repo root means the agent knows how to build and test, follows your conventions, and stays out of the directories you’ve flagged — all without you re-explaining anything. Keep it tight, reference detail rather than inlining it, use the user file for personal preferences, and update it when the project changes.

Set this up first, then layer on the rest of the power-user features — MCP servers, skills, and subagents — on top of a project the agent already understands.