A Safe Path for AI Agents in a Large Codebase

The worry I hear most from experienced engineers isn’t that AI agents are useless. It’s that they’re too capable in the wrong way: fast, confident and unaware of the ten unwritten rules that keep a large, old, tangled codebase standing. Let one loose on a critical path and it can produce a change that looks fine, passes a shallow review and breaks something three systems away.

That worry is reasonable. But the conclusion isn’t “keep agents out”. It’s that adoption needs a path, and the codebase needs a shape that makes the path safe. Most of what that takes, I’ve written about separately. This note connects the pieces.

1. Climb a ladder; don’t jump to the top

Nobody would give a new hire production access to the payments service on day one. Treat agents the same way: start where mistakes are cheap and the value is real, and widen the boundary as the team’s practices mature.

Rung	What agents do	Why it’s safe
1. Read-only	Explain unfamiliar code, search, summarise, draft review comments	Nothing changes unless a human acts
2. Non-functional work	Tests, docs, types, lint fixes, small refactors with no behaviour change	Easy to verify; mistakes are visible and cheap
3. Bounded features	Small changes inside one well-tested, well-contracted area	Contracts and tests catch what review misses
4. Critical paths	Payments, auth, customer data	Last, with stronger gates: extra reviewers, evals, staged rollouts, instant rollback

The second rung is where I’d start almost any team, and it’s where I started. On one platform we had written most of our tests by hand, so the assistant had good patterns to copy, and then let it fill the gaps under a boy scout rule: whenever we touched a service below the coverage target, it generated the missing tests, and we reviewed them. AI stayed a contained development aid, not a loop running ahead of us. The confidence that bought is what made the next rung possible (A Testing Strategy Teams Actually Adopted).

The principle: expand the boundary as the team matures, not ahead of it. A team tech radar is a good way to make that visible: which uses of AI are adopted, which are on trial, which are deliberately on hold (Staying Current: Awareness vs the Trigger to Act).

2. Make the problem space smaller

Agents struggle with large codebases for the same reason new engineers do: too much context, too many hidden couplings. So the most effective AI strategy is often an architecture change, not a tooling one.

• Bounded contexts. Split the system along domain lines, each with its own model, language and owner. A context small enough for a team to hold in their heads is small enough for an agent to work in without breaking a neighbour (Planes and Bounded Contexts).
• Contracts at the boundaries. Agreed APIs, events and schemas between contexts mean a change inside one can’t silently break another; a contract test fails first (Contract-Driven Development).
• Smaller tickets. A task broken down until it’s independent, small and testable is one an agent can do well and a reviewer can actually check (INVEST). A ready ticket is an AI-ready ticket (From Statement of Work to Done: Requirements Both Ends Can Build From).
• Strangle, don’t rewrite. Untangling a monolith piece by piece is how you get those small contexts in the first place (Strangler Fig Migration).

None of this is new. Domain-driven design and modular boundaries were good ideas before AI. Agents just raise the reward for doing them.

3. Let the pipeline enforce the rules

“Agents must not reach into another domain’s database” is a sentence in a document, and documents don’t stop anyone. Encode the important rules so the build fails when they’re broken:

• Fitness functions for architecture: module boundaries, dependency direction, forbidden imports (Architecture Fitness Functions).
• Contract tests at every boundary.
• Small pull requests and required reviews, with AI-written code held to exactly the same bar as human code.
• No new dependency without human approval.

This also covers the subtle failure mode: an agent producing something that works but quietly violates the intended design. Executable rules catch the drift humans assume isn’t there (Agents Audit What Humans Assume).

4. Small contexts are also a security boundary

The same shape that makes agents safer makes attacks smaller. If an agent, or a package it pulled in, is compromised, the damage is limited to what that context can reach:

• Least privilege per context: an agent working in one domain gets that domain’s repository, credentials and test data, not the whole estate.
• No secrets on disk where an agent runs; tokens injected at run time, short-lived.
• Restricted network access from sandboxes and builds, so nothing can phone home.
• Curated dependencies, because agents add packages freely (AI-Era Supply Chain: What to Trust When Anything Can Be Generated).

A monolith with one set of credentials is one big blast radius. Bounded contexts turn it into many small ones.

The short version

Agents do cause havoc in large codebases, when they’re dropped onto critical paths of a tangled system with nothing but a human skim-reading the diff. Give them a ladder instead: read-only, then low-risk work like tests and docs, then bounded features, and critical paths last. Shape the codebase into small, contracted domains. Let the pipeline enforce the rules. You get the speed, and the blast radius, for bugs and for attackers alike, stays small.