Guide
Architecture decision records for startups: a template and example
What an architecture decision record is, which startup decisions deserve one, a minimal markdown template, and a worked Postgres example for a billing product, with the habits that keep records in use.
- Published
- Updated
- 9 min read
- By Dev Talan
Key takeaways
The short version. Each point is explained in full below.
- 01
Write an ADR only for decisions that are hard to reverse, surprising without context, and the result of a real trade-off, such as the database, authentication provider, tenancy model, or hosting region. Most pull requests should fail all three tests.
- 02
Give every record a revisit trigger with a number or an event in it, such as the 2,000 usage event writes per second in the billing example, so reopening the decision is a quick check instead of a recurring argument.
- 03
Keep ADRs as numbered markdown files in a folder such as
docs/adr, add each one in the same pull request as the change it explains, and never rewrite an accepted record: write a new one that supersedes it. - 04
Start this week by backfilling the three decisions your next engineer is most likely to question, usually the database, authentication, and how customer data is separated.
- 05
Point your agent instructions file, such as
AGENTS.md, atdocs/adrso coding agents read the log before they change the code it covers.
An architecture decision record (ADR) is a short file in the repository that records one hard-to-reverse technical decision: its context, the options considered, the choice, its trade-offs, and when to revisit it. For a startup, ADRs answer the question that every handover, new hire, and due diligence review raises: why was it built this way?
This guide to architecture decision records for startups adapts the format Michael Nygard proposed in his 2011 post Documenting Architecture Decisions for a small team that ships every week. It covers which decisions deserve a record, a minimal ADR template, a worked example for a billing product on Postgres, where to keep the files, and the habits that keep them in use.
What is an architecture decision record?
#An architecture decision record captures one significant decision and the reasoning behind it, in about a page. Architecture here means any choice that shapes the system and costs a lot to change later, whether or not it appears on a diagram. The full set of records, read in order, explains how the system reached its current shape.
- ADR
- One decision in one file, with the context, the options considered, the decision, and its consequences.
- Decision log
- The folder that holds every ADR, numbered in order. Numbers are never reused.
- Status
- Proposed while under review, Accepted once agreed, and Superseded when a later record replaces it. Some teams also use Deprecated for a decision that no longer applies and has no replacement. Either way, the old record stays in the log.
- Revisit trigger
- A condition you can check, such as a write rate, a table size, or a contract requirement, that should reopen the decision.
An ADR is not a design document or meeting notes. A design document explores how to build something and can run for pages. An ADR records what was chosen and why, and links to the longer material if it exists. Microsoft's guidance on maintaining an architecture decision record asks for records that are “pithy, assertive, on-topic, and factual,” and that rule suits a startup well.
Why do startups need architecture decision records?
#Startups need ADRs because the people who make the early decisions are rarely the people who live with them for long. Code shows what the system does. It doesn't show the options someone rejected, or the constraint that ruled them out. That gap gets expensive at three predictable moments.
| Moment | What gets asked | Without ADRs | With ADRs |
|---|---|---|---|
| Handover | Why is billing a separate service? Can we drop this queue? | The new team guesses intent from the code, or reopens decisions that were already settled | Dated reasoning, the options that lost, and the trigger that would justify a change |
| Technical due diligence | Why this database, this hosting, this way of separating customer data? | Founders answer from memory, and the answers drift between calls | A list of deliberate choices with known limits, ready before the data room opens |
| New hires | Why does it work like this, and is it safe to change? | Weeks of questions and digging through old chat threads | An afternoon reading the log, then informed questions |
Coding agents read the repository too. A recorded decision tells them which patterns are deliberate, so they are less likely to undo a constraint they can't see. Point your agent instructions file, such as AGENTS.md, at docs/adr so agents read the log before they change the code it covers. When a team builds fast with AI tools, the reasoning is the easiest part to lose.
ADRs don't impress investors on their own
No one funds a company for its decision log, and not every round includes technical diligence. What reviewers look for is evidence that the team understands its own system and its limits. Records written as you go provide that evidence. Reconstructing them the week before a round produces thinner records with less of the real reasoning.
Which technical decisions deserve an ADR?
#A decision deserves an ADR when it passes three tests: it is hard to reverse, a future engineer would be surprised by it without context, and it came from a real trade-off between options. Documenting technical decisions only helps when the records are few enough to read, so most pull requests should fail all three tests.
- The primary database, and how money, time, and identifiers are stored in it.
- The authentication provider and how sessions and roles work.
- How tenant data is separated, for example with Postgres row-level security or a schema per customer.
- Hosting, regions, and where customer data is allowed to live.
- What runs in background jobs instead of a web request, and how it retries.
- Build versus buy for a core capability such as billing, search, or notifications.
- API style and versioning, once customers or other teams depend on it.
- What data an AI feature may send to a model provider, and what it must never see.
- A shortcut taken on purpose for speed, with the condition that ends it.
Skip records for choices that are cheap to change or follow a convention: a date library, lint rules, folder names. If a pull request description can explain it, it doesn't need an ADR. Many bigger choices surface while scoping an MVP, the natural time to write the first few.
What should an ADR template include?
#A minimal ADR template needs a title, status, date, context, options considered, decision, consequences, and a revisit trigger. Nygard's original format had five parts: title, context, decision, status, and consequences. The two main additions earn their place at a startup: the rejected options are what a new team most needs to know, and startup constraints change fast enough that every decision should say when to reopen it. The confidence line is optional. Microsoft's guidance recommends recording it, because a decision made with low confidence is the first one to reconsider.
# 0000: Decision stated as a short phrase
- Status: Proposed | Accepted | Deprecated | Superseded by 0000
- Date: YYYY-MM-DD
- Deciders: names or roles
- Confidence: high | medium | low
## Context
The problem, the constraints, and the facts that force a choice now.
Write facts, not opinions, and link to data or tickets.
## Options considered
1. Option A: what it is, its main strength, its main cost.
2. Option B: what it is, its main strength, its main cost.
3. Option C: what it is, its main strength, its main cost.
## Decision
We will ...
## Consequences
- What gets easier.
- What gets harder, and what we accept in exchange.
- Follow-up work this creates.
## Revisit when
A measurable condition that should reopen this decision.How do you write an architecture decision record?
#Write an ADR while the decision is being made, in a pull request, and keep it under half an hour of work. These steps fill in the template.
- 01Name the decision, not the topicA title such as “Use Postgres for billing” states the choice, so it is easy to find and to supersede.
- 02Write the context as factsList the requirements, constraints, expected volumes, deadlines, and what the team already knows how to run.
- 03List the options you really consideredInclude buying a service and doing nothing when they were on the table, each with its main strength and main cost.
- 04State the decision in one or two sentencesStart with “We will”, in active voice, so nobody has to infer what was chosen.
- 05List the consequences honestlyInclude what gets harder and the follow-up work. A record that lists only benefits reads as a sales pitch, and the next team won't trust it.
- 06Set a revisit trigger you can checkPick a number or an event, such as a write rate or a contract requirement. A trigger like that turns a recurring argument into a quick check.
- 07Review it like codeOpen the record as Proposed, let reviewers challenge the options and the trigger, and change the status to Accepted when the pull request merges.
What does a worked ADR example look like?
#A worked ADR example states the choice, gives each losing option a fair line, admits the costs, and ends with a trigger that has a number in it. This one is for a hypothetical seed-stage billing product: a B2B SaaS that meters customer usage and sends monthly invoices, built by three engineers who know TypeScript and SQL. The volumes and thresholds are made up for illustration and don't come from a real product.
# 0003: Use Postgres as the system of record for billing
- Status: Accepted
- Date: 2026-11-01
- Deciders: CTO, founding engineer
- Confidence: high for invoices and ledger, medium for usage events
## Context
We bill B2B customers monthly from metered usage. An invoice, its line
items, and its ledger entries must be saved together or not at all.
Finance needs monthly revenue and overdue-invoice reports in SQL.
Amounts must be exact. We expect about 5 million usage events a month
in year one. The team knows TypeScript and SQL, and nobody has run
MongoDB or DynamoDB in production.
## Options considered
1. Managed Postgres: transactions, foreign keys, check constraints, and
SQL reporting. One primary database to scale.
2. MongoDB: flexible documents and multi-document transactions.
Fewer rules enforced by the database, so more money logic lives
in application code, and finance would need a new reporting path.
3. DynamoDB: scales writes with no servers to manage. Access patterns
must be designed up front, and finance reports need an export.
4. Stripe Billing as the only record: nothing to run. Our contract
pricing rules would still need a database, and reports would depend
on API calls or exports.
## Decision
We will store customers, contracts, invoices, line items, and an
append-only ledger in managed Postgres. Amounts are bigint minor units
with an ISO 4217 currency column. Stripe holds payment methods and
charges, and we store its IDs, not copies of its data.
## Consequences
- Invoice generation runs in one transaction, so a failure leaves no
partial invoice.
- Check constraints reject negative invoice totals, and a foreign key
to a currencies table rejects unknown currency codes.
- We own migrations, backups, and major version upgrades.
- usage_events will grow fastest, so we partition it by month now.
- Heavy reports may later need a read replica to keep invoicing fast.
## Revisit when
- Usage event writes regularly exceed 2,000 per second, or the table
passes 500 million rows. Move usage events out first, not the ledger.
- A customer contract requires data residency our provider can't offer.Four details make this record useful a year later.
- The context is specific. Atomic invoices, SQL reports, exact amounts, and the team's skills decided it, and a later reader can check whether they still hold.
- The losing options get a fair line each. MongoDB, DynamoDB, and Stripe-only suit other products, and the record says why they lost for this one.
- The costs are written down. Upgrades, partitioning, and a possible read replica are known before they surprise anyone.
- Confidence and triggers are split by part. The ledger decision is firm. Usage events have their own trigger, so a scaling problem doesn't turn into a full database migration.
Money needs an exact type
The PostgreSQL documentation calls real and double precision inexact and recommends numeric where exact storage is required, such as for monetary amounts. Integers in minor units, like the bigint amounts above, are the other common exact choice. Whichever you choose, record it, because changing it later touches every table and report that holds money.
Where should you store architecture decision records?
#Store ADRs in the repository, next to the code they explain, as one numbered markdown file per decision in a folder such as docs/adr. Nygard's original post kept them in the project repository as doc/arch/adr-NNN.md. Every engineer, reviewer, and coding agent already reads the repository, and it moves with the code at handover.
| Location | Works well for | Breaks down when |
|---|---|---|
Repository, in docs/adr | Versioning with the code, review in pull requests, and handover with the repository | Non-engineers need a direct link to read them |
| A wiki such as Notion or Confluence | Readers outside engineering | Pages drift from the code, changes skip review, and a contractor's workspace leaves with the contractor |
| Tracker tickets | Keeping the decision next to the work | Closed tickets get buried, and the decision is mixed into the discussion |
| Shared documents and chat threads | Getting a first draft down quickly | No status, no numbering, and each document belongs to whoever created it |
docs/adr/
README.md
0000-template.md
0001-record-architecture-decisions.md
0002-typescript-across-the-stack.md
0003-postgres-for-billing.md
0004-row-level-security-for-tenants.mdOur open source Damn Labs tools keep their logs the same way. When this guide was published, Commitscape had 31 numbered records in docs/adr and Hexlode had 10. On client projects, choices such as the database, hosting, and authentication provider go into ADRs in the client's own repository, as our engineering standards describe.
Which habits keep ADRs useful?
#ADRs fail in two ways: they turn into paperwork nobody writes, or into a folder nobody reads. These habits prevent both.
- Cite the record where the question comes up. Put the ADR number in the pull request description and in review replies, such as “intended, see ADR 0003”, so readers find the reasoning from the change. Our AI code review workflow uses the same one-line reply to dismiss a reviewer's false flag.
- One decision per file. If a record covers the database and the job queue, split it.
- Keep it to a page. A longer record is becoming a design document. Write that separately and link to it.
- Never rewrite an accepted record. Write a new one, and change only the old record's status to
Superseded by 0007. Commitscape's record 0024, which moved commit lists into Postgres rows, was superseded by 0027 ten days after it was accepted. Its status line is the only part that changed. - Check revisit triggers on a schedule. Scan them once a quarter. The ones that fired become roadmap items.
- Backfill the decisions people ask about. With no log yet, start with the choices new hires question most, and mark each record as written after the fact.
- Record the big calls too. A rebuild or refactor decision belongs in the log with the options the team rejected.
If you are choosing an outside team, ask how it records decisions and where the records will live. The software partner evaluation checklist lists more questions to ask any partner before you sign.
What should you do next?
#Create docs/adr this week, add the template, and backfill records for the three decisions your next engineer is most likely to question: usually the database, authentication, and how customer data is separated. After that, add a record in the same pull request whenever a hard-to-reverse choice comes up.
If you are preparing for a handover or a round, or you inherited a codebase with no written reasoning, the technical debt triage checklist is a good first pass. For an outside read, a software audit reviews the code, architecture, infrastructure, and workflow in about 3 to 5 days, and its written report ranks risks and fixes.