Architecture Decision Records¶
ADRs are short, immutable records of significant decisions. They explain why we built things the way we did. When a decision changes, a new ADR is written that supersedes the older one — the old ADR is not deleted.
How to write one¶
- Copy
_template.md(when it exists) toXXXX-short-title.md - Use the next available 4-digit number, zero-padded
- Fill in: Status, Date, Decision-maker, Context, Decision, Consequences
- Open an MR — get one approval from a project maintainer
- Once merged, the ADR is immutable. To change a decision, write a new ADR that supersedes it.
Index¶
| # | Title | Status |
|---|---|---|
| 0001 | No public cloud, no GitHub | Accepted |
| 0002 | Docs-as-code with MkDocs Material | Accepted |
| 0003 | OpenClaw permanently rejected | Accepted (Final) |
| 0004 | Paperclip skill gateway as runtime | Accepted |
| 0005 | Wagtail for Gamine CMS | Accepted |
| 0007 | Apache AGE as property graph layer | Accepted |
| 0008 | Six Eyes as content quality gate | Accepted |
What belongs in an ADR¶
- Why we chose one approach over alternatives
- Constraints that drove the decision
- What this commits us to or rules out
What does not belong in an ADR¶
- Status of an implementation in progress (use Vikunja)
- A description of how something works (use the relevant doc)
- A complaint about a tool we are still using (open a Vikunja ticket)