Modernize the system piece by piece

Name the problem first: difficult changes, maintenance cost, dependencies, or missing knowledge. Only then decide whether to improve code, replace a slice, or rewrite a larger part.

My path: from a desktop application to the cloud

We bought the source code of a desktop system, an application running on the user’s computer. We wanted to move it to the cloud and change technology from .NET to Java. We had the code, so my first thought was simple: perhaps AI could just rewrite it.

In our trials, models did not handle that well enough. I would not base a whole project on “rewrite this system” today either. That may change soon, but then we needed a path we could actually follow.

We took the classic route: an expert described behaviour, we examined source code, and rewrote the system step by step. It was long and expensive. Having code did not mean we immediately understood every rule and connection.

Today I would approach it differently. Middleware convinced me: agents first describe system logic and dependencies in .md files and JSON. They get a model they can navigate instead of reconstructing behaviour from separate code fragments every time.

For me that was a “wow” moment: agents could view the system as a whole and connect the analysed slice with the rest. We used this approach while delivering Szacun, and it worked very well for us.

More about middleware and what I call “flattening” code

My conclusion: before asking AI for a new system version, check whether it can reconstruct its behaviour, rules, and dependencies. New code alone will not show what was lost along the way.

Commissioning a rewrite? Check what you can actually take over

Before the current or new contractor begins changes, check control of code, domain, accounts, and environments. Name who on your side understands the system and can deploy and maintain it. Our own team could already develop code, but we still needed the contractor for environments; that is why I separate those capabilities.

Prepare the contractual exit plan: an existing-system handover list, dates, responsibilities, and acceptance conditions. Agree documentation rules for the new solution. Agree who maintains the working version during modernization and who takes over that duty afterwards. Rewriting code alone does not remove dependence on a contractor.

See my five software-house lessons and the list to complete

This is the same framework as for a new project, with the addition of taking over existing knowledge and maintaining continuity of operation.

Protect current behaviour

Start with investigating one area and checking gaps in system documentation. Record sample input and expected results, connections to other systems, and what must not be interrupted. Add behaviour tests that allow version comparison.

Not every old behaviour is a requirement. The person who knows the product decides what you retain, what is a defect, and what still needs explanation. An agent should not preserve a defect merely because it found it in code.

Compare three options

Based on the checked system description [sources and version], compare improving current code, replacing a slice, and rewriting it. We want to remove [specific problem]. Include domain rules, data, connections to other systems, cost, maintenance, and the team’s ongoing work. Give pros and cons, unknowns, and evidence needed for a decision. Propose the smallest stage, a way to compare behaviour, and a return to the previous version. Do not start a migration or change production.

Move one slice and compare the result

Choose a slice whose replacement addresses the named problem. Open the old and new versions on the same test data and record comparison with the task.

Resolve every difference with the person accountable for the product or rule: defect correction, agreed change, or a problem to fix. Record the decision. New code and tests can agree with each other and still fail the user’s need.

Attach the card and complete its “Modernization” section. It includes version comparison, data, switch condition, and return fields. Before changing data writes, agree what happens to reports already added in the new version. Simply running old code may not handle them. Rehearse rollback on a test-approved copy of data before switching users.

Show a demo of the old and new flows. After corrections, perform needed refactoring, tests, and independent review. Record differences and decisions instead of declaring the whole area ready after one successful trial.

Stage result: confirmed behaviour, checked data, and rollback capability appropriate to the change. Existing documentation distinguishes current from target state. Turning off the old element needs a separate decision after agreed conditions are met.