DEV Community

Decision Desk
Decision Desk

Posted on

Install a lightweight ADR process in 30 minutes

#leadership #architecture #documentation #softwareengineering

By Decision Desk

Part 2 of a short series. Part 1: Ceremony proportional to irreversibility: Type 1 vs Type 2 engineering decisions

Architecture Decision Records have been around since Michael Nygard's 2011 post "Documenting Architecture Decisions." The idea is simple: when you make a significant technical decision, write a short document that captures the context, the decision, and its consequences, and keep it next to the code.

Most teams agree ADRs are a good idea. Many have a docs/adr/ folder with three records from two years ago. The format is almost never the reason the practice dies. It dies because nobody agreed when to write one, how much to write, or what "accepted" means.

This post is a 30-minute install that answers those three questions. You need a repo (or a wiki), one meeting, and a decision your team is making this week.

Before the meeting (5 minutes, one person)

Pick a home. If your team reviews code in GitHub or GitLab, use docs/adr/ in the main repo. Decisions get reviewed in PRs like everything else, and they're versioned with the code they describe. If most of your design work happens in Notion or Confluence, use one database or parent page there. Pick one location. Two locations means zero.

Pick a naming scheme. NNNN-short-title.md, as in 0001-use-postgres-for-billing-events.md. Numbers only go up and are never reused.

Create a stub. Keep it short. A Type 2 record should fit on one screen:

# ADR-NNNN: [Decision, stated as the outcome]

| Field          | Value                                  |
|----------------|----------------------------------------|
| Status         | Proposed / Accepted / Superseded by ADR-____ |
| Date           | YYYY-MM-DD                             |
| Deciders       | @names                                 |
| Classification | Type 1 / Type 2                        |
| Reviewers      | @names                                 |

## Context
What forces a decision now? 3–6 sentences.

## Decision
We will …

## Alternatives considered
| Option      | Why not (one line) |
|-------------|--------------------|
| Status quo  |                    |
| Alternative |                    |

## Consequences
Good: …  Costs we accept: …  Follow-ups (owner, date): …

## Revisit when
A metric, a dependency change, or a date.
Enter fullscreen mode Exit fullscreen mode

Save it as docs/adr/template.md. If you want a well-known format with more structure, MADR (Markdown Architecture Decision Records) is free and widely used. The exact headings matter much less than what follows.

The meeting (30 minutes, whole team)

Minutes 0–5: agree on the goal

Say it plainly: "Decisions that someone will ask 'why?' about get written down before they turn into folklore. Small, reversible ones get a short record. Big, hard-to-reverse ones get a full one. Trivial ones get nothing."

That last sentence is the one that gets buy-in. People resist ADRs because they picture writing four pages for a library bump.

Minutes 5–12: agree on how to classify

This is the step most ADR rollouts skip, and it's the one that keeps the practice alive. Use a simple rule: ceremony proportional to irreversibility.

  • No record needed: nobody will ask "why?" in six months. The PR description covers it.
  • Type 2 (easy to reverse): can be fully undone within a sprint, with no data migration, contract change, or other team affected. Use the stub, get one reviewer, done the same day.
  • Type 1 (hard to reverse): touches data you can't regenerate, sensitive data, or money; needs a migration or coordinated release to undo; creates a contract others build on; or forces other teams to change if you reverse it. Use the stub plus extra sections (non-goals, alternatives in depth, rollback honesty, operability/security), and get reviewers from every affected team.

Two rules for the edge cases: when unsure, go heavier (you can downgrade after five minutes of discussion). And classify the slice, not the project. A big initiative usually contains one or two Type 1 choices and many Type 2 ones.

Minutes 12–20: classify one live decision

Pick something real that's in flight. Not a hypothetical, and not something from last year. Run through the questions out loud. It should take two or three minutes. If people disagree about the type, that disagreement is useful: it usually means someone knows about a dependency or a data implication that others don't.

Decide: Type 1, Type 2, or no record.

Minutes 20–25: assign it

  • Author: the person closest to the decision, not the most senior person in the room.
  • Reviewer(s): one for Type 2. For Type 1, one per affected team, plus security or data if relevant.
  • Due date: Type 2 this week. Type 1 gets a review window of about 3–5 working days, or 48 hours if the cost of delay is high.

Create an index, either a docs/adr/README.md with a table or a view in your wiki database, and add the first row now: ID, title, status (Proposed), type, author.

Minutes 25–30: agree on three rules

  1. "Accepted" requires the reviewer's OK, and for Type 1, cleared blockers. A Type 1 record isn't accepted until the rollback story is honest (separating "flip the flag" from "migrate the data back"), owners are named for implementation and for revisiting, and data or security impact is addressed.
  2. Never edit an accepted decision's substance. If you change your mind, write a new ADR that supersedes the old one and link them both ways. Fixing typos is fine. Rewriting history isn't.
  3. Link records from where the work happens. Put the ADR link in the PR description, the epic, or the RFC. A record nobody can find from the code is only slightly better than no record.

That's the meeting. The process is installed once the next decision goes through it, not once the template is perfect.

The first four weeks

Week 1: the first record gets written and reviewed. Expect it to be a bit long. That's fine.

Week 2: watch for the "do we need an ADR for this?" question. Answer it with the classification questions, out loud, in the channel. This is how the team learns the boundaries.

Week 3: look at the index. If everything is Type 1, your classification is too cautious, or people are only writing records for big decisions and skipping the Type 2 ones. If everything is Type 2 and records are two lines long, check whether anything irreversible slipped through.

Week 4: scan for records stuck in "Proposed" for more than two weeks. Accept them, reject them, or withdraw them. A decision log full of stale proposals signals that decisions don't really get made here.

Optional upgrades, later

Don't add these on day one. Add them when you feel the gap:

  • CODEOWNERS on docs/adr/ so the right people are auto-requested on ADR PRs.
  • A tradeoff worksheet for Type 1 decisions with several real options: weighted criteria, plus a line for where judgment overrode the scores.
  • A review scorecard for contentious decisions, filled in independently before discussion, to show where reviewers actually disagree.
  • CLI tooling like adr-tools to generate numbered files, if your team likes that.
  • A quarterly skim of accepted Type 1 records against their revisit triggers.

Common ways this goes wrong

  • The architect writes all the records. Then it's a documentation job, not a team practice. Authors should be the people closest to the decision.
  • Records get written after the fact to justify a choice. Some of that is fine, since backfilling a few important past decisions is useful. But if every record is retroactive, the review step is theater.
  • The template grows. Every incident adds a section. Resist it. Keep the Type 2 stub on one screen and put additions in the Type 1 extras.
  • No "no record needed" category. Without it, people either document everything and burn out, or document nothing and feel guilty.

Thirty minutes, one folder, one stub, three rules. The value shows up six months from now, when someone asks "why did we do it this way?" and the answer is a link.

If you'd like the classification step as a printable one-pager, the free Decision Classifier has the 7 yes/no questions, the ceremony for each outcome, a minimal ADR stub, and three worked examples: https://decisiondeskeng.gumroad.com/l/vbowoo

Top comments (0)