Refactoring and legacy modernization 🔧

Legacy code refactoring is the use case where the agent is most useful and most dangerous at the same time. Useful because it can analyze hundreds of lines in seconds and propose migration patterns. Dangerous because refactoring without tests is a bug with a different name. The golden rule: safety net first, scissors second.

Refactoring without tests is like repairing a bridge while someone is driving on it.

When to use the agent for this case 🎯

• Legacy module modernization — migrating from an obsolete pattern to a modern one.
• Interface extraction — defining clear contracts from monolithic code.
• Complexity reduction — breaking giant functions into small, testable units.
• Incremental migration — strangler fig: wrapping the legacy with new layers, one piece at a time.

When NOT to use the agent ⛔

• There are no regression tests — without a safety net, every modification is a gamble. Add tests first (see testing and TDD), then refactor.
• The legacy is critical for production — if a bug can cause financial losses, refactoring must be planned with robust integration tests.
• You do not understand the observable behavior — if you do not know what the legacy code does, you cannot verify that the refactoring preserves behavior.

Opening prompt 📝

“Refactor [module] preserving behavior. Safety net: [tests to pass]. Constraints: do not modify [public APIs / external behavior]. Plan for incremental sub-tasks.”

Concrete example:

“Refactor legacy/auth.go preserving observable behavior. Safety net: all tests in auth_test.go must pass. Constraints: do not modify the HTTP API contract, do not change JWT token format. Plan: extract dependencies first, then introduce interfaces, finally replace implementation.”

Context setup 🔧

1. Identify existing tests — they are your safety net. If there are none, create a minimal regression test suite first.
2. Document observable behavior — what does the module do? What inputs, what outputs? What are the edge cases?
3. Define constraints — what must NOT change? Public APIs, data formats, external behavior.

Workflow 💡

1. Plan by sub-task: each sub-task must be individually verifiable. One sub-task = one issue = one acceptance criterion.
2. Extend test coverage before modifying code. The more tests you have, the less risk you take.
3. Execute in micro-increments: after each modification, run the test suite. If something fails, stop and analyze.
4. Use plan mode for every sub-task that crosses multiple modules. Context must be focused.
5. Consider delegating to sub-agents for independent tasks — it reduces duration and context consumption of the main session.

The strangler fig pattern is your ally: do not rewrite everything at once. Wrap the legacy with new layers, one piece at a time, until the old one can be removed.

Characterization testing: the real safety net 🧪

Before refactoring anything, you must lock down the current behavior — bugs included. Characterization tests (or golden master tests) do not document how the code should work, but how it works now, bugs and all.

The generation cycle operates in 3 phases:

1. Scaffolding: the agent creates tests with placeholder assertions (e.g., assert result == None).
2. Execution: the test fails, revealing the legacy code’s actual output.
3. Capture: the agent captures the actual output and converts it into the immutable baseline.

A test that captures the current behavior — bugs and all — is more valuable than a test that describes ideal behavior. The first tells you when something changes. The second tells you nothing.

To verify behavioral equivalence post-refactoring, use a dual-run harness: legacy and refactored code executed in parallel against the same characterization suite. Equivalence is proved only when output, state mutations, and emitted events exactly match the golden masters.

Database schema evolution 🗄️

Database migrations are the most critical failure point. The Expand and Contract pattern operates in 4 sequential phases:

The rule is: never combine an application change with a schema migration in the same deploy. Each phase must be independently deployable and verifiable.

Anti-patterns in agentic refactoring 🚫

Task decomposition and agent-sized units 🧩

Every refactoring task must be an atomic unit with an explicit contract:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

## Refactor Target: [module]

**Permitted Edits**: src/payments/processor.py, src/payments/adapters.py
**Read-Only**: src/orders/models.py, tests/fixtures/

**Directives**:
1. Extract inline API calls into adapters.py
2. Implement abstract PaymentGateway interface
3. Preserve all existing error handlers

**Verification Gate**:
- Target: pytest tests/unit/test_payments.py --cov=src/payments
- Floor: 100% pass rate, 92% branch coverage
- Lint: zero violations

Isolated environments (like OpenHands sandboxes) execute tasks in containers, preventing out-of-scope modifications. For large-scale refactoring, an Architect Agent analyzes dependency graphs and assigns independent modules to Worker Agents in separate sandboxes.

LSTs vs long-context LLMs 🔬

For precise code transformation, enterprise platforms combine agentic reasoning with Lossless Semantic Trees (LSTs). LSTs represent code at full compiler fidelity, retaining type bindings, formatting, and transitive dependency graphs — without requiring compilation during iterations.

Long-context LLMs (1M+ tokens) are useful for high-level architectural mapping, but suffer from retrieval degradation on large prompts and lack compiler-level precision for variable scoping and type attribution.

Acceptance criteria ✅

• Regression suite green at every increment.
• No change in observable behavior.
• No unplanned public API changes.
• Each sub-task independently verifiable.

Further reading 📚

• Testing and TDD — the fundamental safety net for refactoring.
• Adding features — the complementary use case.
• Surviving sessions — how to handle errors and loops during refactoring.