Skip to main content

ADR Template

Use this template when proposing a new architecture decision. Copy it to docs/adr/NNN-<slug>.md, fill in every section, and open a PR.

Template​

# ADR NNN: <Title>

- **Status**: Proposed | Accepted | Deprecated | Superseded
- **Date**: YYYY-MM-DD
- **Deciders**: <list>

## Context

<!-- Why is this decision needed? What forces are at play?
     Describe the situation that motivates this decision.
     Include technical constraints, business requirements,
     and any relevant prior decisions. -->

## Decision

<!-- What was decided? Be specific and concrete.
     State the decision in active voice:
     "We will use X for Y because Z." -->

## Consequences

### Positive

<!-- What improves as a result of this decision? -->

### Negative

<!-- What trade-offs are accepted? What becomes harder? -->

### Neutral

<!-- What changes that is neither positive nor negative?
     Side effects, migrations, or shifts in responsibility. -->

Guidelines​

  • Title: Use a clear, noun-phrase title — e.g., "Monorepo with Nx Orchestration", not "Should we use a monorepo?"
  • Status lifecycle: Proposed → Accepted (on merge) → optionally Superseded by ADR-NNN or Deprecated
  • Context: Write enough that someone unfamiliar with the project understands why the decision was needed
  • Decision: State what was decided, not what was considered — alternatives belong in the Context section
  • Consequences: Be honest about trade-offs; every decision has negative consequences
  • Numbering: Sequential, zero-padded to 3 digits (001, 002, …)
  • File naming: docs/adr/NNN-<slug>.md where <slug> is a kebab-case summary

See Also​