Refactor legacy code with AI: preserve behavior while changing structure

A worked example: where the task becomes difficult

A fictional invoicing tool has a long function mixing discounts, tax presentation, file generation and email delivery. The owner wants maintainable code without changing invoice amounts. Begin with controlled invoices covering ordinary, discounted and zero-line-item cases. Separate pure calculations from side effects. Do not let the agent infer accounting policy from variable names or replace an approved rounding rule with its preferred convention.

Decisions to make before implementation

Define observable compatibility: calculated totals, output fields, file names, error outcomes and when delivery occurs. Use characterization checks where existing behavior is the contract, while identifying suspected bugs separately. Move calculations behind a stable interface before changing callers. Keep database migrations and dependency upgrades outside the refactor unless a documented necessity makes them part of the work.

A practical sequence for the work

Use the sequence below as a task boundary, not as a claim that the example has been executed. Work with approved inputs and the project’s actual architecture. If a required integration or permission is unavailable, keep that stage visibly incomplete rather than generating a plausible substitute result.

• Create controlled examples of current successful and failed invoice generation.
• Extract a pure calculation boundary while retaining approved rounding behavior.
• Move file and delivery orchestration separately without changing their public contract.
• Compare outputs and side effects before and after each structural step.

A detailed brief you can adapt for your agent

Replace the illustrative context with your approved facts and controlled inputs. Keep the stated boundaries when adapting the brief. The expected deliverable matters more than a particular tool name: ask for an explanation grounded in the inspected material and evidence for the requested outcome.

Refactor invoice generation into calculation and orchestration boundaries without changing approved outputs. Use the supplied controlled invoice cases. Keep tax and rounding rules unchanged and isolate delivery through a fake adapter for tests. Report suspected business-rule bugs separately. Do not upgrade dependencies or migrate stored records as part of this structural task.

Failure modes that an attractive preview can hide

Legacy behavior can be wrong, but silently correcting it during a refactor makes comparisons ambiguous. Record the suspected defect as a product decision. Also watch for ordering changes: generating an invoice twice or sending it before persistence can cause real operational damage. Use fake delivery adapters during testing and explicitly preserve idempotent behavior where the workflow needs it.

Technical references: GitHub: getting useful results from coding tasks

Acceptance checks and the evidence to retain

Keep before/after output comparisons, the new responsibility map and any intentionally unchanged defects. Explain which checks establish compatibility and which cases remain unexamined.

Specific answers

Common questions