adr.crastinating.pro
Lightweight3 sections · ~100–200 words

ADR-Lite

Common community variant

Three fields: Decision, Why, Consequences. The smallest format that still captures the *why* — the field every team is tempted to skip.

Use it when

  • Your team is just starting an ADR practice and any friction will kill it.
  • Every decision in your repo has the same shape and you want a one-page form.
  • You want to inline ADRs in PR descriptions without making the PR feel bureaucratic.

Avoid when

  • Decisions that need to compare options — there's no slot for them.
  • Decisions with non-trivial context that future readers will need.

Strengths

  • Almost no ceremony. Adopters typically write 3× more ADRs in the first quarter than Nygard adopters.
  • Fits in a single PR description block.
  • The Why field, when honestly filled, often reveals that the decision is wrong before it ships.

Weaknesses

  • No alternatives section — reviewers can't push back on what was rejected.
  • No status lifecycle, so superseding an ADR-Lite is informal.
  • Tempting to drift into 'because the team agreed' for the Why, which is empty.

Sections

3 required · 0 optional

Minimum viable structure. The format that survives daily use.

  1. 01

    Decision

    Required

    What we will do. Active voice. One sentence, two if you must.

    We will use Biome (not Prettier + ESLint) as the linter and formatter.
  2. 02

    Why

    Required

    The decisive reason. Not three reasons — the *one* reason that, if it changed, would change the decision. The team's nuance lives here.

    Single-binary install + single config file removes one onboarding step and one pre-commit failure mode. The marginal capability gap to ESLint hasn't bitten us in 6 months of evaluation.
  3. 03

    Consequences

    Required

    What we'll have to live with. Both the wins and the costs.

    We give up some niche ESLint plugins (no React Compiler check yet, no Storybook lint). We're betting Biome closes those gaps before we miss them.

Worked example

A real ADR written in the Lite format. Copy the markdown and adapt it.

ADR-Lite: Use Biome as the toolchain

Status: Accepted (2026-04-21)

Decision

We will use Biome 1.9 (not Prettier + ESLint) as the linter and formatter across all packages in the monorepo.

Why

Single-binary install + single config file removes one onboarding step and one pre-commit failure mode. The marginal capability gap to the ESLint plugin ecosystem hasn't bitten us in 6 months of evaluation against the existing codebase.

Consequences

We give up some niche ESLint plugins — no React Compiler lint, no Storybook-specific rules — until Biome closes those gaps. We're betting that happens before we feel the absence.

Field of application

Honest accounts of where this template was the right shape — and where it wasn't.

Tags:lightweightstarterminimal