Greenfield vs brownfield: building with agents

"Building with AI agents" describes two genuinely different experiences depending on where you start. Spin up something new and the agent feels magical — fast, clean, unblocked. Point it at a ten-year-old codebase and it can feel useless — confidently wrong, breaking things, missing the obvious. Same agent, opposite experience.

The difference is greenfield versus brownfield, and understanding it tells you why the agent struggles where it does and how to help it. Here's the honest comparison.

Two very different starting points

Greenfield is new construction — building from scratch, no existing code to respect. Brownfield is renovation — working inside an existing, often aged, codebase with its own history, patterns, and constraints.

For human developers, brownfield has always been harder, for the obvious reason: you have to understand what's there before you can change it safely. With agents, that same gap exists — but it bites differently, because of what the agent can and can't see.

Greenfield: the agent has a clean slate

On greenfield, the agent and you start from the same place: nothing. There's no hidden context to miss, because there's no history yet. Every decision is being made now, in the open, and the agent participates in making them.

This is why agents shine on new projects. There's no undocumented past to misread. The context that exists is the context you're both creating, and a contextbase here grows naturally from the first session. Greenfield is the agent's best case — give it a clear brief and let it run.

Brownfield: tacit knowledge the agent can't see

Brownfield is harder for one specific reason: the codebase is full of tacit knowledge — reasoning that lives in people's heads and nowhere in the code. Why this query is structured oddly (a bug workaround), why this module avoids that pattern (a past disaster), which parts are fragile (everyone just knows).

The agent reads the code but not the reasoning. So it sees the odd query as a mistake and "fixes" it — reintroducing the bug. The guides on brownfield AI development keep stressing this: legacy carries knowledge agents can't reach on their own, and missing the moment to inject it produces large changes full of subtle bugs.

Stuart Leo

Greenfield, the agent misses nothing because there's nothing to miss. Brownfield, it misses everything the codebase never wrote down.

Why specs and context matter more in brownfield

This is the crux of the comparison. On greenfield, you can lean on the agent's defaults — there's no existing reality to violate. On brownfield, defaults are dangerous, because the existing system has constraints the agent doesn't know about. So brownfield demands more explicit context and tighter specs:

The same spec discipline helps both, but brownfield can't skip it — the spec and the captured context are what stop the agent from confidently breaking things.

How to approach each

• Greenfield: brief clearly, let the agent run, and capture context from session one so the project never becomes an opaque brownfield later.
• Brownfield: supply the missing context. Have the agent map the area first, write specs for the change (not the whole system), capture decisions and gotchas as you go, and verify hard against existing tests. Grow a contextbase into the legacy where you work.

Greenfield lets the agent run — brownfield makes you supply the context the code never wrote down. Know which you're in, and you'll know why the agent behaves the way it does.

Start here: see how to add a contextbase to a legacy project, C² vs spec-driven development, or read the method.