How AI-DLC Handles Brownfield Code Generation: Key Differences from Greenfield Projects

AI-DLC detects existing code repositories and activates brownfield mode, triggering a reverse-engineering phase that produces targeted file modifications rather than new code creation, ensuring incremental evolution that preserves existing architecture and conventions.

The awslabs/aidlc-workflows repository defines a multi-phase pipeline for AI-driven software development that fundamentally adapts its behavior based on workspace state. Unlike greenfield generation that creates code from scratch, AI-DLC brownfield code generation treats existing codebases as living systems requiring surgical precision—scanning current implementations, documenting existing architecture, and generating compatible changes that respect established patterns.

Workspace Detection and the Brownfield Flag

Before any generation occurs, AI-DLC executes a Workspace Detection phase that scans the repository for existing source files, build manifests, and infrastructure indicators. According to aidlc-rules/aws-aidlc-rule-details/inception/workspace-detection.md, when the system detects any existing code, it automatically sets the brownfield = true flag. This boolean switch alters the entire downstream pipeline, injecting brownfield-specific stages and modifying the behavior of standard construction phases.

The detection logic examines specific markers including package.json, pom.xml, CDK stacks, Terraform files, and source directories to determine project maturity. This automated classification ensures that AI-DLC never treats legacy code as a blank slate.

The Reverse-Engineering Stage

For brownfield projects, AI-DLC inserts a mandatory Reverse-Engineering stage immediately after workspace detection and before requirements analysis, as defined in aidlc-rules/aws-aidlc-rule-details/inception/reverse-engineering.md. This stage performs three critical functions:

1. Discovery: Identifies all packages, build systems, and infrastructure artifacts present in the repository
2. Documentation Generation: Creates a comprehensive architectural snapshot including architecture.md, code-structure.md, and api-documentation.md that records components, dependencies, and code-quality metrics
3. Artifact Storage: Persists these documents under aidlc-docs/inception/reverse-engineering/ to serve as reference material for subsequent generation phases

These reverse-engineered artifacts become the authoritative source of truth about the current system state, allowing the AI to understand implicit conventions and technical constraints before proposing changes.

Code Generation Strategy: Modify Versus Create

When the Code-Generation phase executes, brownfield mode fundamentally changes the definition of "generate." According to aidlc-rules/aws-aidlc-rule-details/construction/code-generation.md, the rules explicitly state that for brownfield projects, "generate means modify existing files when appropriate, not create duplicates." This principle drives several behavioral differences:

Documentation and Source of Truth

Greenfield projects rely solely on Vision and Technical-Environment documents as input. Brownfield projects augment these with the reverse-engineered architecture documents, creating a composite source of truth that includes both desired future state and documented current state.

File Handling Patterns

• Greenfield: Creates new directories and files from scratch using canonical templates
• Brownfield: Locates specific target files (e.g., order-service/src/handlers/returnRequests.ts) and performs surgical insertions or replacements while preserving surrounding context and formatting

Style Preservation and Dependency Management

When operating in brownfield mode, AI-DLC preserves existing naming conventions, folder layouts, and coding styles to maintain codebase consistency. For dependencies, rather than simply adding new libraries, the system detects version conflicts with current package.json or pom.xml files and suggests in-place upgrades that respect existing dependency trees.

Incremental Testing Strategy

Testing behavior diverges significantly between modes:

• Greenfield: Generates fresh unit and integration test scaffolding
• Brownfield: Augments existing test suites, re-runs them to verify baseline functionality, and only adds test coverage for newly added behavior

Required Documentation for Brownfield Projects

Brownfield code generation imposes stricter documentation requirements to ensure compatibility. According to docs/writing-inputs/example-minimal-vision-brownfield.md, the Vision document for brownfield projects must contain:

• A "Current State" section describing existing components and architecture
• An explicit "What Must Not Change" list defining architectural constraints and untouchable components

Additionally, the Technical-Environment document must describe the existing stack currently in production, rather than a desired future state. These constraints provide the AI with guardrails necessary to generate changes that integrate seamlessly with legacy systems.

Practical Examples of Brownfield Code Generation

The following examples demonstrate how AI-DLC modifies existing files rather than generating new ones:

Adding an endpoint to an existing TypeScript service:

[AI‑DLC generated diff]  
--- a/src/handlers/returnRequests.ts
+++ b/src/handlers/returnRequests.ts
@@
 import { approveReturn, rejectReturn } from '../services/returnService';
 
 // New endpoint: GET /returns/:id/status
+export async function getReturnStatus(req, res) {
+  const { id } = req.params;
+  const status = await getReturnStatusFromDB(id);
+  return res.json({ id, status });
+}
 
 // Existing endpoint: POST /returns
 export async function createReturn(req, res) {
   // …
 }

Updating dependencies in an existing Node.js project:

{
  "name": "order-service",
  "version": "1.4.2",
- "dependencies": {
-   "aws-sdk": "^2.1000.0"
+ "dependencies": {
+   "aws-sdk": "^2.1200.0"
  },
  "scripts": {
    "test": "npm run lint && npm run unit-test"
  }
}

In both cases, AI-DLC locates the exact file and injects only necessary changes, preserving surrounding code, formatting, and existing logic paths.

Summary

• AI-DLC brownfield code generation begins with workspace detection that sets the brownfield = true flag in aidlc-rules/aws-aidlc-rule-details/inception/workspace-detection.md
• A mandatory Reverse-Engineering stage creates architectural snapshots stored in aidlc-docs/inception/reverse-engineering/ before any code generation occurs
• Code generation switches from file creation to surgical modification, locating existing targets and inserting changes while preserving style and structure
• Dependency management detects version conflicts and suggests in-place upgrades rather than blind additions
• Documentation requirements include "Current State" and "What Must Not Change" sections to constrain the generation scope
• Testing augments existing suites rather than replacing them, ensuring regression safety

Frequently Asked Questions

How does AI-DLC detect whether a project is brownfield or greenfield?

AI-DLC executes a Workspace Detection phase that scans the repository for existing source files, build manifests (such as package.json or pom.xml), and infrastructure artifacts. When any existing code is detected, the system sets brownfield = true in the workflow configuration, automatically triggering brownfield-specific pipelines and documentation requirements.

What files does the reverse-engineering stage create for brownfield projects?

The reverse-engineering stage generates comprehensive architectural documentation including architecture.md, code-structure.md, and api-documentation.md. These files are stored under aidlc-docs/inception/reverse-engineering/ and capture the current system’s components, dependencies, and code-quality metrics to serve as reference material for subsequent generation phases.

How does AI-DLC code generation differ between greenfield and brownfield repositories?

For greenfield projects, AI-DLC creates new directories and files from scratch using canonical naming conventions. For brownfield projects, the system locates existing target files and performs surgical modifications—inserting or replacing specific code snippets while preserving surrounding context, formatting, and existing conventions, as explicitly defined in aidlc-rules/aws-aidlc-rule-details/construction/code-generation.md.

What specific documentation is required for brownfield AI-DLC projects?

Brownfield projects require a Vision document containing a "Current State" section describing existing architecture and an explicit "What Must Not Change" list defining constraints. The Technical-Environment document must describe the existing production stack rather than a desired future state, ensuring the AI generates changes compatible with current infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}