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

A trustworthy test suite, or an honest statement that one does not exist. Tests are the only reliable standard an agent can check its own work against without a human involved, so if the suite has few tests or wrong ones, 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 break easily and which patterns exist for a real reason rather than by accident.

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

Yes, by name, with the reason to be careful spelled out. A human engineer learns warnings like this through informal talks with colleagues 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 found time to update 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 give an agent 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 kind of failure 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 what matters is what gets into the agent's context window for that specific task, and your own knowledge sits outside it. 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 completely needs the brief restated for the agent's benefit.

How long should a legacy codebase brief be?

Long enough to cover the tests you can trust, the dangerous spots, and the conventions, and no longer than that. A brief that hides 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 unrelated text the agent has to consider alongside the useful information, 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 is released.

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, given the same code with a normal task prompt, would have read all three systems as equally valid and started extending whichever one it found 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 planning these takeovers: an agent needs the same three things a new hire needs, tests it can trust, known dangerous spots, and current conventions, but it needs every one of them stated in writing, because it has none of the instinct a person brings to the job.

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 problems caused 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 such problems. Ask it to add a feature near that strange function, and it is as likely to copy the pattern as to question it. A prompt that says "be careful" will not fix this, because the cause is the actual difference in how the two of them process a codebase: a person judges what they read with suspicion learned elsewhere, an agent judges what it reads only by the instructions you gave it for this task.

So the brief for an agent has to supply 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 easy to break either way.

Tests are the only reliable standard 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 involved.

This is why an existing test suite matters more for an agent than it does for a person. A new hire can rely on judgment and a Slack message when there are few tests. An agent relies 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 was released.

If the suite is solid, say so and tell the agent to use it as the standard to satisfy. If it is not, do not let the agent find that out by trusting a passing run that means less than it seems to. 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.

Name the dangerous spots before the agent finds them

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 slowly, in an informal talk with a colleague 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 dangerous spot down, the agent has no way to know it is working in one.

In practice this means listing, by name, the two or three places in the system where the straightforward change is the wrong one. Payment retry code that looks redundant but exists because of a specific kind of failure. 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. Give it a file that uses an outdated error-handling style because the team never found time to update 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 turns the correction into judgment they keep. An agent keeps nothing 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 stays in use for years after it stopped being useful.

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 time on the project. Whatever does not change a decision it will make on the current task takes up space in its context window for no benefit, and unrelated detail in that context window is not neutral: the agent weighs it against the parts that actually matter, and it can get treated as instruction when it was only meant as background.

This is the opposite mistake from under-briefing, and it is just as common. A brief that hides 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 history of how the system started. 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 difference appears in measured results too. 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 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 use when the brief leaves things out.

This is also why an eval suite matters for every change the agent makes. 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 dangerous spots took them the longest to find themselves. A person brings suspicion to strange code because bad code has caused them problems 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.

How to brief an agent on a legacy codebase