Every Claude Code project I run now uses the same shape: one CLAUDE.md at the repo root with the design system, security rules, and content discipline, plus a PHASE-N.md for each chunk of work I want to ship as a unit.
The split matters. CLAUDE.md answers what is this project and what are the rules I never want to relax. The phase file answers what are we doing right now and what’s out of scope. When the two collide, the root file wins; that gets stated explicitly in the phase file, so there’s no ambiguity.
A phase file tends to have four things:
- Pre-flight: which docs to read first, in what order
- Tasks: numbered, in build order, with the actual decisions called out
- Out of scope: what belongs to later phases, so the model doesn’t quietly expand the work
- Quality bar: what “done” looks like before the commit goes in
Most of the value isn’t in the prompt itself. It’s in the constraint that I have to write the prompt before I start.
Forcing the spec before the work surfaces every ambiguity I would otherwise discover halfway through implementation. That’s the part that compounds.