Mel – the agentic terminal
The agentic team for coding.
How to use an AI coding agent on a large or legacy codebase
November 16, 2026 · 6 min read

- An agent sees a slice of your code at a time. Tell it where to look.
- Write a one-page map: the main folders, how to build, how to test, what not to touch.
- Get one test command working before you ask for any change.
- Read every diff. Old code hides rules nobody wrote down.
Yes, an AI coding agent can work on a large or legacy codebase, but not by reading all of it at once. Give it a short map of the code, a command that proves a change works, and one small task at a time, and it becomes useful on code that is years old. This guide shows how to set that up in a week, what to hand the agent first, and where it still needs you. It works with any agent. We use Mel – the agentic terminal (openmel.dev), the agentic team for coding, in the examples.
Can an AI coding agent understand a large codebase?
Part of it at a time, which is how people work too.
An agent does not hold your whole repository in its head. It searches, opens files and reads the ones that look relevant to the task. On a small project that search finds the right files quickly. On a project with thousands of files and ten years of history, it can land on the wrong copy, a dead module, or a pattern your team dropped years ago.
So the question is not whether the agent is smart enough. It is whether it can find the right place to start and check that its change works. Both are things you can give it.
What should you give the agent before the first task?
A map. One page, kept in the repository, written for a newcomer. It saves the agent, and every new hire, a search on every task.
Put five things in it:
- What the main folders are for. One line each. "
billing/is the old invoice code, still live.payments/is the new one." - How to build and run it. The exact commands, in order.
- How to test it. The command for the whole suite and the command for one part.
- The rules that are not in the code. "Never change a migration that has shipped." "Dates are stored in UTC."
- What not to touch. Generated files, vendored code, anything another team owns.
You can ask the agent to draft the map from the code, then correct it. That is faster than writing from nothing, and it shows you what the agent gets wrong before it changes anything.
Why does the test command matter so much?
Because it is how the agent checks its own work.
Without a test it can run, an agent can only guess whether a change worked. With one, it can make the change, run the check, see the failure and try again before you ever look at it. On legacy code this matters even more, because a change in one place often breaks something far away.
If your old project has no working tests, start there: ask the agent to get the suite running, or to write a few tests around the part you plan to change. It is low risk, and it teaches the agent how the code behaves.
What should the first tasks be?
Go from reading to writing, in steps you can check.
| Week one | Task for the agent | What you check |
|---|---|---|
| Day 1 | Explain one module: what it does, what calls it, what it calls | Is the explanation right? Correct the map where it is not |
| Day 2 | Get the test suite running and report what fails | Do the failures match what the team already knows? |
| Day 3 | Add tests around one function you plan to change | Do the tests describe how the code works today? |
| Day 4 | One small fix inside that function, with the tests passing | Read the whole diff. Did it stay inside the function? |
| Day 5 | One change that touches two or three files | Check the list of changed files first, then the diff |
By the end of the week you know which tasks the agent handles well in your code, and you have a map and tests your team keeps.
How do you stop the agent from changing the wrong files?
Three habits do most of the work.
- Name the starting point. "Start in
billing/invoice.py" stops the agent from editing the copy inlegacy/that nobody uses. - Say what is off limits in the task and in the map.
- Look at the changed-file list before the diff. A file you did not expect is the fastest warning sign.
Approvals help while you are still learning how the agent behaves on your code. In Mel, configurable approvals keep you in control of commands and edits, so you can have the agent ask before it runs a command or changes a file, and loosen that once you trust it on a kind of task.
Which model should you use on old code?
It depends on the task, so it helps not to be stuck with one.
Explaining a module and writing tests for it can go to a different model than a tricky change across several files. Mel works with Claude, GPT, Gemini, DeepSeek and Qwen, US and Chinese models in one tool, with a key for each or on a paid plan. Try the same small task on two models and keep the one whose diff you would rather read.
Where does the agent still need you?
In the places old code keeps its secrets.
An agent can read what the code does. It cannot know why a strange line is there unless someone wrote it down. That if that looks useless may protect one large customer. The slow loop may be slow on purpose. When the agent wants to delete or "simplify" something odd, treat it as a question for the team, not a cleanup. Add the answer to the map, and the next task starts smarter.
Where does Mel fit?
Mel – the agentic terminal is a multi-agent, multi-model AI terminal and agentic coding desktop app for Mac, Windows, Linux and VS Code. It plans, builds, tests and ships your work with you in control, and it is building the first superintelligent terminal. A team of agents works on files, commands, code and diff review, and you choose the model for each task.
Mel is free with your own API key. Pro is $20 a month and Max is $200 a month. For teams working on one big codebase, Mel Business has shared credits and one invoice, at $50 a seat with 2 seats minimum.
To try the first-week plan on your own repository, download Mel and start with Day 1: ask it to explain one module. If you want to walk through it with your team, write to hello@openmel.dev and we will set up a short demo.
Frequently asked questions
Can an AI coding agent read my whole repository? Not all at once. It searches and reads the files that look relevant to the task. A short map and a named starting point help it find the right ones.
Is it safe to let an agent change legacy code? It is as safe as your checks. Get one test command working first, keep tasks small, and read every diff. Configurable approvals can have the agent ask before each command and edit.
What is the best first task on an old codebase? Ask the agent to explain one module and correct what it gets wrong. Then get the tests running. Both teach you how the agent sees your code before it changes anything.
What if the codebase has no tests? Make writing a few tests the first real task, around the code you plan to change. Without a check it can run, the agent can only guess whether its change worked.

Lalla is a hands-on tech founder, agentic infrastructure architect and the vision behind Mel.
Follow on LinkedIn