A Safe Coding-Agent Refactor, Step by Step

A legacy module rarely has a complete specification. Its real contract is scattered across callers, tests, production behavior, and awkward edge cases. A coding agent can help untangle it, but a passing test suite alone does not prove that behavior stayed unchanged. The safest workflow gives the agent a narrow assignment, captures missing contracts, and checks each structural change before proceeding.

1. Establish a trustworthy baseline

Start from a clean working tree and create a dedicated branch. Record the runtime version, dependency lockfile, test command, and relevant environment settings. Run the module’s tests and the wider suite before editing anything. Save failures and warnings so later results have a meaningful comparison. If tests are flaky, record that explicitly rather than allowing the agent to rerun them until they pass.

2. Define what must not change

Write a short refactoring contract before asking for code. Name the target module, allowed files, and intended structural improvement. List observable behavior that must remain stable: return values, exception types, public signatures, ordering, side effects, and serialization formats. Explicitly exclude dependency upgrades, feature work, and unrelated cleanup. A useful instruction is: Preserve existing behavior, including documented quirks; propose suspected bug fixes separately.

3. Ask for an inspection report first

Have the agent inspect the module, its callers, and nearby tests without modifying files. Request a dependency map, likely compatibility risks, and a small sequence of proposed changes. Check that report yourself. Dynamic imports, reflection, plugin registration, and external consumers can make apparently private functions part of an implicit contract. If the agent cannot establish whether something is unused, uncertainty is not permission to delete it.

4. Add characterization tests before moving logic

Cover behavior that existing tests miss, especially branches the refactor will touch. For a legacy invoice formatter, that might include empty items, missing optional fields, rounding boundaries, and the exact error raised for invalid currency. Run these tests against the unchanged implementation first. Review expected outputs yourself; tests derived from the agent’s assumptions can simply certify the wrong behavior. Label odd existing behavior so nobody mistakes preservation for endorsement.

5. Make one structural change at a time

Give the agent one bounded task, such as extracting input normalization into a helper while keeping the public entry point unchanged. Require it to stop after that change and report files modified, tests executed, and unresolved concerns. Avoid combining extraction, renaming, algorithm changes, and error-handling cleanup in one patch. If you use CodeRelay Hub from Claude Code or Codex, keep the selected model and agent settings stable during this sequence to reduce troubleshooting variables.

6. Validate through progressively wider gates

Run the closest tests first for fast feedback, then expand validation before accepting the patch. Use the repository’s existing commands rather than letting the agent invent substitutes.

• Run characterization tests and the module’s existing unit tests.
• Run tests for direct callers and relevant integration paths.
• Run configured type checks, lint checks, and build steps.
• Run the full required suite in CI before merging.

A test failure is a stop signal. Ask for a diagnosis before another edit, and reject fixes that weaken assertions, skip tests, or change expected values merely to accommodate the refactor.

7. Review the diff as a behavior change

Even when the goal is structural, inspect the patch for changed defaults, exception handling, mutation, evaluation order, and resource cleanup. Verify that mocks have not hidden meaningful interactions. Where practical, compare old and new implementations on the same representative inputs, using isolated fixtures rather than replaying destructive side effects. Commit each validated increment separately so a regression can be traced and reverted without discarding unrelated work.

8. Finish with evidence, not confidence

Ask the agent for a final summary containing the structural changes, exact validation commands, results, and remaining gaps. Independently inspect the final diff and CI status. Keep behavior fixes in follow-up work, and use the normal rollout safeguards if the module affects production. The deliverable is not just cleaner code; it is a reviewable chain of small changes with explicit evidence that known contracts still hold.

Open a free CodeRelay Hub workspace to try this workflow.