Claude Code Build Loop
Quality-gated feature work: nothing ships on "it compiles" — every increment is built, reviewed, tested end to end, and fixed before the user hears "done."
Source of work
- A plan file exists (roadmap, refactor plan, or task list with
- [ ]checkboxes — search the repo): work the first unchecked task. Tasks are ordered intentionally — never skip ahead. If the plan references spec docs, read only the sections relevant to the current task. - No plan (or the request is outside it): build from the user's prompt. Restate it as a verifiable goal with 2–4 success criteria and confirm scope in one message before building.
The loop
Run per task (or per prompted feature). Do not advance until every step passes.
- Build. Implement exactly what the task specifies. Simplest implementation that satisfies it, surgical changes, no speculative scope. Match existing project conventions.
- Review. Run
/reviewon the changed code. If the change touches auth, payments, user input, or data access, also run/security-review. Fix all findings in scope — bugs, security issues, edge cases, performance, style in files you touched. If the project has a design system spec (design tokens file, DESIGN.md, theme config), check UI changes against it — no hardcoded colors, type, or spacing that bypass tokens. Note pre-existing issues in untouched code for the report instead of fixing silently. Re-run/reviewuntil clean. If a finding contradicts the task or spec, the spec wins — flag the disagreement.
- Test end to end. Run the task's verification step (or the success criteria). Run the full test suite — everything that passed before must still pass. Add tests for new logic. Then exercise the feature as a user would: run the app, walk the real flow including empty, loading, and error states.
- Fix. Anything testing finds goes back through the loop: fix →
/review→ re-test. Never mark a failing task complete; never start the next task with the app broken.
- Continue. Mark the task
- [x], update any progress/status line in the plan, and loop to the next task until the requested scope is complete.
- Report. When done, tell the user: what was built and plan progress, review findings fixed and anything deferred, how it was verified (tests + flow walked), and what needs their attention next. Be honest about anything flaky or partially verified.
Rules
- Skipped review or untested work = unfinished work.
- Don't relitigate plan decisions; if a task seems wrong, ask one specific question rather than guessing.
- Discovered work no task covers? Surface it and propose a task — never silently expand scope.
