Agentic AI in brownfield engineering

How engineering teams can scale delivery without breaking what already works

Photo by Compagnons on Unsplash

Where agentic AI works out of the box and where it doesn’t

Agentic AI works well in greenfield development, where there is nothing to contradict.

It also works well in **legacy migrations**, because the old system becomes the specification: the agent can read the existing code, infer the intended behavior, and help rebuild it on a new stack.

The harder case for agentic AI is in brownfield engineering. Brownfield engineering lives in years of decisions, exceptions, corrections, and tradeoffs, and in the judgment of the engineers who built and maintained the system. With brownfield, an application that already runs on a modern stack — but its real specification was never fully captured in the code.

AI cannot see a codebase’s history unless you teach it.

• Greenfield (blank slate to fill) → Agentic AI works out of the box
• Legacy migration (old code is the spec) → Agentic AI works out of the box
• Brownfield in a modern stack (conventions live in people’s heads) → Agentic AI struggles until you teach it

You have to make the system legible to agentic AI.

Most of that work comes down to writing down what the team has been carrying in its head for years.

What AI doesn’t know about your system

Every mature platform carries knowledge that was never formally written down. It tends to fall into four categories, roughly in order of how hard they are to capture.

4 categories of implicit knowledge in a mature codebase

1. Standards you’d write down if you could, like naming, package structure, error handling, etc. Yes, these are documentable and you should, indeed, document.
2. Decisions tied to past incidents, like “We stoped injecting repositories into controllers after the 2024 refactor.” Documenting these architectural decison records (ADR) is important, but they go stale.
3. Cross-domain contracts, like how billing expects events to be shaped from the catalog. Shift documentation so it doesn’t only include the “what” that lives in the API specs, but so it also incluses the “why” that lives in people’s heads.
4. Taste and judgment, like “This abstraction is clever, but we would never ship it here. This is, generally, undocumentable.

The first instinct is to document everything and point the AI at it. While that’s useful, it is not enough. You’ll never capture every historical decision and edge case—and trying to do so, all at once, will stall the team and leave gaps.

The practical approach is narrower: document the rules the AI can reliably follow, then build feedback loops to catch the rest.

The hardest category is taste. That is the judgment you hire experienced engineers for. It cannot be fully captured in a file.

Brownfield engineering for agentic AI in the wild

We run into this scenario quite regularly. Most recently, we encountered it on a multi-year, multi-domain platform with dozens of microservices and ~70 engineers.

Agentic AI can work in this kind of environment, but not by default.

How did we approach it?

1. We used Amazon Q for more than a year. It helped with autocomplete, but we had no effective way to teach it our engineering conventions.
2. In January 2026, we moved to Kiro and that changed everything.

We built a five-layer guardrail stack. The pattern should transfer to most agentic IDEs, though the naming below is specific to Kiro.

The 5-layer guardrail stack

• Layer 1: steering files → .kiro/steering/*.md ; global conventions the agent reads on every task
• Layer 2: spec files → .kiro/specs/ ; feature-level specs that drive multi-step agent work
• Layer 3: automated checks → Linters; precommit hooks; Kiro agent hooks on pull request (PR) open
• Layer 4: Kiro review agent → Separate agent reviews every AI-generated PR against steering files; catches ~80% of drift
• Layer 5: human review → Senior engineers fouced on architecture and taste (not acting as linters)

Where did we get the most leverage?

Most of the leverage came from the first two layers: steering and spec files.

We spent about six weeks writing the steering files that Kiro reads on every task, and that work paid off well beyond the tool. Writing for an agent that starts fresh every time forced us to be precise, and it surfaced disagreements between domain teams that had been quietly drifting apart for the better part of a year. The agent became the forcing function that made us resolve the ambiguity.

Layers 3–5 protected against having to review the same mistakes over and over. Within a few weeks, the patterns we had encoded as linter rules and hooks stopped reaching human reviewers at all.

What’s the outcome for our client?

The review agent now catches 80% of the convention drift that used to land in senior engineers’ queues.

How senior engineer review time changed after the 5-layer guardrails

The throughput gain is real, but the more important shift* is where senior engineers now spend their attention.

• Convention drift and structure dramatically dropped from 60% to 10%.
• Architecture and design valuably increased from 20% to 55%.
• Security and authorization increased slightly from 15% to 20%.
• Actual bug review increased from 5% to 15%.

*Percentages are based on manually categorizing review comments (convention, design, correctness) across a sample of PRs from two sprints before and after the guardrail stack was deployed.

For a long stretch, the most experienced people were spending their time on low-level convention checks a good linter should handle. Now they are focused on the actual design questions.

A readiness check for bringing agentic AI into a brownfield system

If you are about to bring agentic AI into a brownfield system, it is worth working through this readiness check before measuring productivity gains.

1. Do you have 1–2 engineers who deeply know your conventions and can spend time teaching? If no, build that capacity.
2. Are you willing to invest 4–6 weeks writing steering files before measuring productivity? If no, expect small wins and steady drift.
3. Do you have automated checks for the patterns the AI keeps getting wrong? If no, build them first. Manual review won’t scale

Once you get to Yes on all these answers, you’re ready to bring agentic AI into a brownfield system.

How do you get maximum value from agentic AI in a brownfield system?

Teams that get real value from AI treat the first quarter as a teaching period. They use that time to make conventions explicit, identify drift, and build guardrails before asking the tool to move faster.

Teams that push for productivity in week one usually end up in one of two places:

1. Some roll the program back.
2. Others absorb a steady stream of small convention-drift problems that never become formal incidents because they arrive one pull request at a time.

In a brownfield system, an agent that has not learned your conventions does not wait for better instructions. It produces confident, well-tested code in the wrong shape. It does that at team speed, faster than reviewers can keep up. Before that becomes your reality, ask the AI to audit your existing documentation against the codebase and produce a log of gaps and inconsistencies. Brownfield documentation is rarely current, and the remediation that would take a senior engineer a week takes about an hour. Get to a trustworthy baseline before you ask the agent to move fast.

If you point AI at an inconsistent codebase, it will not clean up the inconsistency for you. It will learn the inconsistency and reproduce it.

The takeaway? Don’t start with the tool

Start with what your senior engineers know but have never had a reason to write down. Once the system is legible to the agent, it can follow your conventions reliably and free your people for the work that actually needs judgment.

If you skip that step, you will not automate engineering discipline. You will automate the drift you already had.

*Slalom is a fiercely human business and technology company that leads with outcomes and teams with leaders, bringing more together.*