What CLAUDE.md Is and Where It Lives

CLAUDE.md is how you give Claude Code lasting instructions about your project. It is a plain Markdown file that Claude reads automatically when it starts. Instead of repeating the same context in every session, you write it once and it sticks.

What goes in it

Think of it as a short briefing. Good things to put in it: the commands you actually run, conventions the code follows, and rules Claude should respect every time. It is persistent project memory, not a one-off prompt.

Where it lives

CLAUDE.md can sit in a few places, and each has a purpose:

• ~/.claude/CLAUDE.md — your personal file, used across every project you work on.
• ./CLAUDE.md or ./.claude/CLAUDE.md — the project file, shared with your team through git.
• ./CLAUDE.local.md — personal notes for one project; add it to .gitignore so it stays private.

A simple project file might look like this:

# CLAUDE.md

## Commands
- `npm run dev` — start the dev server
- `npm test` — run the test suite

## Conventions
- Use the existing `lib/db.js` helper for database access.
- Keep API routes in `app/api/*`.

Why it helps

Because the project file is checked into git, everyone on the team gets the same guidance. New sessions start already knowing your setup, so you spend less time explaining and more time building. The rest of this series covers how these files load, how to write them well, and the tools that manage them.