The compact definitionAn architecture test is an executable constraint over the structure or dependency graph of a codebase.
Why diagrams and conventions drift
A diagram can explain the intended shape of a system, but it usually cannot react when a new import bypasses a layer. A convention in a wiki has the same problem: it depends on every contributor remembering it at the right moment.
Architecture tests do not replace diagrams or review. They give both a feedback loop. The rule runs where the change happens and points to concrete evidence when the implementation and the decision disagree.
What is worth testing
Dependency direction
Keep domain logic independent from delivery and persistence details. Prevent feature modules from reaching into each other. Define the small set of public seams through which layers may collaborate.
Cycles
Cycles turn local changes into coordinated changes. Detecting them early keeps ownership, build behavior, and refactoring paths easier to reason about.
Structure and naming
Location and naming rules are useful when they communicate an architectural role — for example, adapters that must live behind a port or handlers that must use a recognizable suffix.
Metrics and diagrams
Coupling, cohesion, size, and distance metrics reveal pressure before a binary rule is violated. Diagram conformance checks keep a deliberately drawn system map connected to the dependency graph that actually ships.
How to introduce architecture tests
Choose one costly boundary
Start where accidental coupling has caused real review, delivery, or ownership pain.
Make the scope explicit
Use selectors that fail when they match nothing, so a green test cannot hide a typo.
Baseline honestly
When legacy violations exist, record them and block new debt instead of pretending.
Run in the normal suite
Keep feedback local, fast, and visible in the same CI signals the team already trusts.
Architecture tests and coding agents
Coding agents can move quickly across a repository, which makes machine-checkable boundaries especially valuable. A precise test failure gives an agent the same grounded feedback it gives a human: the rule, the offending edge, and the code that must change.
Reports extend the loop. A dependency graph can become a pull-request artifact, a Mermaid diagram, structured JSON for tooling, or a standalone HTML page for architectural review.
Keep the rules humane
- Test decisions with a real cost of violation, not personal formatting preferences.
- Attach a rationale so future maintainers know why the boundary exists.
- Prefer a small, legible rule vocabulary over a clever internal DSL.
- Treat a rule change as an architecture decision, not a way to make CI green.
- Delete constraints that no longer reflect the system you intend to build.
The resultArchitecture becomes a living part of delivery: documented in code, exercised on every change, and open to deliberate evolution.