When Code Already Exists (Brownfield)

Back in Lesson 4, Ms. Sharma asked for one more thing: a reminder the day before a book is due. We said that idea would kick off its own small Inception. Let's actually build it now — and notice something important along the way: this time, the Class Library Loan Tracker already exists.

That single fact changes how Inception starts.

Greenfield vs. Brownfield, for Real This Time

Back in Lesson 2, "greenfield" meant starting from nothing — no code, no folder, just Ms. Sharma's paper system and a problem. This time, Workspace Detection runs the same check it always does, but gets a different answer: there's already a library-loan-tracker/ project sitting right there, with working code and an aidlc-docs/ folder full of history.

That's brownfield: building on top of something that already exists, rather than starting from a blank folder. And it triggers a stage we haven't seen yet.

Reverse Engineering: Robo Reads the House Before Renovating It

Reverse Engineering only runs for brownfield projects, and only the first time — if it already ran before and the code hasn't meaningfully changed since, Robo loads what it wrote last time instead of redoing the work.

What it actually does:

• Scans every part of the project, not just the parts you happen to mention
• Works out the business purpose of each piece — what does this code actually do, in plain terms?
• Looks for infrastructure, build tooling, and how services talk to each other
• Checks code quality signals: test coverage, linting setup, obvious technical debt

It then writes up what it found as a set of documents in aidlc-docs/inception/reverse-engineering/:

For our small library tracker this is a quick pass — a handful of Python files, one small domain model. For a real production system with years of history, this is the step that keeps Robo from confidently proposing something that quietly breaks a part of the system nobody remembered existed.

Wait for Explicit Approval applies here too, same as every other stage — read what Robo found before moving on. This is your one chance to correct a wrong assumption before it becomes the foundation for everything that follows.

Writing a Brownfield Vision Document

The Vision Document changes shape too. A greenfield vision starts from "what are we building"; a brownfield one has to start with "what already exists" — and, critically, what must be left alone:

# Vision: Due-Date Reminders — Class Library Loan Tracker

## Current State
The Class Library Loan Tracker is a small Python app already in use by
Ms. Sharma's class. It records loans and returns, blocks double-booking
and over-limit loans, and shows an overdue list she checks manually.
It has no notification system of any kind today.

## What We Are Adding
A reminder that fires the day before a loan is due, so Ms. Sharma
doesn't have to remember to check the overdue list herself.

## Features In Scope
- A daily check for loans due tomorrow
- Some way to surface that reminder to Ms. Sharma (exact method —
  open question below)

## Features Out of Scope
- Reminders to students directly (Ms. Sharma is still the only user)
- Any change to the loan or return recording flow

## What Must NOT Change
- The existing `create_loan()` / `return_loan()` logic and its rules
  (2-book limit, no double-booking)

- The overdue list's current behavior — this is additive, not a
  replacement

## Open Questions
- Should the reminder be an email, a message when she opens the app,
  or something else? She doesn't check her school email often.

The "What Must Not Change" section is doing real work here. Reverse Engineering told Robo how the existing loan logic works; this section tells it, explicitly, not to touch that logic while building something new next to it. Without it, a busy or overly helpful AI agent might "improve" something nobody asked it to improve — which is exactly the kind of quiet drift Lesson 7's "never vibe code" rule exists to prevent, just showing up one step earlier, at the planning stage instead of the code.

The Technical Environment Document, Brownfield Style

The greenfield version described a stack from scratch. The brownfield version describes the stack that's already there, so Robo builds in a way that fits — not a way that happens to be technically correct but looks like it was written by someone else entirely:

# Technical Environment: Due-Date Reminders

- Existing stack: Python 3.12, no framework, local file storage
- Existing test framework: pytest — new code should have tests in
  the same style as tests/test_loan.py

- What to add: a small scheduled check, plus one new function for
  surfacing the reminder

- What must stay unchanged: create_loan(), return_loan(), and the
  local-file storage approach — no new database

- Example pattern: follow the style already used in src/models/loan.py
  (see BookAlreadyOnLoanError for how we raise and handle domain errors)

That last line matters more than it looks. Pointing Robo at a real, existing file is far more effective than describing a coding style in words — it gives Robo an actual pattern to match, so the reminder code looks like it grew out of the same codebase instead of being bolted onto it.

Everything After This Looks Familiar

Once Reverse Engineering and the brownfield Requirements Analysis are approved, the rest of the journey is exactly what you already know: Workflow Planning, maybe Application Design if the reminder needs a new component, Units Generation if it's more than one unit — then Construction, unit by unit, exactly as Lesson 3 walked through, finishing with Build and Test.

Brownfield only changes how Inception starts. Everything downstream of "here's the plan" works the same whether the project is a day old or three years old.

What's Next

One more piece of the real methodology worth knowing about: a way to layer extra, stricter rules on top of the core workflow — for security, for testing style, for whatever your project or organization needs enforced every time.

Continue to: Extensions — Opting Into Extra Rules