What is the single most important thing to give an AI agent before it touches a legacy codebase?

A trustworthy test suite, or an honest statement that one does not exist. Tests are the only ground truth an agent can check its own work against without a human in the loop, so if the suite is thin or wrong, the agent needs to be told that directly instead of finding out by breaking something.

How is briefing an agent different from onboarding a new human engineer?

A new hire brings judgment by default: they read a strange piece of code and assume there might be a reason for it, even before anyone explains. An agent does not bring that suspicion on its own, so the brief has to state explicitly what a human would infer, including which files are fragile and which patterns exist for a real reason rather than by accident.

Should you tell an agent about known landmines in the code, like a function nobody fully understands?

Yes, by name, with the reason to be careful spelled out. A human engineer picks up warnings like this through hallway conversation and old commit messages over weeks; an agent only knows what is in its context window for that session, so the warning has to be written down and included every time.

Can an agent infer a team's coding conventions just by reading the existing code?

Partly, and that is exactly the risk. An agent will match the patterns it sees, including bad ones, so if three files use an old error-handling style because nobody got around to updating them, the agent will likely extend that style into new code unless the brief says which patterns are current and which are just old.

Does an agent need the same historical context a new hire gets, like why a system was originally built a certain way?

Only the parts that affect a decision it will make today. A new hire benefits from hearing the long version because it builds their judgment over months; an agent has no memory between sessions unless you re-supply it, so the brief should include only the history that changes what the agent should do right now, not the full story.

What happens if you point an agent at a legacy codebase with no brief at all?

It will read the code and act on what it finds, treating every existing pattern as equally intentional. This is the same failure mode as a new hire copying a bad pattern because it is what they saw first, except the agent has no instinct to ask "should I be doing this" before it does.

Is it worth writing a brief for a codebase you already know well?

Yes, because a brief is not really about what you know, it is about what makes it into the agent's context window for that specific task. Knowledge in your head does nothing for the agent unless you write it down and hand it over each time, so even a codebase you know by heart needs the brief restated for the agent's benefit.

How long should a legacy codebase brief be?

Long enough to cover ground truth, landmines, and conventions, and no longer than that. A brief that buries three critical warnings inside ten pages of general background is worse than a short one that states the three warnings plainly, because an agent weighs everything in its context window rather than skimming for what matters the way a person would.

Does giving an agent more context always make it more reliable?

No. Extra context that is not relevant to the current task adds noise the agent has to weigh alongside the real signal, and irrelevant detail can get treated as instruction. The goal is a brief scoped to what changes the agent's decisions on this task, not a complete history of the codebase.

Who is responsible for checking an agent's work in a legacy codebase, the brief writer or the agent itself?

The team, not the brief and not the agent alone. A brief reduces the chance of a bad decision, but the check that catches what the brief missed has to run against the actual behavior of the system, written from the specification, the same way any other change to the codebase is verified before it ships.

How to brief an agent on a legacy codebase: Reveneau

We were handed a codebase last year with no working test suite and three separate authentication systems, each written by a different phase of the same team, only one of which was actually in use. A new engineer on that project would have spent a week in meetings, reading old pull requests, and asking "wait, is this one still used?" before touching a single file. An AI agent, pointed at the same code with a normal task prompt, would have read all three systems as equally valid and started extending whichever one it landed on first.

That is the real difference between briefing a person and briefing an agent on a system neither of them wrote. Here is what we have learned scoping these handoffs: an agent needs the same three things a new hire needs, ground truth, known landmines, and current conventions, but it needs every one of them stated in writing, because it has none of the instinct a person carries in by default.

A new hire brings suspicion. An agent does not.

A person who has worked on other codebases reads a strange function and has a reflex: "that's probably a workaround for something, let me ask before I touch it." That reflex comes from years of being burned by code that looked simple and was not.

An agent has no such reflex unless you give it one. It reads code and treats every pattern it finds as equally intentional, because it has no personal history of being burned. Ask it to add a feature near that strange function, and it is as likely to copy the pattern as to question it. This is not a flaw you can prompt your way around with "be careful." It is the actual difference in how the two of them process a codebase: a person filters what they read through suspicion earned elsewhere, an agent filters what it reads through the instructions you gave it for this task and nothing else.

So the brief for an agent has to carry the suspicion the agent does not bring on its own. Name the workaround. Say why it exists, if you know, or say plainly that nobody currently knows and to treat it as fragile either way.

Tests are the only ground truth an agent can check itself against

A new hire, unsure whether a change is correct, can ask a teammate. An agent working on its own has no equivalent unless the codebase gives it one, and the only thing that plays that role reliably is a test suite it can run and read the result of without a human in the loop.

