AI Assistant for Coding in Legacy Monorepos

A legacy monorepo isn't just a big codebase. Treating a legacy monorepo like a bigger version of a normal repo will make the agent setup that worked fine on a smaller project fail in ways you can actually predict ahead of time.

Start with the dependency graph. An agent trying to figure out what a change will break is only as good as the map it's working from, and in a legacy system, that map has holes in it.

Then there's sheer size. No agent session holds all of that in its context window at once, not without someone deciding in advance how to split it up and feed it in.

CI adds another layer. Agents don't work that way. They can generate pull requests all day long, and a pipeline tuned for human pacing starts to buckle under that volume.

Ownership makes it worse. An agent can walk straight across one of those lines without knowing it crossed anything, because the access rule lives in a config file, not in the code it's reading.

And then there's just the accumulated mess: a bit of jQuery next to a modern frontend framework, three different ways of calling the database depending on which decade the code was written in, no single "right" pattern an agent could learn from and apply everywhere else. Keep them in mind, because the rest of this piece is about addressing each one directly.

Monorepos are gaining ground as the preferred structure for agent-driven work, and that context shapes everything that follows. A repo boundary acts like a wall for an agent. Putting the frontend in one repo and the backend in another means an agent working on the frontend cannot see the backend code unless someone manually hands it over. It ends up guessing at how the two sides are supposed to connect, with no way to check its guess against the actual implementation.

A monorepo removes that wall. The mess inside that view is the actual problem this piece is about.

Context boundaries and agent output degradation in a legacy monorepo

Agents aren't bad at legacy code on some fundamental level. They get worse in a specific, predictable way: when they can't see enough of the dependency graph to reason about a change correctly. In a legacy monorepo, that graph is often too large for any single agent session to hold, and that's the root of most of the bad output people blame on "the AI just isn't good enough."

A monorepo makes a certain kind of task genuinely easier. An agent can follow a data type starting at the database schema, through the API layer, all the way into a frontend component, inside one session, because everything it needs sits in the same repository. That's a real, repeatable advantage over a split-repo setup where the agent would just have to guess at the connection.

But scale erases that advantage fast in a legacy system. No context window available today holds that much at once, not without someone deliberately splitting the content or retrieving only the relevant pieces.

This plays out in ordinary, everyday ways. An agent working on one corner of the repo can write code that calls into an interface without ever seeing the function it's actually calling. That's not a hypothetical edge case. It happens constantly in large repos, and it's one of the most common sources of agent-written code that looks fine and breaks in production.

Spectro Cloud's experience points to one way around this. Handing an agent the whole repo and hoping it figures out what to focus on is a different thing entirely, and it tends to produce worse results, not better ones.

Three practical moves address this without anyone having to restructure the repository itself. First, scope each session by defining the subdirectory or cluster of services an agent should work in for a given task. Second, surface the real dependency graph: pull it from actual build tooling output rather than letting the agent infer it from reading code, since inference is where mistakes creep in. Third, lay down a hierarchy of instruction files throughout the repo, so an agent working three folders deep doesn't have to guess at local conventions or burn its context budget just exploring before it writes a single line.

That third piece, instruction files placed deliberately throughout a repo, deserves its own full treatment, and it gets one later in this piece. For now, the point to hold onto is that context architecture is a decision someone makes on purpose. It doesn't happen by default just because the agent has repo access.

The cross-cutting change advantage, and the coordination problem it creates

Flipping the lens from reading code to writing it brings the monorepo's biggest payoff for agents into view: atomic cross-cutting changes. For legacy codebases specifically, this is where the productivity gains get dramatic, as long as the coordination around it holds up.

Cross-cutting changes matter even more in a legacy system than in a younger one, for a simple reason: years of accumulated shared libraries, internal APIs, and shared data models mean a single field rename can ripple through far more places than it would in a codebase that's only been around for a year or two.

In a multi-repo setup, that same change turns into a coordination exercise: separate pull requests across repos, version bumps, decisions about release order, compatibility windows while some services have updated and others haven't. AI agents currently have no standardized way to treat a change across multiple repositories as one single transaction, so this kind of cross-repo work is exactly where agent-driven change tends to fall apart.

A monorepo sidesteps the whole problem. An agent can update the source, touch every call site, adjust the relevant tests, and ship it all as one commit. No partial state anywhere in the system.

Spectro Cloud ran into a concrete version of this benefit. Because backend and UI code lived in the same repository, an automated code review tool caught an RBAC mistake: a UI change that read Kubernetes secrets without going through the correct service account. That kind of problem often slips through when backend and frontend code live in separate repos reviewed by separate teams, each only looking at their own slice of the change.

None of this means parallel agent work in a monorepo is simple. Then merge time arrives, and A's refactor doesn't match the way B calls into it, and C built its frontend code against a shape of the endpoint that B never actually shipped.

