1. Say it once, at the start of every session
Claude Code reads CLAUDE.md when a session starts. That file is the handbook: how to build, how to test, the conventions, and the gotchas a newcomer would not guess. The /init command can draft a starter. Read the draft. A generated handbook that you have not read is just a longer guess.
If the slash command has moved, the current Claude Code docs are the list. This page will not pretend a shortcut is permanent.
2. Gotchas beat generalities
The valuable lines are the ones that defy a normal assumption. The test must run from the repository root. The API returns dates in local time. The generated folder is never edited by hand. “Write clean code” is not a gotcha. The model has heard that sentence a million times, and it does not change the next edit.
Keep the file short. A bloated handbook dilutes the lines that matter. When Claude repeats a mistake, add one line. Every so often, delete the lines that no longer apply.
3. One place for each rule
Team conventions belong in the project file. Personal habits belong in your user-level configuration, not in the file every teammate will load. The same instruction in the handbook, a skill, and the prompt will eventually contradict itself. Pick one home.
Never put a secret in the file. A key in CLAUDE.md is a key in the chat, in the logs, and in the repository. Credentials stay in the place your team already keeps credentials.
4. A long chat is not a handbook
Long sessions fill with dead ends, and quality drops. Start a fresh session for unrelated work. /clear or /compact are the documented ways to shed a long thread. A compact is a summary, and a summary drops detail. The finish line belongs in the plan file, not only in the chat you are about to compress.
Small commits let you roll back when a run wanders. Claude Code also offers checkpoints and rewind. Read the current docs for what those restore before you trust them with a day’s work. The commit is the copy you already understand.
5. What to try next
Open CLAUDE.md. If it does not exist, create a short one: the build command, the test command, and three gotchas. Delete any sentence you would not notice if it vanished.
The corrections you make more than once belong in a skill or a command you can reuse.