Architecture Decision Records
An ADR captures a single architectural decision — what was chosen, why, what was rejected, and the consequences. It is small, immutable, and reviewable. The point of writing one is to preserve the reasoning, not just the conclusion.
When to write one
Write an ADR when a decision is:
- Architectural — it shapes the structure, not just the surface, of the system.
- Hard to reverse — backing it out later costs more than getting it right now.
- Non-obvious — a future reader might reasonably ask "why this and not the alternative?"
Examples that warrant an ADR:
- Picking a database engine, ORM, or persistence strategy.
- Choosing a synchronous vs. asynchronous integration pattern.
- Adopting a new framework, language, or runtime.
- Replacing an existing subsystem.
- Establishing a project-wide invariant ("we always X" or "we never Y").
Examples that don't warrant an ADR:
- Renaming a variable. Picking a colour. Choosing between two equivalent libraries with no meaningful trade-off.
- Tactical implementation details that fit comfortably inside a single task.
If a reviewer would reasonably ask "why" six months from now, write the ADR. If they wouldn't, don't.
The Synthex convention
ADRs live in docs/specs/decisions/ (configurable via architecture.decisions_path). Each ADR
is a numbered markdown file: 0001-use-postgres.md, 0002-monorepo-layout.md, and so on. The
template Synthex uses:
# ADR-NNNN: Short noun-phrase title
**Status:** Proposed | Accepted | Superseded by ADR-MMMM
**Date:** 2026-MM-DD
**Author:** Name (or Architect agent)
## Context
What problem are we solving? What constraints apply? What did we know at the time?
## Decision
What did we choose? State it clearly enough that someone reading this in two years
can act on it.
## Alternatives considered
Each option that was on the table, with the trade-off that ruled it out.
## Consequences
What does this commit us to? What becomes easier, harder, more expensive,
or constrained?
## References
Links to RFCs, specs, related ADRs, external resources.The structure is deliberately small. ADRs that grow into essays signal that the decision should be split into multiple ADRs.
Status values
- Proposed — the decision is captured but not yet approved by the team.
- Accepted — the decision is in force; reviewers may cite it.
- Superseded by ADR-MMMM — the decision was reversed or replaced. The original ADR is preserved unchanged; the new ADR explains why.
ADRs are append-only. You don't edit accepted ADRs to "fix" them — you write a new one that supersedes the old, and the chain of decisions becomes the audit trail.
Authoring with the Architect agent
write-adr/synthex:write-adr launches the Architect agent in interview mode. The agent
prompts for context, decision, alternatives, and consequences, drafts the ADR, and saves it at
the next available number under architecture.decisions_path.
The Architect's prompts are designed to surface assumptions: what evidence supports the decision, what would change your mind, what's the smallest reversible step. If you can't answer those questions, the ADR isn't ready.
ADRs vs. specs vs. RFCs
The trio:
- An RFC is a proposal — an open question seeking discussion.
- An ADR is a decision — a closed question with a recorded outcome.
- A spec is a rule — the constraint the decision established.
A proposal lives in an RFC, gets accepted, becomes an ADR, and the rule it created lands in a spec. Reviewers enforce the spec; the ADR is consulted when someone asks why the spec is the way it is.
Maintenance
ADRs require almost no maintenance once written. The maintenance happens through superseding, not editing. Periodic plan retros can surface ADRs that are quietly being violated — a signal the team has drifted and either needs to recommit or write the superseding ADR explicitly.