Quick Understanding of an Obsolete Legacy Project With AI

A few weeks ago, I transferred to a new project to join a colleague who was maintaining similar legacy Java applications. But with no documentation available, how do you jump on a moving train as quickly as possible without turning your first few weeks into a trial-and-error nightmare?

Fortunately, my transition happened during the biggest AI boom to date, leading to a simple decision: let Copilot analyze the application so it could describe it to us — creating documentation not just for us, but for itself as well.

Where to Start?

At the beginning, though, I had no idea where to start. Throwing prompts at Copilot in hopes it would somehow figure things out didn't sound effective — if you don't specify exactly what you want from a language model, the results are usually far from satisfying.

So, I consulted another model on the best approach for this scenario. To avoid having the result influenced by GitHub Copilot's context, I asked the free web version of Microsoft Copilot. The output was Markdown containing a list of files I would need and what they should contain.

The beauty of the Markdown format is that it can be read by both humans and machines; this gave us not only a rough idea of what was going on, but we could also read through individual points ourselves and make corrections if needed.

I took the generated file, fed it directly into GitHub Copilot within the codebase, and let it work its magic. To say the result blew me away would be an understatement.

For instance, Copilot picked up on the fact that the application historically contained two different development approaches — an old one and a new one — and was able to distinguish between them and describe both. It generated all the necessary files, such as agents.md, architecture.md, and various skills. I then handed those files over to Microsoft Copilot to validate whether they were written properly. Once confirmed, I had a solid launching pad to dive into the depths of the project.

AI-Driven Development

With the generated files in place, I decided to tackle my first tasks on the project using AI. I rephrased the task requirements using another AI before feeding them to the codebase agent.

That brought another surprise: not only did it execute the assigned task without any issues, but the visual review also looked completely fine. I submitted the work for a code review to my colleague, and he had no objections either.

The supporting Markdown files I generated played a massive role in this success, as they outlined the code style, architecture, and similar guidelines. Thanks to them, Copilot didn't need to reconstruct a huge amount of context over and over again, since most of what it needed was already described in those .md files.

This also saved on token usage, which everyone is running low on following the recent pricing changes. That said, I confirmed that the best way to develop software is a hybrid approach combining human intelligence and AI — you still have to decide what a Copilot is suitable for and what it isn't.

The Future of the Project

This experience left me with several key takeaways for future projects. Consulting multiple LLMs definitely helped — asking a free model how best to instruct the paid one saved me from burning tokens on vague or imprecise prompts.

If I ever face a project transition again, I would do it the same way: first generate supporting files, learn from the AI's outputs, and only then dive into the actual codebase.

Naturally, the Markdown files themselves need to be maintained. If breaking changes occur in the application that alter its structure or could negatively impact Copilot's understanding of the code (and its performance), those changes must be reflected in the .md files.

The easiest way is to use AI for this as well, as it can capture changes precisely and concisely. I even wrote directly in agents.md that if it finds any information helpful, it should update the auxiliary files itself. However, since we primarily do maintenance work, we didn't need to update the original .md files during my first few months on the project because we hadn't made any fundamental changes to the codebase.

Looking ahead, we don't have to limit ourselves to just maintenance. The missing documentation has been effectively replaced by our newly created Markdown files. If the client wishes, these files will allow us to build new features for the application as well.