Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture Fitness Function

Pattern

A reusable solution you can apply to your work.

An architecture fitness function is an automated check that verifies your system still honors a specific architectural decision, catching structural drift before it compounds into expensive problems.

“An architectural fitness function provides an objective integrity assessment of some architectural characteristic.” — Neal Ford, Rebecca Parsons, and Patrick Kua

Also known as: Architectural Guard, Governance Check, Structural Invariant

Understand This First

  • Feedback Sensor – fitness functions are feedback sensors that target architectural properties rather than individual code correctness.
  • Harness (Agentic) – the harness runs fitness functions as part of its verification pipeline.
  • Architecture – the architectural decisions that fitness functions protect.

Context

At the tactical level, architecture fitness functions sit inside a project’s automated verification pipeline alongside tests, linters, and type checkers. They occupy a specific niche: where a unit test checks that a function returns the right value, and a linter checks that code follows style rules, a fitness function checks that the system’s structure still matches the architect’s intent. Does module A still avoid importing from module B? Do all database calls still go through the repository layer? Does the public API surface remain backward-compatible?

The name comes from evolutionary biology by way of software architecture. In biology, a fitness function measures how well an organism survives in its environment. Neal Ford, Rebecca Parsons, and Patrick Kua adapted the idea in Building Evolutionary Architectures (2017): an architecture fitness function measures how well a system preserves the properties its designers care about as the code changes over time.

Problem

How do you prevent a codebase’s architecture from eroding as dozens of developers and agents make changes every day, each focused on their immediate task rather than the system’s overall structure?

Architectural decisions are easy to make and hard to enforce. A team agrees that the UI layer won’t call the database directly. They document it. They mention it in code reviews. Six months later, someone adds a “quick” database query in a view controller because the proper abstraction felt slow. An agent, lacking the context of that architectural rule, does the same thing on its third task. Each violation is small. Together they dissolve the boundary the team designed.

Manual code review catches some violations, but reviewers are inconsistent, overwhelmed, and focused on functionality rather than structure. The architecture degrades silently until the cost of a single change starts climbing and nobody can explain why.

Forces

  • Architectural rules live in people’s heads. Unless a rule is codified and enforced, it’s a suggestion. Suggestions erode under deadline pressure.
  • Agents don’t absorb tacit knowledge. An agent that hasn’t been told about a layering rule will cross the boundary without hesitation. It generates plausible code, not architecturally sound code.
  • Slow feedback is weak feedback. If a violation is only caught during a monthly architecture review, dozens of dependent changes have already piled on top of it. Early detection is cheap; late detection is expensive.
  • Not every architectural property is easy to check automatically. “The system should be modular” is hard to test. “No package in the ui/ directory imports from infrastructure/db/” is easy to test.

Solution

Express architectural decisions as executable checks that run in the build pipeline, and fail the build when a decision is violated. Each check targets one architectural characteristic and returns a clear pass or fail.

The checks themselves take several forms.

Dependency constraints enforce which modules can import from which. An import linter rule that prevents ui/ from importing db/ directly is a fitness function. ArchUnit (Java), Dependency Cruiser (JavaScript), and similar tools let you write these constraints as test-like assertions: “classes in package X should not depend on classes in package Y.”

API surface checks verify that the public interface of a library or service hasn’t changed in breaking ways. Schema comparison tools, contract tests, and API snapshot tests all serve as fitness functions for interface stability.

Performance budgets set thresholds on measurable quality attributes. A test that fails when a page takes more than 200 milliseconds to load, or when a build artifact exceeds 500 kilobytes, protects a performance decision that erodes one small addition at a time.

Structural rules check properties of the codebase’s organization. “Every public class must have a corresponding test file.” “No function in the core/ module calls external HTTP endpoints.” “Every database migration is reversible.” These turn architectural intentions into automated gatekeepers.

Granularity matters most. Each fitness function should check one property and produce a clear error message when it fails. “Layer violation: ui/checkout_view.py imports db/queries.py directly. Use the services/ layer instead.” A developer or agent that sees this message knows exactly what to fix and why.

Run fitness functions in the same pipeline as tests and linters. They should be fast enough to run on every commit. If a fitness function takes minutes, it belongs in a nightly build rather than the commit pipeline, but it should still run automatically.

