CLAUDE.md and project memory

Each Claude Code session starts with a blank conversation. It does not remember yesterday. A file named CLAUDE.md fixes most of that: Claude Code reads it at the start of a session, so your standing instructions are already in place.

Details here come from the memory page of the official docs (code.claude.com/docs). Check it for changes.

Where the file lives

• Project: ./CLAUDE.md or ./.claude/CLAUDE.md in your repository. Commit it so your whole team shares it.
• Personal: ~/.claude/CLAUDE.md in your home folder, for preferences that apply to every project.

Project instructions describe the project. Personal instructions describe you.

Generate a first draft

Inside a session, run:

/init

Claude Code looks at your project and drafts a CLAUDE.md. If one already exists, it suggests improvements instead. Treat the draft as a starting point and edit it. You know things the code does not say.

Run /memory to see and open the memory files that are loaded.

What belongs in it

Keep it short. Every line costs attention, and long files get followed less reliably. Good content:

• How to build, run, and test, with the exact commands.
• Conventions that are not obvious from the code: naming, folder layout, style rules.
• Hard rules: things never to touch, such as generated files or a production config.
• Gotchas that cost you an hour once.

A small example:

# My Site

## Commands
- Run: npm run dev
- Test: npm test
- Lint: npm run lint

## Rules
- Never edit files in /dist (generated).
- Use plain CSS, no frameworks.
- Keep pages under 100 lines of HTML.

## Gotchas
- Images must be added to /public, not /src.

What does not belong

• Secrets. Never put keys or passwords in a file you commit.
• Long documentation. Link to it instead.
• Vague advice like "write good code." Claude already tries.
• Things that rot quickly. Out-of-date instructions are worse than none.

Importing other files

You can pull another file in with an @ path, such as @docs/style-guide.md. This keeps CLAUDE.md short while letting Claude reach longer references. Imports written inside code spans or code blocks are ignored, so write them as plain text.

Keep it alive

When Claude makes the same mistake twice, that is a hint that a rule is missing. Add one line and move on. You can also ask in-session: "Add a rule to CLAUDE.md that tests must be run before commits." Review the change like any other edit. Every few weeks, delete lines that are stale.

Try it

In a project you own, run /init and read the result. Delete anything wrong or obvious. Add exactly three things: the test command, one rule you care about, and one gotcha. Then run /clear, start fresh, and ask: "What are the rules for this project?" If the answer misses something you wrote, shorten or reword that line.