03 Lecture 3 Quiz: From Greenfield to Brownfield

Greenfield development starts from an empty directory where you make every decision — file names, architecture, conventions. Brownfield development means working in an existing codebase with pre-existing constraints, conventions, and users who depend on current behavior. It is not about technology age or team size — it is about whether you start with a blank canvas or an existing one.

Research by Minelli, Mocci, and Lanza (2015) found that roughly 70% of development time goes to program comprehension — reading code, navigating call hierarchies, and building mental models of how existing components interact. The primary developer activity is not writing — it is reading.

In greenfield, tests are part of a workflow you choose to follow. In brownfield, the existing test suite is a contract: it encodes the expected behavior of the system. “All tests pass” is the minimum bar for any change, and pytest is your first and last command. Production validation does not replace tests — users finding bugs is not the same as a test suite preventing regressions.

When you open a 10,000-line codebase, the AI has never seen it. It does not know the directory structure, naming conventions, test patterns, or architecture. Without context, the AI gives vague, generic answers and generates code that does not match the project’s style. The problem is not too much context or window size — it is that the AI starts with zero project knowledge.

A CLAUDE.md provides the AI with a structured map of the project: architecture, key files, testing patterns, git workflows, coding conventions, and common pitfalls. The same question asked with and without this file produces dramatically different answer quality — from vague generalities to specific, accurate references. It complements existing docs rather than replacing them.

CLAUDE.md is influence, not enforcement. When the AI focuses on complex code generation, style rules can be crowded out. This is why CLAUDE.md and automated tooling (pre-commit hooks, linters, CI) are complementary layers: the CLAUDE.md guides the AI’s behavior, and automation catches what slips through. The file is not ineffective — it significantly improves output — but it cannot guarantee perfection.

The brownfield Definition of Done includes: all existing tests pass (no regressions), new code has tests, coverage is maintained, code passes the linter, PR is reviewed, documentation is updated if behavior changed, and conventions are followed. In greenfield exercises like the SO Challenge, “done” simply meant “the plot looks right.” The key distinction is the emphasis on preserving existing behavior and meeting team standards.

AI excels at code explanation, test generation, refactoring suggestions, and documentation drafting in brownfield settings. However, it struggles with architectural decisions (the “why”), unwritten conventions, side effects and state, legacy patterns, and scope control. The key insight is that AI is strongest at tasks involving pattern recognition in visible code, not at understanding invisible context.

Legacy patterns exist because removing them would break real users. The AI does not understand the historical context — why a workaround was added, which downstream systems depend on the current behavior. It may suggest locally sensible changes that violate broader constraints. While knowledge cutoffs and missing git history are real limitations, the core issue is that AI cannot distinguish intentional legacy patterns from genuinely improvable code.

Pre-commit hooks run automatically on every git commit and catch violations (like PEP 8 issues from ruff) before they enter the repository. They serve as the enforcement layer that complements CLAUDE.md’s influence layer — because even with comprehensive project instructions, AI-generated code can still contain style violations. They do not provide feedback to the AI during generation, nor do they replace code review.

Different AI tools use different file names for the same concept: Claude Code uses CLAUDE.md, GitHub Copilot uses .github/copilot-instructions.md, and Cursor uses .cursorrules. The file names differ, but the content and purpose are identical: encoding project context that the tool reads automatically.

In a shared codebase, the flat diary/001-xxx.md sequence would produce merge conflicts. Instead, the diary uses a branch-based structure: diary/feature//001-xxx.md. Each entry is committed alongside the code it documents, and commit messages use the [diary] prefix. PR descriptions complement the diary but do not replace it.

The existing test suite acts as a contract for expected behavior. When refactoring, all existing tests must pass without modification. If a test breaks, the refactoring changed behavior — you fix the refactoring, not the test. Code reviews help, but they cannot catch all behavioral changes the way an automated test suite can.

In a brownfield project, conventions are pre-existing: naming patterns, import ordering, docstring format, test framework style. Without explicit context (like a CLAUDE.md), AI follows generic conventions (PEP 8) that may not match the project’s actual style. Inconsistency makes the codebase harder to read and maintain for all contributors. This applies to all projects, not just open-source ones.

Locust’s entire purpose is measuring and generating load. If a change adds 5ms of processing per request at 10,000 requests/second, that is 50 seconds of overhead per second. Performance is not a non-functional requirement — it IS the product. This makes benchmarking a natural part of every exercise. While CI benchmarks exist in some projects, the fundamental reason here is Locust’s core purpose.