Topic: ADR team-size scaling

ADR Template for Squad-Sized Teams — Scaling the Practice from 3 to 50+ Engineers

The standard Nygard ADR template was designed for one context: a senior individual contributor writing up a completed decision they made alone or with one or two colleagues. At three people, the template has too many fields — the ceremony exceeds the value. At fifty people with multiple squads and an architecture board, the same template has too few — it cannot capture cross-team scope, stakeholder sign-off, or the RFC thread that preceded the decision. This page covers the minimum viable ADR template for each team size, which fields are never optional regardless of scale, and what governance ceremony (if any) adds value at each step.

TL;DR

Three fields are never optional at any scale: Title (what was decided, not what the problem is), Decision (one sentence saying exactly what you chose), and Consequences (what gets harder and what gets easier). Context shrinks to one sentence at small scale; Stakeholders and Alternatives become meaningful only when you have cross-team scope. Add ceremony exactly one step before the lack of it causes a problem — not earlier.

Why the same template fails at different scales

The Nygard template was defined in a blog post written by a consultant helping large enterprises adopt a documentation habit they did not have. The intended audience was engineers at organizations where decisions were being made informally across teams and the consequences were appearing months later in a different service. The template was deliberately verbose to force the author to slow down and explain context that colleagues in other departments would need.

Applied to a three-person startup, the same template produces documents that nobody reads because they require ten minutes to write and capture information that all three people already know. Applied to a 50-person engineering org without modification, it omits the RFC process, the architecture board review, and the cross-team stakeholder list — the fields that matter most at that scale.

The right response is not to abandon the practice but to scale the template to the ceremony level the team actually needs. The following templates are minimal — use the smallest one that produces a useful record. Add fields when a missing field has already caused a problem, not in anticipation of a problem.

The 3-person startup template

At three people, everyone was probably in the same conversation when the decision was made. The primary audience for the ADR is your future self — twelve months from now, at 15 people, when you are onboarding engineers who were not in the room. Write to that reader.

# ADR-0001: [What was decided — name the choice, not the problem]

**Status:** Accepted
**Date:** 2026-01-15

## Decision
[One sentence. "We chose X over Y." or "We will use X for Z."]

## Consequences
- Makes harder: [one thing]
- Makes easier: [one thing]

That is the full template for a three-person team. Context is omitted because it is obvious; if it is not obvious, add one sentence. Alternatives are omitted because the author considered them during the decision — they belong in the Decision field as a parenthetical ("chose X over Y and Z because Y lacked feature F and Z cost 3× more"). Status is always Accepted (you do not write ADRs for Proposed decisions at this scale — write them when the decision is made).

The most important discipline at this scale: write the ADR on the day of the decision, not two weeks later. Two weeks later, the Context is already wrong, the Alternatives are forgotten, and the author is writing a rationalization rather than a record. One hour on the day is worth two hours two weeks later.

Do not worry about tooling. A doc/decisions/ folder with one file per decision is sufficient. Auto-numbering, TOC generation, and web publishing are problems for a later scale. At three people, the cost of adopting tooling exceeds the benefit for the first 12 months.

The 10-person squad template

At ten people, you have engineers who were not in the room when a decision was made. The ADR now needs to carry enough context for someone who joined after the decision to understand not just what was decided but why the alternatives were insufficient. A two-sentence Context section and a one-paragraph Consequences section replace the one-liner versions from the three-person template.

# ADR-0042: [What was decided]

**Status:** Accepted
**Date:** 2026-03-10
**Decider(s):** [Name or initials — one or two people]

## Context
[Two to four sentences. What was the situation that made this decision necessary?
What constraints existed? What was the alternative-space? Keep it to what a new
engineer needs to understand why this decision was not obvious.]

## Decision
[One to three sentences. What was chosen and what was the primary reason?
If alternatives were considered, name them here and state the deciding factor.]

