Legacy maintenance with Claude Code and Codex: a controlled team workflow

Coding agents can assist legacy maintenance when the task is bounded, the current behaviour is observable and the correction can be verified. The starting point is not an instruction to rewrite the application. It is a specific defect, a business rule and an environment where the team can test the result.

An older system often contains valuable rules that are poorly documented. Claude Code or Codex may help investigate the repository, but neither should decide silently which behaviours to preserve or replace.

Workflow prepared with AI assistance on 17 September 2026. The export example is pedagogical, not a description of a client incident. The cover is an AI-generated conceptual illustration.

Choose a small, observable maintenance task

Select a module with an identifiable input and output: an export, a calculation or a validation step. Write down the reported failure and the behaviour the business expects.

For this example, an export produces an incorrect line when a quantity is missing. The agreed rule is to reject the invalid record. The agent must not invent a default quantity of zero or one because that makes execution easier.

A broad request to modernise the entire codebase would mix diagnosis, architecture and business decisions. Keep that work separate from the maintenance ticket.

Step one: investigate without editing

Ask the agent to identify the entry point, relevant files and execution path. It should distinguish observed facts from hypotheses and name what remains unknown.

A useful initial instruction is to trace how quantity values reach the export, identify existing validation and propose the smallest check that can reproduce the failure. No implementation change is needed at this stage.

Verify the investigation against the repository. A file with a promising name may not participate in the failing path. If execution requires an unavailable service, record that limitation rather than inventing a confirmed cause.

The investigation can reveal missing business information. Return those questions to the responsible owner before asking for a patch.

Step two: establish the behaviour to preserve

Characterisation tests help document existing behaviour, but not every existing behaviour is desirable. Separate the valid contract from the known defect and from unresolved questions.

Include ordinary values, missing values, zero, empty input and relevant boundaries. Whether each case is valid depends on the project's actual contract; do not import an assumption from another application.

Write the failing test before the correction where practical. Its expected result should come from the agreed rule rather than merely copying the current implementation.

Step three: produce a focused correction

Ask for the smallest change that addresses the evidenced cause. Preserve the public interface and avoid unrelated formatting, dependency upgrades or broad refactoring.

Inspect error handling carefully. Catching every exception or silently skipping a record can hide the problem rather than resolve it. If the export contract requires a visible failure, the patch must preserve that requirement.

A new library is not automatically justified because it simplifies the agent's proposal. Assess whether the existing code can express the correction clearly and whether another developer can maintain it.

The diff should be small enough to connect each change to the ticket. Any additional improvement can be proposed separately.

Step four: verify the correction and its boundaries

Run the targeted regression test and the relevant module checks. Add integration or functional validation according to risk. Report the command and actual result, including checks that could not run.

For an export, inspect the produced file in a safe test destination. Unit tests alone may not cover encoding, separators, downstream expectations or error reporting across the complete workflow.

Have another person review the patch and the evidence. A confident agent summary is not a substitute for this review. The unit testing guide explains how to challenge tests that pass too easily.

Do not use a production system to discover whether a hypothetical correction works. Deployment remains a separate authorised step.

Compare tools without sharing the first solution

If evaluating Claude Code and Codex, start from the same repository commit in independent environments. Use equivalent instructions, business rules and acceptance criteria.

The second tool should not receive the first tool's completed investigation, patch or test suite unless the evaluation explicitly measures that assisted workflow. Record execution mode and setup effort.

Use the comparison guide to keep quality, control and total effort visible. Count failed attempts and manual corrections.

Keep modernisation separate from maintenance

A maintenance exercise may reveal a need to replace dependencies or redesign a module. That can justify a new project, but it does not authorise an implicit rewrite within the current ticket.

Separate the immediate correction, documented technical debt and proposed modernisation scope. This lets the business decide what risk and effort it is willing to accept.

The AI engineering service can support a broader integration or development scope when it is explicitly required.

Keep a useful delivery record

The final record should contain the ticket, starting commit, evidenced cause, test that reproduces the defect, focused patch, executed results, unresolved limitations and business decisions.

Another developer should be able to understand why the change exists without reading every prompt. Preserve the evidence in the project's normal delivery tools, with appropriate limits on sensitive logs.

Measure the cost of reaching acceptance through the ROI method, including investigation, review and unsuccessful proposals.

Frequently asked questions

Can we start if the application has no tests?

Yes, with investigation and a suitable initial check. The absence of tests does not justify accepting an unverified patch; it makes the validation plan more important.

Should the agent receive the whole repository?

Provide the context the authorised task needs while respecting access restrictions. More context is not automatically better and may include unnecessary sensitive material.

Must the application be modernised first?

Not necessarily. A bounded correction can preserve a valuable existing system. Modernisation should be justified and scoped separately.

Prepare a legacy maintenance workshop

Hunter BI can help select an authorised module, clarify the rule and define an evidence-based correction workflow. Examine client source-code security before sharing access.

Discuss a legacy maintenance pilot with Claude Code or Codex.