# Greenfield: build from complete spec
Spec ? Agent ? System
# Evolution: build from the delta
Spec(v1) ? Spec(v2) ? Diff ? Agent ? Targeted ChangesThe Matrix Methodology regenerates from specs. That breaks when you have customers, production data, and API contracts. Agents work from spec version diffs, not whole specs.
Expand-Migrate-Contract
# Phase 1: Expand — add new alongside old
ALTER TABLE users ADD COLUMN email_v2 VARCHAR(255);
# Writes to BOTH, reads from old
# Phase 2: Migrate — backfill and switch
UPDATE users SET email_v2 = normalize(email);
# Reads from new, writes to both
# Phase 3: Contract — remove old
ALTER TABLE users DROP COLUMN email;
# Rollback no longer possibleMigration Risk Levels
| Type | Example | Risk |
|---|---|---|
| Additive | New nullable column | Safe |
| Structural | Relationship change | Expand-migrate-contract |
| Destructive | Column removal | Needs approval |
Agent Rules for Evolution
- Never DROP without explicit instruction
- Never assume data loss is acceptable
- Flag migrations that lock production tables
- Preservation is default: anything not in diff stays unchanged
Living Specs vs Static Specs
Two approaches to keeping specs aligned with evolving code:
| Approach | How It Works | Tradeoff |
|---|---|---|
| Living Spec | Bi-directional sync: agents update specs when code changes, code regenerates when specs change | No drift, but tooling overhead |
| Static Spec | Specs written upfront, code generated once, manual reconciliation for divergence | Simpler, but specs go stale |
# Living spec workflow
Code change (manual edit) ? Agent updates spec ? Spec reflects reality
# Static spec workflow
Spec change ? Agent generates code ? Manual review catches divergenceLiving specs prevent drift automatically. Tools like GitHub Spec Kit watch code changes and update spec files. Good for teams where code and specs must stay synchronized without manual reconciliation.
Static specs are simpler: write spec, generate code, done. Drift happens when developers edit generated code without updating the spec. Good for solo developers or small teams willing to manually sync specs when needed.
Hybrid pattern (common in 2026):
Static spec for greenfield (regenerate freely). Switch to living spec after first production deploy (preserve and sync).
A project shifts from greenfield to evolution at the first real user or irreplaceable data. Before: regenerate freely. After: diffs only. Hyrum's Law: every observable behavior becomes depended-on.