It's tempting to blame the monorepo itself when this happens, or to blame whatever agent tool was in use. That's a misdiagnosis. The coordination failure happens earlier, at the point where the shared interface between A, B, and C should have been nailed down before any of them started writing code. The repo didn't cause the conflict. Skipping that decision did.

The fix lives in process, not in repository strategy. Settle the shape of a shared interface before parallel agents start implementing against it, the same way a team of human engineers would agree on an API contract before splitting up the work. Agents don't remove the need for that conversation. They just make it more obvious, and faster, when the conversation never happened.

Slow CI and lost agent-driven productivity gains

Context problems and coordination problems are solvable with the right setup. Context and coordination problems aren't the only constraint: a third one, which has nothing to do with how smart the agent is, produces its own ceiling on productivity, and that is the CI pipeline. Agentic workflows push a much higher volume of code and pull requests toward CI than human developers ever generated on their own, and in a legacy monorepo, the pipeline built for a human pace becomes the ceiling on how much of that productivity the business ever actually captures.

The mechanics are straightforward. If that code then sits in a build queue for hours waiting its turn, the time saved didn't disappear, it just moved somewhere else in the system, and the business never sees it as a gain.

This isn't a minor wrinkle. Boris Cherny, creator of Claude Code, has described handling around 259 pull requests a month, something like eight or nine a day, against a typical pace of around twelve a month for a single developer. It's a different order of magnitude entirely, and most CI setups were never built to absorb it.

Most legacy CI configurations run a full-suite build on every single pull request, because nobody ever made the dependency graph explicit enough to support a targeted build. That's not a nice-to-have fix for later. Resolving it is a precondition for agentic workflows to deliver throughput gains that actually hold up over time, not an optional tuning step.

Failed agent-generated pull requests make all of this worse. Agents just make that weakness visible a lot faster.

Configuring AGENTS.md hierarchies to give agents stable, scoped instruction inside a large repository

Once context and CI are accounted for, the next lever is instruction itself: how an agent knows what's expected of it in a given corner of the repo. AGENTS.md has become the common format for this. The file gives an agent project-specific instructions and context, and the real value in a legacy monorepo comes from using more than one of them, arranged in a hierarchy, rather than a single file sitting at the top of the repo trying to cover everything.

The nearest AGENTS.md file in the directory tree takes priority over anything further up. A file in a subdirectory can override whatever the root file says, so local conventions win out over general ones. Without this kind of layered instruction, agents either miss local conventions entirely, or they spend so much of their context budget exploring the codebase to figure things out that they have less left over for the actual task.

A good AGENTS.md file for a legacy monorepo tends to share a few traits. The file should also spell out ownership and scope: which team owns this part of the repo, which directories the instructions apply to, and what the agent should leave alone or flag for a human.

There's a limit to what any of this can guarantee. A file telling an agent not to touch a sensitive directory is a helpful guardrail. It is not a substitute for actually locking that directory down.

Matching model choice to the specific demands of legacy monorepo work

Even with context architecture and instruction files in place, one more lever gets underused across most teams: which model actually runs each task. No single model wins across every kind of work that comes up in a legacy monorepo, and treating model choice as something decided once, during procurement, rather than per task, leaves real capability and real budget on the table.

Break the work down by task and the differences get obvious. Planning a cross-cutting refactor across a deep, tangled dependency graph calls for strong reasoning and a model that handles large context well, since the planning stage is where mistakes are cheapest to catch and most expensive to miss. Long-running agentic work, like running CI, chasing down build failures, and handling deployment, stretches over a long autonomous session, where reliability over time matters more than peak reasoning on any single step.

A pattern falls out of all this pretty naturally: save the frontier-level model for complex reasoning and planning, and drop down to a cheaper, faster model for high-volume, repetitive work. At the scale agentic workflows run, that split keeps the AI budget reasonable, since the volume of indexing and autocomplete calls alone can dwarf the volume of actual planning calls.

That makes flexibility in model choice a structural requirement for serious legacy monorepo work, not a feature to check off a list. Platforms built to let teams choose or route between models, rather than ones built around a single provider, fit legacy monorepo work better for exactly this reason: the work itself isn't one task, it's several very different ones stacked on top of each other.

Structuring an agent rollout in a legacy monorepo for measurable, stable productivity gains

Teams that get lasting productivity gains out of agents in legacy monorepos are the ones that treat the rollout itself as a discipline, with measurement, phased scope, and governance built in from day one.

Sequencing drives most of the difference. Fixing the constraints this piece has walked through, context, coordination, CI, instruction, model routing, before scaling up agent autonomy puts problems in front of a small team on a small slice of the codebase, rather than in front of the whole engineering org at once.

A structured rollout tends to move through four phases. The fourth is scaling with a feedback loop, expanding scope only once the measurement framework shows quality holding steady or improving, not just speed going up.

The ceiling on what agents can deliver in a legacy monorepo is set by how ready the surrounding infrastructure and process are to absorb what the agent produces, not by how capable the model is. Teams that build that readiness first tend to see their gains compound over time. Teams that skip it run into the same bottlenecks again at every stage they try to scale.