Marius Margowski

Decision Records for Busy Teams: A Lightweight ADR Workflow

Fast teams forget why they chose things

Most architecture pain does not come from one bad decision. It comes from ten old decisions that nobody can explain anymore.

A new engineer asks, "Why did we choose this queue, this framework, this table shape?" The team opens old pull requests, chat threads, and calendar notes. Nobody finds a clean answer. Work slows down, confidence drops, and we argue about history instead of solving the current problem.

This is where ADRs help. ADR means Architecture Decision Record. It is a short document that captures one important technical decision, why you made it, and what tradeoffs you accepted.

The problem is that many teams make ADRs too heavy. If writing one feels like writing a mini thesis, nobody will keep doing it.

You need a lightweight workflow that fits real delivery pressure.

What an ADR should do, and what it should not do

An ADR should answer five things:

  1. What problem are we deciding on?
  2. What options did we consider?
  3. What did we choose?
  4. Why did we choose it?
  5. What are the consequences?

That is enough. You do not need twenty sections, long prose, or perfect language.

The goal is not documentation theater. The goal is decision memory.

A lightweight ADR workflow that teams actually keep

Use this flow when a decision is expensive to reverse, affects multiple engineers, or changes system boundaries.

Step 1: Write a draft before the meeting

The decision owner writes a draft with one page max. This forces clarity before discussion starts.

Keep the first version simple:

  • context
  • options
  • proposed decision
  • tradeoffs
  • open questions

If there is no decision owner, assign one. Shared ownership often means no ownership.

Step 2: Review asynchronously first

Post the draft in your team channel and link it in the related ticket.

Ask reviewers for concrete feedback:

  • missing option
  • wrong assumption
  • operational risk
  • migration risk

This removes basic confusion before people enter a call.

Step 3: Time box the decision meeting

If comments expose real disagreement, run a short meeting. Thirty minutes is often enough.

Use a simple agenda:

  1. restate the decision question
  2. walk through options quickly
  3. call out highest risk tradeoffs
  4. decide owner and deadline for final call

Do not let the meeting drift into implementation details unless they change the decision itself.

Step 4: Mark status clearly

Each ADR should carry a status:

  • proposed
  • accepted
  • superseded
  • rejected

Status matters more than polish. Engineers need to know whether they should follow it today.

Step 5: Link ADRs to code and tickets

An ADR without links becomes dead text.

For each accepted ADR, link:

  • main pull request or pull requests
  • migration ticket if needed
  • rollback plan if risk is high

Now the record becomes part of delivery, not a side activity.

A practical ADR template

Use this template as a starting point:

# ADR 012: Choose Queue for Email Delivery

## Status
Accepted

## Context
We need reliable email delivery with retries and clear failure visibility.
Current cron based job has duplicate sends and weak observability.

## Options
1. Keep cron with incremental fixes
2. Use BullMQ with Redis
3. Use managed queue service

## Decision
Use BullMQ with Redis for the next phase.

## Why
It gives retries, delayed jobs, and clear worker model with low migration cost.
Managed queue service reduces operations work but adds higher monthly cost today.

## Consequences
Positive:
- Better retry behavior
- Better visibility into failed jobs

Negative:
- Redis becomes a stronger dependency
- Team needs worker operations runbook

## Links
- PR: <link>
- Ticket: <link>
- Monitoring dashboard: <link>

If this feels long, shorten the Context and Why sections. Keep the decision and consequences explicit.

Common failure modes

Failure mode 1: ADRs are written after the fact

This turns records into storytelling, not decision support.

Write the draft before the final call. Even a rough draft is better than memory reconstruction.

Failure mode 2: No one owns updates

Systems change. Decisions expire.

Assign ownership by domain, then review old ADRs on a fixed cadence, for example once each quarter.

Failure mode 3: Everything gets an ADR

Not every technical choice needs formal record keeping.

Use ADRs for high impact choices, such as:

  • data storage strategy
  • service boundaries
  • auth model
  • messaging approach
  • caching policy with user visible risk

Skip ADRs for local refactors, naming choices, or tiny library swaps.

Failure mode 4: The record has no operational view

Many ADRs explain architecture but ignore operations.

Always include consequence notes for support, monitoring, incident response, and migration effort. A decision that works only in development is not a complete decision.

Keep the system lightweight as the team grows

When teams grow, process tends to thicken. Fight that pressure.

You can keep ADRs lightweight with three guardrails:

  1. one page target for first draft
  2. fixed status vocabulary
  3. links to real implementation artifacts

That is enough structure to preserve clarity, and enough flexibility to keep momentum.

What to do this week

Pick one recent decision your team still debates, write a one page ADR draft, and run the five step workflow above.

If the next engineer can answer "why did we do this?" in under two minutes, your workflow is working.