ADRs as the documentation format
Architecture Decision Records replaced topical docs. Before, there were separate documents for database, deployment, features, workflow, coding standards and release process, and they went stale because nobody knew which one a change belonged in.
How it works
- Numbered files in
docs/adr/ - One decision per file, never edited to reflect a new decision, superseded by a later numbered ADR instead
- New ADRs start as Proposed on
main - Referenced by number in issues and PRs afterwards ("as per ADR 0004")
Examples from SMPW
| Number | Decision |
|---|---|
| 0001 | Trunk-based development |
| 0002 | Feature flags |
| 0004 | Build step |
| 0006 | Where CSS lives |
| 0008 | One directory per feature |
Why it works better
A decision has a date and a reason attached, so later you can tell whether the reason still holds. Topical docs only ever tell you the current state, never why it's that way.
The numbering is portable, any project can start at 0001.