Decision Record Testing
Use when asked to verify that a codebase actually reflects a recorded architectural decision (an ADR/DR) — reviewing a decision record for testability, or checking code/CI for drift from a decision already made — as distinct from writing the decision record itself (see architecture-decision-record, decision-records).
Decision record testing is the practice of verifying that a codebase actually conforms to the decisions captured in its Architecture Decision Records (ADRs) or Decision Records (DRs) — closing the gap between "we decided X" (a written document) and "the system actually does X" (an enforced, checkable fact). See Architecture Decision Record and Decision Records for writing the records themselves; this skill is about checking the codebase stays consistent with what's written.
Why a decision record needs a testable claim
A decision record's "Decision" and "Consequences" sections are only useful going forward if they can actually be checked against the system later — "we will use PostgreSQL, not MySQL" is checkable (grep for a MySQL driver import); "we will keep the architecture clean" is not. When authoring a decision record with this skill in mind, phrase the decision as something a later reader (or an automated check) could concretely verify, the same discipline Specification Driven Development applies to writing any spec.
Ways to check conformance
- Static checks / linters — a rule forbidding a specific import, dependency, or pattern the decision record ruled out (e.g. banning a second HTTP client library after a decision record standardized on one).
- Architecture fitness functions — see Fitness Function Testing for automated, ongoing checks that a codebase's structure keeps matching an architectural intent, which is the same underlying idea applied continuously rather than as a one-off review.
- CI-integrated policy checks — a decision like "all new services expose a health-check endpoint" can be checked automatically against every new service definition, catching drift the moment it's introduced rather than at the next architecture review.
- Periodic manual review — for decisions too nuanced to check mechanically (e.g. a decision about tone in error messages), a scheduled human review against the recorded decision, rather than relying on it never being revisited.
Handling superseded decisions
When a decision record is superseded by a newer one, any automated check built for the old decision needs to be updated or removed at the same time — a stale enforcement rule for a decision that's no longer current actively blocks legitimate work, which is worse than having no check at all.
Common pitfalls
- A decision record with no checkable claim — if nobody can tell from the codebase alone whether the decision is still being followed, drift goes unnoticed indefinitely.
- An automated check that outlives the decision it enforced — a linter rule left in place after the decision was superseded turns into an unexplained obstacle for the next contributor.
- Assuming a decision record is self-enforcing — writing it down changes nothing on its own; only an actual review or automated check closes the loop between decision and reality.
Learn more
- Architecture Decision Record, Decision Records for writing the decision record itself.
- Fitness Function Testing for the broader discipline of continuously checking architecture against intent.
- Specification Driven Development for the general principle of keeping written intent and actual behavior reconciled.