Migrating legacy code with AI: yes, but not as you imagine
A practical strategy for modernizing legacy code using AI agents without falling into false promises
Consider the following scenario:
You have a legacy application written in Scala, written with not-great software practices, that you need to migrate to Java, following good practices.
Three years ago, your solution would have been to go slowly, translating code bit by bit from one side to the other.
Now, at the dawn of generative AI and developer assistants, could you delegate that task to an AI agent?
Short answer: Yes.
Longer answer: Yes, but not how you’d expect.
In today’s email, I’ll tell you the strategy that has worked for me to migrate legacy code from one language to another.
This is a real scenario one of the dev teams I work with actually faced — this is real life.
First idea: let the AI do everything
Epic fail.
This was the first bright idea that came to my mind:
Why don’t we load the old project and an empty new project into the IDE, give a powerful prompt to an AI agent, and have it migrate all the code?
Unviable, at least for now.
No matter how good the prompt is, when there’s lots of code, the agent will lose things along the way; it’s simply too much context, and we know AI agents can get confused when carrying too much context.
I’ve done some tests with small scripts, 50–100 lines, to migrate from SHELL to Python, and this approach worked pretty well.
With a normal or large-sized project, as I said, it simply doesn’t work.
Second idea: divide and conquer
Epic fail too!
This was the second bright idea:
Okay, we can’t ask the agent to do everything at once, so let’s give it smaller chunks, packages, modules, and the context will be smaller.
Without full visibility, it simply can’t apply good practices; it needs to refactor very often, and it doesn’t notice; you have to tell it. It hallucinates a lot.
It simply doesn’t scale.
Third idea: abstract the business rules so another agent can understand them
Success.
This idea didn’t come from me; it came from a teammate:
Let’s ask an AI agent to analyze the Scala project and produce a document that explains things like business logic, black-box tests, functional behaviour, etc. Then use that document with another AI agent to gradually help us implement the same behaviour in Java.
Why did this work?
AI agents get along well with instructions in Markdown. They’re also good at translating code to text and vice versa, and if we ask them to adapt the output so another agent can process it, even better.
This lets the agent implement in blocks while having the complete vision in text, making the process more efficient.
I won’t lie: it takes time, and you have to work with the agent step by step, but so far it’s working for us.
Tips
To finish today’s email, here are some tips based on what we learned with this exercise.
Ask the agent to start by implementing the tests. This is the TDD approach, and it will help you, the human, trust that things are being done correctly.
Ask for the plan before implementation. Review its plan, and ask for changes.
Request changes incrementally. We’ve seen in previous editions that Spec-Driven Development can work if it happens in small batches and you don’t ask for all functionality at once.
Review every change. Seriously, review them, because sometimes the agent slips and doesn’t do things the way you want or it alters a test to make its job easier.
To get the agent to follow good practices, using a AGENTS.md file has worked very well for me. You can read more about AGENTS.md here.
I hope this real-life learning is useful to you.
I’d love to know if you’ve tried something similar and if you’ve encountered any limitations when programming with AI agents. Please reply to this email or leave a comment.
Did you enjoy today’s edition? Share it with your friends 👇🏻