The architecture-preserving code refactor loop

An AI coding-agent workflow for improving a targeted code area through dependency mapping, atomic refactors, baseline tests, and downstream regression checks without changing architecture or public contracts.

Use when

Use this for a focused readability, typing, maintainability, or performance refactor whose intended behavior and public contracts should remain unchanged.

The loop

Refactor [target] toward [measurable goal] in [repository]. If the target or goal is missing, ask and stop. Record current behavior and affected dependencies; select representative tests for boundaries and failure modes, then make one atomic change without altering public contracts unless authorized. Run the same tests, type and lint checks, and affected-consumer checks, keeping only regression-free improvements. Repeat for at most five rounds. Stop on success, blocked architecture, approval required, exhaustion, or no progress. Preserve unrelated work and finish with the diff, impact map, evidence, rejected attempts, and remaining debt.

Steps

• Define the target, measurable goal, current behavior, public contracts, and applicable baseline checks.
• Map internal call sites, upstream dependencies, and downstream consumers using the repository evidence available.
• Select or add representative tests for boundaries, type constraints, and failure modes without forcing arbitrary coverage work.
• Apply one atomic refactor and rerun the baseline, static checks, and affected-consumer checks.
• Keep only verified improvements and repeat for no more than five rounds before entering a terminal state.

Verification

The target improves without changing contracts or downstream behavior. The stated measurable goal is met, baseline behavior and public interfaces remain intact, and the relevant tests, type checks, lint checks, and affected-consumer checks pass under recorded conditions.

Why it works

A blast-radius map prevents a locally attractive change from breaking consumers elsewhere. Atomic iterations and fixed checks make it possible to reject a failed attempt without compounding uncertainty across later changes.