Full workflow
Use the narrative brief first, then execute the step summary in order.
When to use this workflow
Use this when backend code needs maintenance but the risk of a broad rewrite is too high. Codex should work from observable behavior, existing tests, and narrow boundaries.
Cleanup lane examples
Good lanes:
- One HTTP handler group.
- One persistence adapter.
- One queue worker.
- One schema validation path.
- One integration client.
Bad lanes:
- "Clean up the backend."
- "Make the architecture better."
- "Refactor all services."
Codex first prompt
text
We are doing backend cleanup, not a rewrite.
Inspect the target boundary and related tests before editing.
Identify behavior that must remain unchanged, missing verification, dead code candidates, and the smallest safe cleanup plan.
Do not edit files until the plan names exact files and commands.Verification ladder
Use the strongest practical gate for the cleanup:
- Unit tests for pure behavior.
- Integration tests for persistence or network seams.
- Migration dry run for schema changes.
- Smoke request for critical handlers.
- Log or metric check for production-sensitive paths.
Done criteria
The cleanup is done when the changed boundary is easier to explain, tests cover the behavior that matters, commands pass, and remaining risk is written in the handoff note. If a cleanup requires behavior changes, split that into a separate feature or fix branch.