Fitness Functions: Checking Selected Architecture Properties
Fitness functions make selected properties such as coupling, dependencies and latency continuously checkable. They don’t replace domain quality or architectural trade-offs.
A fitness function is not a complete quality model. It evaluates one specific architecture property that can be operationalized – such as freedom from cycles, coupling, latency or compatibility between two services. In this post, I focus on automated checks that are as unambiguous as possible and deliver a narrowly scoped verdict on every commit. Properties such as understandability or domain appropriateness still need human judgment.
How big the difference from common practice is shows in a sentence that comes up regularly in architecture reviews: “Of course the domain must not access the infrastructure.” Everyone nods. A diagram gets drawn, maybe a Confluence entry created. Three sprints later, an import statement points from the domain layer straight into the database adapter. No one did it maliciously. It was Friday afternoon, the bugfix had to go out, and the rule simply wasn’t in the code but in meeting minutes that no one reads anymore. Where an architecture property can be checked unambiguously, an automatic check is more reliable than memory in a review.
A fitness function closes the path from a desired property to a repeatable decision.
From architecture statement to gate
- Property · name an architecture quality that matters to the domain
- Observation · pick a reproducible signal for it
- Threshold · explicitly define the range that is still acceptable
- Check · evaluate the signal automatically and repeatably
- Gate · make a violation visible or let the change pass
- Adjustment · re-examine property and threshold when conditions change
The order preserves the domain reason for the measurement. An existing tool alone doesn’t define a meaningful fitness function.
From wish to mechanical check#
The term comes from Building Evolutionary Architectures by Neal Ford, Rebecca Parsons and Patrick Kua (O’Reilly, 2017), borrowed from evolutionary computing, where a fitness function measures how close a solution is to the goal. Applied to software, this means: an architectural fitness function is an objective, mechanical integrity test for one or more architectural characteristics – that is, for the properties that used to be called, somewhat clumsily, “-ilities”: performance, scalability, coupling, security.
The change of perspective that makes the difference in practice is this: architecture is no longer treated as a state you decide on once, but as a property you maintain continuously. That sounds like a nuance, but it’s a break in the way of working. A diagram describes what the system should look like. A fitness function describes what it must look like – and breaks the build if it doesn’t.
This moves part of governance from the meeting into the pipeline. The rules that can be automated run along with every commit; reviews remain necessary where trade-offs, context and domain appropriateness matter. The gain is above all early feedback: an explicitly agreed rule doesn’t depend on whether it gets noticed again in the next review. If you have ever seen a single creeping coupling violation block a refactoring for months, you know the price of after-the-fact control.
The first fitness function is a unit test#
Getting started is unspectacular, and that’s the good news. The simplest category is static, atomic fitness functions – rules about the structure of the code that can be expressed as a completely normal test. In the Java world, ArchUnit by TNG has become established for this; it checks package and layer dependencies through bytecode analysis. For .NET there is NetArchTest, in the JavaScript world dependency-cruiser. The principle is the same everywhere.
The rule invoked at the beginning – the domain knows no infrastructure – looks like this as a fitness function:
@ArchTest
static final ArchRule domain_must_not_depend_on_infrastructure =
noClasses().that().resideInAPackage("..domain..")
.should().dependOnClassesThat().resideInAPackage("..infrastructure..");
@ArchTest
static final ArchRule no_cyclic_dependencies =
slices().matching("..(*)..").should().beFreeOfCycles();
The nice thing about it: this rule documents itself. It lives in the repository, it runs in CI, and it’s not negotiable without someone visibly changing it. The Confluence entry from above describes an intention. The test makes the same chosen rule executable and its violation visible.
The second block – no_cyclic_dependencies – addresses a classic that is notoriously hard to spot in reviews. Cyclic dependencies rarely arise in one big step. They grow out of many small imports, each harmless on its own. A human no longer sees the cycle in the diagram when it runs across seven modules. The machine does. Exactly such properties – afferent/efferent coupling, instability, freedom from cycles – are the ideal case for static fitness functions, because they are deterministic and cheap to check.
More than a list of tools#
If you only think of ArchUnit when you hear fitness functions, you underestimate the reach of the concept. Ford, Parsons and Kua propose a taxonomy that works well as a sorting aid because it suggests the right type of test for each property. Two axes are enough to start with:
quadrantChart
title Classifying fitness functions
x-axis "atomic (one characteristic)" --> "holistic (interplay)"
y-axis "triggered (on demand)" --> "continuous (ongoing)"
quadrant-1 "Latency/load tests in prod"
quadrant-2 "Chaos/resilience checks"
quadrant-3 "ArchUnit dependency rules"
quadrant-4 "Security scan per commit"Atomic measures a single property in isolation, holistic checks the interplay of several – such as security and latency together under load. Triggered runs on demand, for example in the build; continuous runs permanently against the production system. On top of that, the book adds further dimensions: static versus dynamic, automated versus manual, and temporal fitness functions, which deliberately apply only for a limited time – for example a reminder to finish a library migration by a deadline.
The practical value of this classification doesn’t lie in classifying for its own sake. It lies in forcing a question you would otherwise dodge: which concrete architectural characteristic is this check actually tied to? If you can’t answer that, you’re probably building a vanity metric right now.
When the property is dynamic#
Not everything can be checked statically. Latency, for example, is not a property of the source code but of the running system. This is where dynamic fitness functions come in, which measure against a deployment. Conceptually it stays the same – a threshold, a comparison, a verdict:
def latency_fitness(service):
p95 = measure_p95_ms(service, window="5m")
assert p95 < LATENCY_BUDGET_MS, f"p95 {p95} exceeds budget"
As clean as this looks, it’s just as dangerous to hang this assert blindly into CI as a hard gate. Latency values fluctuate. A p95 over a five-minute window can break because of a single garbage collection peak or a slow neighbor in the cluster without anything in your software having changed. If you ignore that, you produce flaky builds – and a flaky gate gets clicked away or commented out within two weeks. Then you have the friction of the check but no longer its benefit.
The pragmatic answer is a separation: static, deterministic properties may block the build. Dynamic, statistically fluctuating properties run as observing, triggered checks with statistical windows and raise alerts instead of breaking hard. The same idea, two operating modes – depending on how deterministic the measured characteristic is.
For resilience-related properties, it’s worth looking into Michael Nygard’s Release It!. The stability patterns described there – Circuit Breaker, Bulkhead, Timeout – provide not only building blocks for robust systems but also checkable expectations: does the circuit breaker open as intended under simulated overload? That is a fitness function too, just a dynamic one.
Measuring coupling between services#
The most interesting coupling in distributed systems doesn’t run within one deployable but between them. Two teams, two services, one contract – and the silent assumption that the other side won’t break its API. Consumer-driven contract testing makes this assumption checkable. With Pact and a Pact Broker, the consumer describes its expectation of the provider, and the provider verifies against exactly this expectation.
As a fitness function, this lands directly as a step in the deployment pipeline:
pact-broker can-i-deploy \
--pacticipant Checkout \
--version "$GIT_SHA" \
--to-environment production
The question “can I deploy this without breaking a consumer?” thus turns from a gut decision into a mechanical answer. The assumption of staying compatible becomes evidence – coupling as governance-as-code. In practice, this is often the moment when teams can really deploy independently for the first time, because the fear of an unnoticed break has been taken out of the process.
The place where everything comes together#
A loose collection of rules has little effect. Fitness functions only become effective as a gate in delivery. The deployment pipeline – conceptually established since Humble and Farley – is the natural place for this. Between build and deploy lies a barrier that checks several categories in parallel:
flowchart LR
commit["commit"] --> build["build"]
build --> gate{"Fitness<br/>Functions<br/>Gate"}
gate -->|static / atomic| s["Dependency & Cycle Rules"]
gate -->|dynamic / holistic| d["Latency p95 & Load"]
gate -->|contract| c["Pact can-i-deploy"]
s -->|fail = break build| commit
d -->|fail = break build| commit
c -->|fail = break build| commit
gate -->|all green| deploy["deploy"]The red return arrows are the core of the idea: a violation doesn’t lead to a ticket that gets prioritized at some point, but to a broken build that is fixed by whoever caused it – immediately, with full context, before the error sinks into the history. This is the same mechanism that makes continuous integration effective, applied to architecture properties.
And this is where the circle closes to measurable delivery quality. Accelerate by Forsgren, Humble and Kim and the DORA Four Key Metrics – Deployment Frequency, Lead Time for Changes, Change Failure Rate, Time to Restore – provide metrics for the delivery level. Fitness functions can check matching technical guardrails for them. A violated coupling rule is then noticed early; whether that lowers lead time or failure rate is something the team has to verify against its own data.
Where it tips over in practice#
As convincing as the concept is, its naive implementation fails reliably in three places – and I’ve seen all of them in projects.
First, the vanity metric. A green fitness function that checks a pure test coverage threshold feels like safety and yet measures nothing architectural. Coverage says how much code is executed, not whether the dependencies are right. Every function has to be tied to a concrete architectural characteristic; otherwise it’s theater.
Second, the maintenance burden. Fitness functions are code and age like code. I’ve seen codebases in which every second rule carried an @ArchIgnore, because under deadline pressure it was faster to add the exception than to solve the problem. Without ownership and regular cleanup of the exception list, the meaningfulness erodes until only green noise remains. These rules need the same care as production code – otherwise they are worse than nothing, because they create false safety.
Third, starting too late. If you unleash fitness functions on a grown legacy codebase, you get thousands of violations on the first run – and guaranteed frustration. The way out is a baseline: you freeze the current state, declare fitness from now on and only allow improvement, no deterioration. “Declare fitness from now on” is not a betrayal of purity. In grown systems, it’s the only way something like this gets started at all.
Conclusion#
The common thread of these three building blocks – static rules, dynamic measurements, contract checks – is a single idea: architecture is a property you maintain, not a decision you make once. Fitness functions shift control from the review into the pipeline, and with it from hope to certainty.
The gain is rarely the individual rule. It lies in the changed way of working. Teams that secure their most important architecture properties mechanically no longer discuss import directions in reviews, but the domain. They deploy more often because the silent fear of an unnoticed break has been taken out of the process. And they refactor more boldly because a net of green checks reports immediately when a restructuring violates a property.
The start may be small: a single atomic, static rule that secures a property you really care about. A dependency rule that breaks the build is worth more than twenty rules in a document no one reads. The rest grows from there – as plain code that runs with every build and forces no extra process on anyone.
Further reading#
- Neal Ford, Rebecca Parsons, Patrick Kua: Building Evolutionary Architectures (O’Reilly, 2017) – chapter on fitness functions
- ArchUnit (TNG) – static architecture tests for Java
- Nicole Forsgren, Jez Humble, Gene Kim: Accelerate (2018) and the DORA Four Key Metrics – martinfowler.com: StateOfDevOpsReport
- Michael Nygard: Release It! (2nd edition, 2018) – stability patterns for resilience-related fitness functions
- Pact – consumer-driven contract testing with
can-i-deploy
Revised and translated from German with the help of AI.