Architecture Decision Records (ADRs)
Lightweight log of architectural decisions made for this project. One file per decision.
When to write an ADR
Write an ADR when a decision:
- Affects more than one component or crosses a public surface
- Has plausible alternatives that were considered and rejected
- Will be hard to reverse later, or whose reversal would be visibly disruptive
- Was contested during grooming and the team converged on one path
Skip an ADR when:
- The decision is local to a single file or function
- The choice is mechanical / has no real alternative
- It’s a planning / scope decision (those belong in tickets and milestone docs)
Structure
Files are numbered sequentially: 0001-<short-kebab-name>.md, 0002-..., etc. Numbers are permanent — superseded ADRs keep their number and gain a header note pointing at the superseder.
Use the template when starting a new ADR.
Lifecycle
| Status | Meaning |
|---|---|
| Proposed | Drafted; not yet accepted by the team |
| Accepted | Adopted; reflected in code |
| Superseded by ADR-NNNN | Replaced — keep the file, link forward |
| Deprecated | No longer relevant, but kept for history |
How to reference
Code comments do NOT cite ADR numbers (per feedback_code_comments_no_planning_refs — code describes current state). Tickets, milestone docs, and architecture docs SHOULD cite ADRs by number when describing the decision’s rationale.
Index
| # | Title | Status |
|---|---|---|
| 0001 | srv-isolation exposure model: union-mount at /srv over auto-mount under /dev/container/exports/ | Proposed |
| 0002 | synthetic-fileserver stat semantics: qid identity = lifetime id (not path); nlink = 2 + subdir_count | Proposed |