A greenfield product begins with few technical constraints and many product unknowns. A brownfield system begins with code, data, integrations, users and operational history, much of it undocumented.
The same workflow cannot treat those two situations as equal. In greenfield work, the main danger is building the wrong thing well. In brownfield work, the main danger is changing the right thing and breaking something nobody knew depended on it.
| Concern | Greenfield | Brownfield |
|---|---|---|
| Main uncertainty | What should exist? | What already exists, and what will break? |
| Architecture task | Establish boundaries and principles | Recover the actual boundaries and constraints |
| Data | Define the model | Understand ownership, quality and migration |
| Delivery risk | Building the wrong product | Damaging a working ecosystem |
| Fast path | A thin vertical slice | A small change behind a safe boundary |
| Key evidence | User and market learning | Code, telemetry, contracts and incidents |
Mopane Logistics is fictional, and its systems and figures are illustrative. In the quarter after its first pilot, Mopane's software team ran both kinds of work at once. The greenfield piece was a new proof-of-delivery app for drivers. The brownfield piece was Dispatch, the twelve-year-old system of record whose hidden finance export started this series.
The greenfield path
For new software, resist the urge to produce a complete future architecture before the product has been tested against real use. A sensible sequence is: understand the problem and the users, state the risks and hypotheses, build a thin end-to-end slice, gather evidence from use, then decide what to expand.
Use BMAD to make hypotheses, constraints and acceptance criteria explicit. Do not let it turn uncertainty into false certainty through polished documents. A generated product requirements document reads with the same confidence whether its claims come from user research or from the model's general knowledge of logistics apps. The team has to know which is which.
Mopane's driver app
Mopane's drivers record proof of delivery on paper, which is photographed at the depot and keyed into Dispatch the next day. Disputes about whether a delivery arrived, and in what condition, take days to resolve.
The first conversation with the analyst perspective produced an ambitious scope: route optimisation, live customer tracking, in-app chat with receiving staff, vehicle checks and fuel logging. All of them were plausible. None of them was evidence.
The product owner cut the first specification back to one route, Durban to Pietermaritzburg, and six capabilities: look up the day's consignments, capture a timestamp, a photograph and a signature, work fully offline, and synchronise when the phone regains signal. Offline capture was the non-negotiable requirement. The N3 between Durban and Pietermaritzburg has stretches of weak coverage, and several receiving bays are in basements and warehouses with no signal at all.
The specification marked its hypotheses as hypotheses:
- Drivers will capture a signature at more than 90% of stops. Hypothesis; to be measured on the pilot route.
- Synchronisation within four hours of capture is good enough for dispute handling. Hypothesis; to be confirmed with the customer service lead.
- Receiving staff will sign on a driver's phone. Unknown; two large customers may require their own paperwork.
Six weeks of use on one route answered all three, and the third answer changed the design: one large retailer insists on its own goods-received stamp, so the app now photographs the stamped document instead of asking for a signature at those sites. A full architecture written up front would have had to be unwritten.
The brownfield path
In an existing system, project context is a deliverable in its own right. BMAD's documentation has a section on starting in an existing codebase, and the stable release includes a project-context skill. It works through the repository with the team and writes a short, verified block of agent instructions into the project's AGENTS.md file, where every later session will read it. Earlier versions produced a separate project-context document; the current skill writes to AGENTS.md instead.
The aim of the exercise is to establish, and write down:
- repository structure and build process;
- the runtime and deployment model;
- critical data stores;
- external interfaces and hidden consumers;
- authentication and authorisation;
- coding conventions and supported dependencies;
- which tests can be trusted;
- known failure modes and who owns operations;
- regulatory or audit constraints.
What Mopane found in Dispatch
The tech lead and two engineers spent four days on context recovery for Dispatch, using the project-context skill and the AI tool to read the code, the database schema and the deployment scripts, and checking every finding with people who had worked on the system.
They found three things that mattered.
The finance export. The nightly job that broke in Part 1 is a SQL Server Agent job that reads eleven Dispatch columns by name and writes a file for the finance system. It is now listed in AGENTS.md with the rule that those column names are a contract with finance and cannot change without finance's agreement.
A second hidden consumer. A depot manager in City Deep had, years earlier, built a spreadsheet report on a database view of consignments. Three depots now used it for daily planning. Nobody in the software team knew it existed until the database permissions review showed a reporting login nobody recognised. The view is now documented, and changes to it are treated as a breaking change.
A flaky test that was not flaky. One integration test in Dispatch failed intermittently and had been marked "ignore" for two years. When an engineer finally traced it, the failure turned out to be a real timing contract with the finance export. The test failed whenever consignment status updates were still running at the moment the export ran, and the export then read half-updated rows. The "flaky" test was the only thing in the codebase that knew about the problem. It is now fixed, and running.
For more on recovering what an older system knows, see your legacy system is a witness, not just a liability.
The bridge, not the rewrite
For brownfield modernisation, introduce an incremental boundary, such as an API facade, an event stream, an adapter or a new service around one contained capability, rather than a rewrite.
This fits the strangler approach. New behaviour goes in around the old system. Traffic or capability moves across gradually. The old part is retired only when the evidence shows nothing still depends on it.
At Mopane, the facade is a small consignment API in front of Dispatch. The driver app's proof-of-delivery data comes in through it, and the customer portal's new features read through it. Dispatch remains the system of record, and the finance export and the depot spreadsheet keep working against the same tables and view they always used. When the team eventually moves proof-of-delivery storage out of Dispatch, the facade's contract stays the same and only its implementation changes. Our Forward Deployed AI series covers the same pattern from the integration side.
Questions that must never be answered by guessing
Some brownfield questions look like something an AI tool could answer from the code. They cannot, because the answer lives in people, contracts or production:
- Is this table the system of record?
- Can this interface change without another team's approval?
- Which batch jobs depend on this field?
- Is a failing test obsolete, or warning us about a real contract?
- Do production and repository configuration match?
- Who owns this service now the original team has left?
When the answer is unknown, the artefact should say unknown and open an investigation. An invented answer is worse than an incomplete specification, because the invented answer looks finished.
Mopane made this a written rule. Every Dispatch specification has an "unknowns" section, and a change cannot move to build while an unknown in it touches data, an interface or a scheduled job. The first specification written under that rule listed four unknowns. Three were resolved with a phone call. The fourth, whether a customer's EDI integration still read a legacy status code, took a week to answer, and the answer was yes. For worked examples of both paths, see four worked examples: greenfield, brownfield, a small defect and an AI feature.
The short version
Different starting points, different dangers. Greenfield risks building the wrong thing; brownfield risks breaking what works.
In greenfield, mark hypotheses as hypotheses. A thin slice and real use beat a polished architecture written up front.
In brownfield, context is a deliverable. Recover structure, consumers, contracts and trusted tests, and write them where every session will read them.
Bridge, do not rewrite. A facade lets capability move across while the old system keeps serving what depends on it.
Write "unknown" when it is unknown. An invented answer looks finished, which makes it more dangerous than a gap.
Previous: Part 3, getting started without drowning in process. Next: Part 5, the BMAD team is not a replacement for your team. All parts are on the series page.
How CloudNala can help
We help teams use AI-assisted delivery on the systems they already run as well as on new ones. In brownfield work, we lead context recovery on older codebases, find hidden consumers, recover contracts and identify the tests that can be trusted, then write it all down where every later AI session will read it. We design facade and strangler paths that let capability move without a rewrite. On new products, we keep the first specifications honest about what is known and what is still a hypothesis.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Plan an AI Delivery Pilot or write to us at consult@cloudnala.co.za