Brownfield
A brownfield project does not start from scratch. It builds on something that already exists: code, users, data, integrations, processes, technical debt, constraints, and accumulated decisions.
This profoundly changes the way of working.
Difference from greenfield
| Context | Main characteristic |
|---|---|
| Greenfield | Starts from scratch or almost from scratch. |
| Brownfield | Work is done on an existing system. |
In brownfield, the challenge isn't just building. It's building without breaking anything.
Common Risks
- Hidden dependencies.
- Hard-to-understand legacy code.
- Insufficient tests.
- Public contracts that cannot change.
- Accumulated technical debt.
- Incomplete documentation.
- Third-party integrations.
- Users who depend on existing behaviors.
- Data or migration constraints.
Brownfield and AI
AI agents can be dangerous in brownfield contexts if they do not receive enough context. They can generate plausible code that fits poorly with the architecture, duplicates existing logic, or breaks undocumented behaviors.
Before assigning tasks to AI in brownfield contexts, it is advisable to provide:
- relevant architecture;
- repository patterns;
- existing tests;
- constraints;
- public contracts;
- areas that must not be touched;
- regression criteria;
- Always / Ask First / Never boundaries.
Best practices
- Start with small tasks.
- Use more explicit specs.
- Increase human review.
- Run regression tests.
- Ask the agent to read before modifying.
- Protect critical areas of the code.
- Maintain traceability of changes.
- Avoid broad refactorings without approval.
Common mistake
Treating an existing system as if it were a blank canvas. In brownfield, every change coexists with previous decisions, real users, and accumulated constraints. Ignoring that context leads to breakages, technical debt, and regressions.
Resources
🏦 Harness Engineering [in Spanish]Skill Arena · Scrum Manager
🏦 Scrum en equipos con IA [Scrum in Teams with AI, in Spanish]Skill Arena · Scrum Manager
🏦 SDD - Spec Driven Development en equipos ágiles [SDD - Spec Driven Development in Agile Teams, in Spanish]Skill Arena · Scrum Manager
📊 Guía didáctica SDD [SDD Teaching Guide, in Spanish]Resources · Scrum Manager
📊 Guía didáctica Scrum en equipos con IA [Teaching Guide: Scrum in Teams with AI, in Spanish]Resources · Scrum Manager
See also
Want to advance in agility? You can search for calls for courses and exams, or go at your own pace by becoming a member of the Agile Club. This membership includes exclusive resources, e-learning classrooms, and access to Skill Arena: a space to practice and measure your agile skills at your own pace.