Decision Records
Architecture decision records are a last resort, written only when the repository’s structure, code, tests, and owner documentation cannot make a choice clear.
- Kind
- Convention
- Domain
- Documentation & Metadata
- Applies at
docs/pdlc/decisions/- Status
- Stable
01 Defines
When and how a separate decision record is written: a short, numbered ADR copied from a template, whose “Repository Expression” section points back to the files that make the decision visible in practice.
02 Applies when
- Important context behind a choice cannot be read from the repository’s structure, implementation, or tests.
- A tradeoff or constraint would be lost if it lived only in a pull request or conversation.
- Owner documentation beside the affected files is not enough to explain why.
03 Boundaries
- Conventions a directory, command, or module owns are described there, not in a record.
- Records do not replace tests that enforce a convention through routine change.
- The directory keeps only the template until a record is genuinely needed.
Expected behaviour
- 01A record is a copy of
TEMPLATE.mdnamedADR-NNN-short-title.md. - 02Records stay short and specific.
- 03Every record has a “Repository Expression” section pointing at code, owner documentation, tests, and runtime behaviour.
- 04Status, Context, Decision, and Consequences sections frame the choice and what it makes easier or harder.
Behaviour#
Most decisions in a repository are already written down — in the shape of the tree, in a make module, in a workflow, in a test. A decision record that restates one of those becomes a second source of truth that can drift. So the default is to express a convention where it lives, and to reach for a record only when that is not enough.
- 01
Structure
Directories explain their layout in local
README.mdfiles Owner Documentation - 02
Commands
Makefilemodules, scripts, and workflow files explain behaviour Make Module Registries - 03 Infrastructure Roots and modules document their runtime contract locally Environments
- 04 Tests Architectural conventions that must survive routine change are enforced
- 05 Decision record Only what none of the above can make clear
That is why docs/pdlc/decisions/ is expected to be nearly empty. An empty
directory with a template is the convention working, not a gap.
The template#
The template is deliberately small. Its distinguishing section is Repository Expression: a record has to name the places where its decision is visible, so a reader can check that the repository still agrees with it.
| Section | Answers |
|---|---|
| Status | Proposed, or where the decision now stands |
| Context | What cannot be expressed by structure, code, tests, or owner docs alone |
| Decision | The durable choice being made |
| Repository Expression | Code, owner documentation, tests, and runtime behaviour that show it |
| Consequences | What becomes easier, harder, safer, or intentionally out of scope |
Examples#
# ADR-NNN: Title
## Status
Proposed.
## Repository Expression
Where does the repository make this choice visible in practice?
- Code:
- README or owner documentation:
- Tests or validation:
- Workflow or runtime behavior:
Connections