## Consequences
[Three to five bullet points. Split into "makes harder" and "makes easier" if
useful, or list as a flat set of trade-offs. Be honest about the downsides —
this section is where future engineers learn whether the decision is holding up.]

## Status history
- 2026-03-10: Accepted by [name]

The Decider(s) field is added at this scale for one reason: when the decision is later questioned, knowing who made it clarifies whether to ask them for context or to accept that they have moved on. It is not a blame field — it is a routing field for questions.

The Status history becomes useful at 10+ people because ADRs start to live long enough to need updating. When the status changes from Accepted to Superseded, the history records when the original decision was in force. The update protocol and supersession pattern become relevant at this scale — two-file atomic supersession (old ADR → Superseded, new ADR → Accepted, both in the same PR) is the right practice to adopt now, before the first supersession creates a broken-pointer problem.

Tooling is worth adopting at this scale. A simple GitHub Action that validates new ADRs on PRs — checking that the file is numbered, that Status is one of the allowed values, and that any Superseded-by pointer resolves to a real file — eliminates the most common consistency errors before they accumulate.

The 50-person platform org template

At fifty engineers across multiple squads, decisions come in two distinct categories: squad-level decisions (apply within one service or team) and platform-level decisions (apply across squads, constrain what other teams can do). The squad-level template is identical to the 10-person template above. Platform-level decisions need additional fields.

# ADR-0099: [What was decided — platform scope]

**Status:** Accepted
**Date:** 2026-05-01
**Decider(s):** [Primary decision-maker(s)]
**Stakeholders:** [Teams or roles that were consulted or are affected]
**RFC:** [Link to RFC thread or design doc, if the decision followed a proposal]
**Scope:** Platform — applies to all services using [system/layer]

## Context
[Three to six sentences. Explain the situation for an engineer in a different
squad who was not in any of the RFC discussions. Include the constraint that
made this decision necessary — a scaling limit, a compliance requirement, a
team boundary — because that constraint is what future engineers need to know
when asking "can we revisit this?"]

## Decision
[One to three sentences. Be specific about scope: "All new services MUST use X
for Y" is more useful than "We chose X for Y." The word MUST, SHOULD, or MAY
(RFC 2119 language) removes ambiguity about whether this is a mandate or a
default.]

## Alternatives considered
| Alternative | Why rejected |
|---|---|
| Option A | [one sentence] |
| Option B | [one sentence] |

## Consequences
[Five to eight bullet points covering: what teams must change, what becomes
easier, what becomes harder, and what new risk is introduced. Include any
migration path for existing services that are out of compliance.]

## Review date
[Date when this decision should be re-evaluated if circumstances change —
a scaling limit, a vendor end-of-life, a compliance review cycle.]

## Status history
- 2026-04-15: Proposed — RFC-0034 opened for comment
- 2026-04-29: RFC-0034 closed, no blocking objections
- 2026-05-01: Accepted by [architecture board or named leads]

The Stakeholders field at platform scope is not cosmetic. It records which teams were consulted before the decision was made — the audit trail that proves a team cannot later say "we were never told." Consultation does not mean consensus; the decision-maker is still named in Decider(s). But an unconsuled affected team is a political problem that shows up six months later as resistance to adoption.

The Alternatives considered table forces the author to document not just what was chosen but why the other options were insufficient. At squad scale, this is optional because the context is still fresh. At platform scale, it is mandatory because the team that loses the argument (whose preferred option is in the "why rejected" column) will revisit the question at the next opportunity. Having the rejection rationale in writing shortens that conversation from an hour to five minutes.

The RFC field links the ADR to its upstream proposal. Platform-level decisions almost always follow an RFC (request for comment) process where a proposal is posted, teams review it over one to two weeks, and the decision-maker closes the RFC with a verdict. The RFC-to-ADR handoff documents this relationship: the RFC is the deliberation record; the ADR is the decision record. Both are needed. Deleting the RFC after writing the ADR loses the evidence that explains why the Context section reads the way it does.

What scales automatically vs what requires a deliberate choice

