A useful model-assisted refactor starts with a plan you can challenge, not a patch you have to untangle. The strongest practices share a pattern: inspect the repository, define what must stay unchanged, expose uncertainty, and approve a small sequence of edits. This checklist turns those practices into a repeatable planning session before you touch code.
Set a read-only boundary for the planning session
Start by separating investigation from implementation. Use your coding tool’s read-only permissions where available; a prompt alone is not a permission boundary. Allow repository inspection, but require approval before edits, dependency changes, generated files, or commands that modify state.
Give the model a narrow brief: “Plan the extraction of invoice calculation from the HTTP handler. Do not change files. Preserve request validation, rounding, response fields, and error mapping. Identify evidence, unknowns, and verification steps.” A concrete target keeps cleanup from expanding into an unrequested redesign.
Map the change surface with repository evidence
Ask the model to inspect the target code, its callers, nearby tests, repository instructions, and relevant build configuration. Request paths and symbol names for every important claim. If it cannot access the repository, provide selected files and make the missing context explicit.
- Entry points: Which handlers, jobs, commands, or public methods reach this code?
- Dependencies: Which database calls, external services, clocks, and configuration values affect it?
- Consumers: Which callers depend on return values, exceptions, ordering, or side effects?
Require the model to distinguish observed facts from assumptions. “No callers found in the searched directories” is useful evidence; “nothing depends on this” is usually too strong.
Write the behavior contract before the design
Refactoring changes structure while preserving observable behavior. List the invariants before discussing new abstractions. For invoice calculation, these might include rounding at the same stage, retaining error codes, and preserving transaction boundaries. Include operational behavior such as logging, retries, and emitted events when consumers rely on it.
Keep bug fixes and feature changes out of this contract. If discovery reveals a defect, record it separately and decide whether it blocks the refactor. Quietly correcting it during extraction makes regressions harder to diagnose.
Plan tests that capture today’s behavior
Ask which existing tests protect each invariant and where coverage is missing. When behavior is poorly documented, plan characterization tests that record what the current implementation actually does. Review those expectations yourself: a model can accidentally encode intended behavior instead of existing behavior.
Distinguish proposed tests from executed tests. During planning, record commands to run later, required fixtures, and environment limitations. If baseline verification is permitted now, confirm that the command will not unexpectedly update snapshots, write generated artifacts, or contact production services.
Break the refactor into reviewable slices
Request a sequence in which each step has a purpose, touched files, verification, and a recovery point. For the invoice example, that could mean adding characterization tests, extracting a calculation function, switching the handler to use it, and removing dead code only after verification.
Favor the smallest structure that solves the stated problem. Ask the model to justify every new interface or dependency. Avoid mixing broad renames, formatting churn, dependency upgrades, and logic movement into one patch. Small slices make unexpected changes easier to locate and reverse.
Challenge the plan before giving editing permission
Run a separate critique pass: “Find unsupported assumptions, missed callers, behavior changes, and steps that cannot be independently verified.” A fresh session can help challenge the original framing, but agreement between models is not proof. Repository evidence and tests remain the deciding checks.
If you want to try this workflow with Claude Sonnet 5.5 in a compatible coding tool, SwiftRelay provides pay-as-you-go, per-token access. Sign up for SwiftRelay to use its small new-account gift credit for a bounded planning session. Keep credentials and sensitive repository data out of prompts unless your organization has approved their handling.
Approve an explicit handoff to implementation
Before edits begin, require a final plan containing scope, invariants, evidence, unresolved questions, ordered steps, test commands, and stop conditions. Approve that plan explicitly. If implementation uncovers a new dependency or a behavior mismatch, return to planning rather than letting the model expand the scope silently.