This is why an existing test suite matters more for an agent than it does for a person. A new hire can lean on judgment and a Slack message when the tests are thin. An agent leans on nothing but what it can execute and observe, so weak coverage in a codebase removes the one check that would have caught a wrong assumption before it shipped.

If the suite is solid, say so and point the agent at it as the standard to satisfy. If it is not, do not let the agent find that out by trusting a green run that does not mean what it looks like it means. Say directly which parts of the system are actually covered and which are not, and where coverage is missing, plan for a slower, more supervised first pass rather than assuming the tests will catch what they were never written to catch.

Landmines need to be named, not left to be discovered

Every legacy system has two or three places where the obvious fix is wrong, and everyone on the original team knows it without anyone having written it down. A new hire eventually learns these the slow way, in a hallway conversation or a "don't touch that, long story" comment on a pull request months in.

An agent gets exactly one chance to learn it: whatever is in its context for the task at hand. If nobody wrote the landmine down, the agent has no way to know it is standing on one.

In practice this means listing, by name, the two or three places in the system where the straightforward change is the wrong one. A payment retry path that looks redundant but exists because of a specific failure mode. A database migration that has to run in a particular order for reasons that are not visible in the code itself. State it plainly enough that the agent would flag the area as sensitive even without fully understanding why, the same way you would want a cautious new hire to pause and ask first.

Conventions in the code are not automatically the right conventions

An agent is good at pattern matching, which is exactly the problem here. Point it at a file that uses an outdated error-handling style because the team never got around to updating it, and the agent will likely extend that same outdated style into new code, because the pattern is what it sees, not what the team actually wants going forward.

A new hire has the same risk in reverse: they often copy what they see first, assuming it is the house style, and have to be corrected later. The difference is that a person eventually absorbs the correction into judgment they carry forward. An agent does not carry anything forward between sessions unless the brief restates it every time.

So the brief needs a short, explicit list: which patterns in this codebase are current and intentional, and which are leftover and should not be copied. If half the codebase uses one approach to error handling and the newer half uses another, say which one is the standard now. Leaving the agent to infer this from majority pattern in the files it happens to read is how an old convention outlives its usefulness by several more years.

Skip the history that does not change today's decision

A new hire benefits from the long version of why a system was built a certain way, because that story builds judgment they will use for months or years on the project. An agent has no such runway. Whatever does not change a decision it will make on the current task is weight in its context window for no return, and unrelated detail in that context window is not neutral: it competes with the parts that actually matter, and it can get treated as instruction when it was only meant as color.

This is the opposite mistake from under-briefing, and it is just as common. A brief that buries three real warnings inside a long history of the system's original design is worse than a short brief that states the three warnings plainly, because a person skims for what is relevant and an agent does not skim the same way. Cut the origin story. Keep the three things that change what happens if the agent gets them wrong.

Why the brief matters more than the model

Researchers studying how developers work have found that a large share of a developer's time on any existing system goes to understanding it before changing it: one study of program comprehension put the figure at 58 percent of a developer's time, more than they spend writing the change itself, according to Code Compass, a 2024 study on navigating unfamiliar codebases. For an agent, almost none of that understanding happens on its own initiative. It happens in the brief you hand over before the first prompt, or it does not happen at all.

That gap shows up in results, not just in theory. METR, an AI research nonprofit, ran a randomized controlled trial in 2025 with experienced open-source developers working in codebases they already knew well, and measured them 19 percent slower on real tasks when using AI tools, even though the same developers estimated afterward that the tools had made them 20 percent faster. The study's own authors were careful to note the result does not generalize to every setting, and one context they flagged as plausibly different is exactly this one: an unfamiliar codebase, where an agent's speed at reading code can be a real advantage rather than a source of false confidence. The lesson we take from it is not that agents fail on legacy systems. It is that the productivity an agent delivers on unfamiliar code depends entirely on what it is told before it starts, because unlike an experienced developer working from memory, an agent has no memory of the codebase to fall back on when the brief is thin.

This is also why an eval suite matters once the agent starts making changes, not just once. A brief reduces the chance the agent makes a bad decision. It does not replace the check that catches the decision the brief did not anticipate, which is what a real evaluation suite, written from the specification rather than from what the agent happened to produce, is for.

Thanks to the engineers on the teams whose systems we have scoped this way, and who were candid with us about which landmines took them the longest to find themselves. A person brings suspicion to strange code because they have been burned before. An agent only brings whatever suspicion you hand it in the brief, so hand it all of it.

Sources

Code Compass: A Study on the Challenges of Navigating Unfamiliar Codebases: estimates that developers spend 58 percent of their time on program comprehension activities when working in existing code.
METR, Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity: a randomized controlled trial finding experienced developers were 19 percent slower on real tasks in familiar codebases when using AI tools, despite estimating they were 20 percent faster, with the authors noting the result may not generalize to unfamiliar-codebase settings.