ADR-001: Four layers of record, each with a test for what belongs in it
Status Active · Version 2 · Filed 2026-08-03
Context
Half the collaborators on a modern codebase are stateless: they arrive with no memory, read some pages, work, and vanish. Unwritten knowledge is therefore re-derived at cost, per session, forever — the rediscovery tax. The answer this package encodes is that the project is its own memory: the written record isn’t a description of the collaboration, it’s the next collaborator’s mind, reconstituted from disk.
That only works if “where does this go?” has a fast answer. A single NOTES.md
fails not because it can’t hold the content but because nobody can tell what
belongs in it, so the entries that cost the most to re-derive — the failed
approaches — are the ones that never get written.
Decision
Four layers, each with a one-line test.
| layer | holds | test |
|---|---|---|
design-principles.md | standing values, numbered, cited as “DP-2” instead of re-argued | have we re-derived this reasoning more than once? |
decisions/ | a choice among alternatives at a point in time, one file each | did we reject an alternative, or set a constraint a future edit could violate? |
changelog.d/ | what changed, operator-facing, terse | would someone running or using this notice? |
devlog.d/ | how it went, including wrong theories | will a future debugger want the narrative? |
The traffic rules between them matter as much as the split:
-
Principles are durable but not sacred — revised when we learn better, with the reasoning captured where the change lands.
-
A decision whose choice changes is superseded by adding a decision and flipping a status line, rather than by rewriting a body. A record you can quietly rewrite can’t be trusted about what you used to think.
That is a rule about silence, not about editing: a decision whose choice stands but whose reasoning turns out to be wrong is corrected in place, with a
versionbump and ahistory:entry saying what the previous version claimed (ADR-019). Retiring a decision that is still in force, in order to fix a paragraph, makesSupersededstop meaning anything.A decision with an empty “alternatives considered” usually wasn’t a decision.
-
A principle is added on the second re-derivation. One instance is a decision; a pattern is a principle.
-
Fragments are one-file-per-contribution so parallel work never collides (ADR-002).
Alternatives considered
- One document for everything. Simplest to explain, and it fails at the point of use: with no test for what belongs, the cheap entries get written and the expensive ones don’t.
- Infer the narrative from git history. Free, and it captures the wrong thing — commit messages address a reviewer looking at a diff, not a debugger six months later, and the approach you abandoned on Tuesday leaves no commit at all.
- Decisions only (the plain ADR practice). The common baseline, and it has no home for a value that many decisions cite — so the value gets re-argued in each one, which is the cost DP-2 names in a different domain.