Two things scale automatically as the team grows: the number of ADRs (more decisions are made) and the age of the oldest ADRs (they live longer). The consequences of poor practices compound with both — a stale ADR in a three-person team is an annoyance; a stale ADR referenced by three other ADRs in a 50-person org is a systemic problem.

Four things do NOT scale automatically and require deliberate adoption at a specific team size threshold:

Repository location. At three people, a single doc/decisions/ in the main repo is sufficient. At ten people with multiple services, you must decide whether ADRs live per-service (in each repo) or in a central decisions repo. At fifty people with platform decisions, a central repo for platform ADRs alongside per-service repos for squad ADRs is the common pattern. The choice is not reversible without breaking all Superseded-by pointers, so make it consciously before it makes itself.
Status lifecycle governance. Who can change an ADR from Proposed to Accepted? At three people, the author. At ten people, typically the author + one senior reviewer on the PR. At fifty people with platform scope, the architecture board or a defined set of principal engineers. If the governance is not defined, it defaults to the author — which means platform decisions can be accepted without cross-team awareness.
Review cadence. ADRs accumulate technical debt of their own: decisions that are no longer operative, pointers that resolve to archived files, status fields that say Accepted for decisions the team abandoned two years ago. A quarterly ADR health review — 30 minutes, one person, deprecate what is no longer operative per the retirement protocol — prevents this from becoming a sinkhole.
Tooling integration. At three people, no tooling is needed. At ten, a GitHub Action for CI validation pays off within the first month. At fifty, a web-browsable publication layer like Log4Brains is worth the setup cost because non-engineer stakeholders (PMs, executives, new hire onboarding flows) need to find decisions without navigating a git repository.

The sections that are never optional

Regardless of team size, three sections have no optional version:

Title. The title names the decision, not the problem. "Use Postgres for the primary data store" is a title. "Database selection" is not — it names the problem space without stating what was decided. A reader scanning an index of ADRs should be able to infer the decision from the title alone. If the title requires reading the Decision section to understand what was chosen, rewrite the title.

Decision. One sentence. Active voice. Names what was chosen, not why. "We will use Postgres as the primary relational database for the user service" is correct. "After careful consideration of alternatives, we believe Postgres offers the best balance of features and operational maturity for our use case" is wrong — it restates the evaluation process rather than recording the verdict. The Why belongs in Context and Consequences; the What belongs in Decision.

Consequences. The most-read section of any ADR six months after it is written. It must be honest about the downsides. An ADR with only positive consequences in the Consequences section is a press release, not a decision record. The classic form: "This makes it harder to [X]" paired with "This makes it easier to [Y]." Both halves are required. A future engineer who hits the harder thing and reads the ADR needs to see that it was known and accepted, not that it was invisible.

The backlog of decisions that were never written down

Every team that adopts ADRs faces the same question after the first month: what about the 50 decisions made before we started? The retrospective ADR — writing a decision record for something that was decided 18 months ago — is harder than the prospective ADR because the Context is partially wrong (the original constraints are no longer visible), the Alternatives are forgotten, and the Consequences are already known (which is useful) but may have drifted from what was intended.

At small team scale, the most practical source for retrospective ADR content is AI chat exports. Teams at three to fifteen people make the majority of their architecture calls in ChatGPT or Claude sessions — "should we use Redis or Postgres for the queue?", "what are the trade-offs of GraphQL for our API layer?" — and the reasoning is preserved in those exports even when no ADR was written at the time. The WhyChose extractor reads those exports and surfaces the decisions that never reached the ADR directory, producing structured records — Decision, Context, Consequences — that can be reviewed and promoted to formal ADRs in any of the formats described above.

This is particularly useful at the transition from 3 to 10 people, when the team is adopting ADRs for the first time and realizes the historical backlog is larger than they thought. The extractor covers the backlog without requiring every founding engineer to spend a day excavating their memory of decisions made two years ago.

Get early access to WhyChose