Tip

When directing an agent, include your fitness functions in the verification command it runs after every change. If the agent sees “layer violation” in its feedback loop, it will fix the violation on the next iteration. If the fitness function only runs in CI after the pull request is submitted, the agent never learns.

How It Plays Out

A team building a payment processing service has a strict architectural rule: all credit card data must flow through a dedicated payment_gateway/ module, never through general-purpose HTTP utilities. They express this as a Dependency Cruiser rule that fails the build if any file outside payment_gateway/ imports a credit card processing library. Three weeks later, an agent working on a new checkout feature tries to call the payment library directly from a controller. The build fails. The agent reads the error, routes the call through payment_gateway/, and the build passes. A compliance-critical boundary was preserved without a human noticing the attempt.

Not every fitness function targets code structure. An API team takes a different approach: schema snapshot tests that compare the current API definition against the last published version before every release. Removed endpoints, changed field types, dropped required fields all trigger a failure. The check sits in the commit pipeline, invisible on most days. Then an agent working through a refactoring sprint renames a response field from user_name to username. The snapshot test flags a breaking change. Instead of shipping the rename directly, the agent adds a deprecation alias that serves both field names, giving consumers two release cycles to migrate. No human noticed the attempt. The fitness function turned what would have been a customer-facing outage into a smooth transition.

Consequences

Fitness functions turn architectural decisions from social agreements into enforceable rules. They catch violations at the moment they happen, not weeks later during a review. They work especially well in agentic workflows because agents respond to automated signals more reliably than to documentation: an agent that sees a build failure will try to fix it, while an agent that reads “please don’t cross layer boundaries” in an instruction file might still cross them if the instruction gets lost in a long context.

The cost is up-front investment in writing and maintaining the checks. A fitness function that’s too strict blocks legitimate changes. One that’s too loose misses real violations. Finding the right level requires understanding which architectural properties actually matter and which are preferences that shouldn’t be gates. There’s also a maintenance burden: as the architecture evolves, fitness functions must evolve with it, or they become obstacles to the changes they were meant to support.

Fitness functions don’t replace human architectural judgment. They protect decisions that have already been made. Deciding which boundaries to enforce, what performance thresholds to set, and when to relax a rule still requires someone who understands why the system is shaped the way it is.

  • Depends on: Feedback Sensor – fitness functions are a specialized class of feedback sensor targeting structural properties.
  • Depends on: Architecture – the architectural decisions that fitness functions verify and protect.
  • Uses: Harness (Agentic) – the harness runs fitness functions as part of its build-and-verify pipeline.
  • Uses: Boundary – many fitness functions enforce module boundaries and dependency rules.
  • Enables: Steering Loop – fitness function failures feed into the steering loop, driving agents to self-correct architectural violations.
  • Related: Invariant – a fitness function enforces an architectural invariant: a structural condition that must always hold.
  • Related: Test – tests verify behavioral correctness; fitness functions verify structural correctness. Both run in the same pipeline.
  • Related: Harnessability – a codebase with clear module boundaries and strong types is easier to protect with fitness functions.
  • Related: Garbage Collection – garbage collection sweeps fix drift that accumulates between fitness function checks; fitness functions prevent drift at the commit level.
  • Contrasts with: Feedforward – feedforward controls prevent violations by shaping the agent’s output before it acts; fitness functions detect violations after the fact.

Sources

  • Neal Ford, Rebecca Parsons, and Patrick Kua introduced architecture fitness functions in Building Evolutionary Architectures (O’Reilly, 2017). The second edition (2023, with Pramod Sadalage) expanded the framework to cover automated software governance. The concept borrows the term “fitness function” from evolutionary computation, where it measures how well a candidate solution meets a set of criteria.
  • The O’Reilly Radar article “How Agentic AI Empowers Architecture Governance” (2026) connects fitness functions to the Model Context Protocol (MCP), showing how MCP provides an anticorruption layer that lets architects state governance intent without coupling to implementation details.
  • ThoughtWorks has tracked architectural fitness functions on their Technology Radar since 2017, classifying the technique as “Trial” and later “Adopt.”

Further Reading