Skip to content

ADR Log

Intent

Make design rationale discoverable and reviewable so that future team members understand why constraints exist, not just what they are. ADRs create an auditable trail of decisions that supports governance and prevents decision debt.

Behavior

ADR Workflow

The ADR workflow captures decisions from initial issue through acceptance and profile linkage. Each ADR follows a standard template (MADR) that ensures consistent structure: context, decision drivers, options considered, outcome, and consequences.

ADR workflow from issue to accepted decision with profile linkage

Implementation Considerations

Structure

  • Maintain docs/adr/NNNN-title.md using MADR template
  • Index in docs/adr/index.md with status (proposed, accepted, superseded)
  • Link from profiles to relevant ADRs

Templates

Templates
# {number}. {title}

* Status: {proposed|accepted|superseded}
* Deciders: ...
* Date: 2026-01-15

## Context and Problem Statement

## Decision Drivers

## Considered Options

## Decision Outcome

### Consequences

### Links

Benefits

  • Shared memory
  • Easier governance

Trade-offs

  • Up-front writing discipline