Start with the rules that should survive every session
CLAUDE.md is not a project diary. It is a concise instruction file for facts that must still be true when a new Claude Code session starts.
Write down the product, the stack, the commands that prove work is correct and the constraints an agent must not casually rewrite. Put changing task status somewhere else.
- Who the product is for and the problem it solves
- The framework, database and commands used to test or build it
- Coding, security and design constraints that do not change task by task
- Links to the current plan, requirements and task board
Keep active decisions out of the instruction file
A long CLAUDE.md gets ignored. Put durable rules in the file, then link to the feature plan and task record for work that is changing now.
At the end of a task, record what changed, what you verified and the next smallest action. That gives the next session a factual handoff instead of a summary it has to interpret.
Ask the agent to read before it writes
Name the instruction file, relevant feature brief, existing component and test before asking for a change. Then ask the agent to state the constraints it found before it edits code.
This is faster than discovering halfway through that the agent was working from an incomplete version of the project story.