Deze documentatie wordt actief uitgebreid — kom regelmatig terug.

ADR-00001: Record architecture decisions

Approval Status

Status flow: Proposed → Accepted → Reviewed → Approved (or Rejected), or Not Required. A superseded ADR keeps its file; only its status changes to Superseded by NNNNN.

Governance body	Status	Last update
CTN Project Team	Approved	2026-05-29
CTN Technical Advisory Board	Approved	2026-07-08
CTN Steering Committee	Not Required	2026-07-08
BDI Conformance Team	Approved	2026-07-08
BDI Framework Team	Not Required	2026-07-08

Context and Problem Statement

Copied and adapted from original Michael Nygard ADR blog post: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.

Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins.

Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team itself can have value, but only if they are kept up to date. Large documents are never kept up to date. Small, modular documents have at least a chance at being updated.

Nobody ever reads large documents, either. Most developers have been on at least one project where the specification document was larger (in bytes) than the total source code size. Those documents are too large to open, read, or update. Bite sized pieces are easier for for all stakeholders to consume.

One of the hardest things to track during the life of a project is the motivation behind certain decisions. A new person coming on to a project may be perplexed, baffled, delighted, or infuriated by some past decision. Without understanding the rationale or consequences, this person has only two choices:

Blindly accept the decision.

This response may be OK, if the decision is still valid. It may not be good, however, if the context has changed and the decision should really be revisited. If the project accumulates too many decisions accepted without understanding, then the development team becomes afraid to change anything and the project collapses under its own weight.

Blindly change it.

Again, this may be OK if the decision needs to be reversed. On the other hand, changing the decision without understanding its motivation or consequences could mean damaging the project’s overall value without realizing it. (E.g., the decision supported a non-functional requirement that hasn’t been tested yet.)

It’s better to avoid either blind acceptance or blind reversal.

Decision Outcome

We will keep a collection of records for “architecturally significant” decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.

An architecture decision record is a short text file in a format similar to an Alexandrian pattern. (Though the decisions themselves are not necessarily patterns, they share the characteristic balancing of forces.) Each record describes a set of forces and a single decision in response to those forces. Note that the decision is the central piece here, so specific forces may appear in multiple ADRs.

We will keep ADRs in the project repository under docs/arc42/09-decisions/NNNNN-active-sentence.md

We should use a lightweight text formatting language like Markdown.

ADRs will be numbered sequentially and monotonically. Numbers will not be reused.

If a decision is reversed, we will keep the old one around, but mark it as superseded. (It’s still relevant to know that it was the decision, but is no longer the decision.)

We will use a format as defined in ADR-TEMPLATE.md. The whole document should be one or two pages long. We will write each ADR as if it is a conversation with a future developer. This requires good writing style, with full sentences organized into paragraphs. Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments. (Bullets kill people, even PowerPoint bullets.)

Rationale

The adoption of Architecture Decision Records (ADRs) is driven by the need for a sustainable and transparent architectural evolution in an agile environment.

Business alignment: ADRs ensure that architectural knowledge is preserved across team changes, protecting the business investment in the software. By documenting the “why” behind decisions, we ensure that future changes are made with a full understanding of the original intent, reducing the risk of costly regressions or architectural drift.
Technical considerations: Keeping ADRs in the project repository using Markdown ensures they are easily accessible to developers, version-controlled alongside the code, and simple to update. The bite-sized, modular nature of ADRs makes them more likely to be read and maintained compared to traditional, large architecture documents.
Risk assessment: Without ADRs, the project faces the risk of “blind acceptance” (stale decisions hindering progress) or “blind reversal” (changing critical components without understanding consequences). ADRs mitigate these risks by providing the necessary context for informed decision-making.
Cost/benefit analysis: While writing ADRs requires an upfront time investment from senior technical staff, the long-term benefits in terms of onboarding speed, architectural consistency, and maintenance efficiency far outweigh these costs. It prevents the “collapse under its own weight” that often occurs when technical debt accumulates due to misunderstood architectural constraints.

Consequences

Positive: One ADR describes one significant decision for a specific project. It should be something that has an effect on how the rest of the project will run. The consequences of one ADR are very likely to become the context for subsequent ADRs. This is also similar to Alexander’s idea of a pattern language: the large-scale responses create spaces for the smaller scale to fit into. Developers and project stakeholders can see the ADRs, even as the team composition changes over time. The motivation behind previous decisions is visible for everyone, present and future. Nobody is left scratching their heads to understand, “What were they thinking?” and the time to change old decisions will be clear from changes in the project’s context.
Negative: As the ADRs become more complex, the consequences and interactions between them become more complex. We’ll cross that bridge when we get there, by merging and re-bootstrapping the resulting adr’s into a coherent architecture document. Also, writing an ADR requires a time investment. We strongly believe this investment offers long-term benefits in terms of project clarity and maintainability.
Neutral:

Implementation Plan

This ADR will be the first. We will bootstrap the project with a few more decisions along the way. Writing and approving ADRs need to be embedded in the way of working.