Brownfield Agentic Engineering

[!abstract] In one sentence In a brownfield system the code isn’t the whole truth, so make hidden constraints visible, lock today’s behaviour before changing it, and let autonomy follow blast radius, observability and recoverability, not the model’s confidence.

Notes on Addy Osmani’s Brownfield Agentic Engineering (September 2026). It’s real-world evidence for the approach I set out in A Safe Path for AI Agents in a Large Codebase.

The method

1. Draw zones, and have a person own the map.

   • Green: good tests, current conventions, good isolation. Agents work in a tight loop.
   • Yellow: mixed quality. Write characterization tests first, then let agents change code.
   • Red: auth, billing, permissions, payroll. A human pairs on every step, or the work doesn’t happen.
   • Zones move only when earned: yellow becomes green once tests exist and the owner has reviewed the first agent changes.

2. Write down what the code can’t say, and nothing else. That means business nuance, the reasons behind odd design choices, domain rules, external constraints, and the history of code that looks wrong. The agent can read structure, naming and types for itself.

3. Use a research pipeline for yellow and red work:

   1. Research, read-only.
   2. A comprehension memo in which every claim cites a source.
   3. A plan, in a fresh context, where a human picks the path.
   4. Implementation, which halts if the map turns out to be wrong.
   5. Review, in a fresh context, working back from the acceptance criteria.

   “Chat history isn’t a great system of record.”

4. Lock behaviour first. Characterization tests pin what the system actually does today, including ugly behaviour the business relies on. Never let the same session write the tests and make them pass.

5. Follow a zero-risk progression: explain the system → characterization tests → mechanical transforms (codemods, renames, moves) → dead-code inventories → the hairy parts last.

6. Climb an escalation ladder for repeated corrections: silent fix → review comment → instruction line → skill → lint rule, hook, type or test → deny rules, CI checks, scoped credentials. Use prose only for what can’t be enforced. “Every repeated correction is a missing piece of the harness.”

7. Finish migrations. A migration is done when the new path works and the old dependency is demonstrably gone. Half-finished migrations give agents contradictory precedent.

8. Parallelise last. Fan out only once a unit has a reliable judge, cheap recovery and a review format people can absorb. Otherwise one senior reviewer becomes the queue.

Failure modes

• Green suite, wrong behaviour: the agent “fixes” legacy behaviour the business depends on.
• Blindness: tests stay green while the “replacement” still calls legacy code. In SWE Refactor Bench only about 5% of runs passed all three checks: the migration audit, the behavioural tests and independent verification.
• Worktrees isolate files, not behaviour. They still share credentials, local services and network access.
• Misleading metrics: lines generated and green suites. Track these instead:
  • lead time
  • review minutes
  • interventions
  • escaped defects
  • rollbacks
  • parity mismatches
  • legacy dependencies removed

Examples worth knowing

• Parity testing: GitHub’s Scientist runs the old and new paths and diffs the results. Netflix shadowed GraphQL traffic and promoted the new path only when payloads matched.
• Bun’s Zig → Rust port: about 50 workflows in 11 days on 535,000 lines, with two adversarial reviewers per unit and the existing suite as the merge gate. Hours went into a porting guide before any agent ran.
• A VB6 → C# study: 92% behavioural equivalence on simple features, 47% on complex ones. Unit size is the lever.
• Elsewhere: Stripe moved 3.7M lines to TypeScript via codemods, with no agents. Spotify merges 650+ agent PRs a month on infrastructure built years earlier. Asana cleared a multi-year Enzyme backlog in two weeks (vendor-reported).

How it maps to my adoption ladder

My point (A Safe Path for AI Agents in a Large Codebase)	Osmani’s version
Adoption ladder: read-only → tests/docs → bounded features → critical paths last	Zero-risk progression + green/yellow/red zones
Smaller problem spaces (bounded contexts, small tickets)	Unit size is the lever (92% vs 47%)
Executable rules (fitness functions, contract tests)	Escalation ladder: corrections → hooks, tests, deny rules
Security: least privilege, small blast radius	Autonomy follows blast radius; red zones; scoped credentials
Expand as the team matures, not ahead of it	Zones move only when earned

What it added for me: characterization tests before any change, the comprehension memo, never letting one session write both the tests and the code, and “done” includes deleting the old path. Related: Agent Skills and Harness Engineering · Don’t Read the Code? Verifying AI-Written Code · Architecture Fitness Functions.