Evolutionary Architecture

Evolutionary Architecture

"An evolutionary architecture supports guided, incremental change as a first principle across multiple dimensions." — Neal Ford, Rebecca Parsons, Pat Kua

Traditional architecture tries to predict the future. Evolutionary architecture accepts that change is inevitable and builds mechanisms to guide it safely.

---

🎯 Core Concepts

The Three Pillars

┌─────────────────────────────────────────────────────────────┐
│              EVOLUTIONARY ARCHITECTURE                       │
│                                                              │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│   │  Incremental │  │   Fitness   │  │ Appropriate │       │
│   │    Change    │  │  Functions  │  │   Coupling  │       │
│   │              │  │             │  │             │       │
│   │ Deployment   │  │ Automated   │  │ Quantum     │       │
│   │ pipelines    │  │ tests that  │  │ boundaries  │       │
│   │ Feature      │  │ verify      │  │ Team        │       │
│   │ toggles      │  │ architecture│  │ alignment   │       │
│   │              │  │ goals       │  │             │       │
│   └─────────────┘  └─────────────┘  └─────────────┘       │
│                                                              │
│   Change without guidance = chaos                            │
│   Fitness without change = stagnation                        │
│   Coupling without fitness = fragile                         │
└─────────────────────────────────────────────────────────────┘

---

1️⃣ Fitness Functions

Definition: Automated tests that verify architectural goals and constraints. Like unit tests for architecture.

Types of Fitness Functions

| Type | Scope | When It Runs | Example | |------|-------|-------------|---------| | Atomic | Single component | Unit test phase | "No package has >20 classes" | | Holistic | Whole system | Integration test | "API response time 80% | pytest, jest, go test | | Observability | All services expose /health and /metrics | Custom validators | | Coupling | No circular dependencies between modules | madge, import-linter | | Modularity | Package cohesion score > threshold | jdepend, structure101 |

CI/CD Integration

# .github/workflows/architecture-fitness.yml
name: Architecture Fitness

on: [pull_request]

jobs:
  fitness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 1. Dependency direction
      - name: Check Clean Architecture boundaries
        run: |
          pip install import-linter
          lint-imports

      # 2. Cyclomatic complexity
      - name: Check complexity
        run: |
          go install github.com/fzipp/gocyclo@latest
          gocyclo -over 15 ./...

      # 3. No secrets
      - name: Scan for secrets
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: main

      # 4. API latency (if changes touch API)
      - name: Performance regression test
        if: contains(github.event.pull_request.changed_files, 'api/')
        run: |
          docker-compose up -d
          k6 run --summary-trend-stats="avg,min,med,max,p(95),p(99)" tests/performance/api.js

      # 5. Coverage gate
      - name: Test coverage
        run: |
          go test -coverprofile=coverage.out ./...
          go tool cover -func=coverage.out | grep total | awk '{print $3}' | sed 's/%//' | awk '{if ($1  "Organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations." — Melvin Conway

### Implications

| Team Structure | Architecture Result |
|---------------|---------------------|
| One big team | Monolith (natural) |
| Frontend + Backend teams | Frontend/Backend split |
| Feature teams (cross-functional) | Vertical slices, microservices |
| Platform + Product teams | Platform + product services |

### Team Topologies Mapping

| Team Type | Owns | Architecture |
|-----------|------|-------------|
| **Stream-aligned** | One business capability | One Bounded Context / Service |
| **Platform** | Internal tools, infrastructure | Platform services, shared libraries |
| **Complicated Subsystem** | Complex domain (ML, security) | Specialized service |
| **Enabling** | Temporary expertise injection | No permanent ownership |

---

## 🚫 Evolutionary Anti-Patterns

| Anti-Pattern | Symptom | Fix |
|-------------|---------|-----|
| **Fitness Function Theater** | Tests exist but never fail | Make them fail intentionally to verify they work |
| **Ignoring Failures** | Fitness fails, but PR merges anyway | Block merge on fitness failure |
| **Too Many Dimensions** | 50 fitness functions, team overwhelmed | Start with 3-5 most critical |
| **Static Architecture** | No changes in 6 months | Architecture should evolve; stasis is a smell |
| **Wrong Coupling** | Services chatty across team boundaries | Reorganize teams or service boundaries |
| **Premature Extraction** | Microservices at 3-person startup | Start monolith, extract when pain appears |

---

## 📋 Evolutionary Architecture Checklist

When starting a new project:

- [ ] Identified 3-5 critical architectural dimensions
- [ ] Defined fitness functions for each dimension
- [ ] Integrated fitness functions into CI/CD
- [ ] Chose appropriate coupling (monolith → modular → microservices)
- [ ] Aligned team structure with architecture boundaries
- [ ] Planned strangler fig path for legacy integration (if applicable)
- [ ] Documented architecture decisions in ADRs

---

## 🔗 Integration with Other Skills

| Skill | Integration |
|-------|-------------|
| `c4-model` | C4 diagrams show current architecture; fitness functions verify it |
| `ddd-core` | Bounded Contexts = natural architectural quantum boundaries |
| `architecture-decision-records` | ADRs document "why" for each evolutionary step |
| `dora-core` | Deployment Frequency + Lead Time = incremental change velocity |

---

## 📚 References

- [Evolutionary Architecture](https://www.oreilly.com/library/view/building-evolutionary-architectures/9781491986356/) — Neal Ford, Rebecca Parsons, Pat Kua (O'Reilly)
- [Software Architecture: The Hard Parts](https://www.oreilly.com/library/view/software-architecture-the/9781492086888/) — Ford, Richards, Sadalage, Dehghani
- [Fitness Function-Driven Development](https://www.thoughtworks.com/insights/articles/fitness-function-driven-development) — ThoughtWorks
- [Strangler Fig Pattern](https://martinfowler.com/bliki/StranglerFigApplication.html) — Martin Fowler
- [Team Topologies](https://teamtopologies.com/) — Skelton, Pais
- [Conway's Law](https://martinfowler.com/bliki/ConwaysLaw.html) — Martin Fowler

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kinhluan](https://github.com/kinhluan)
- **Source:** [kinhluan/skills](https://github.com/kinhluan/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.