Building Software
Sections

Contents Section 1, Ideal State

Decisions: Recording Why, Inside the Living Artifact

Recording each decision as a dated entry in the project's one living ideal-state document, with the options, their costs and the reason, so later readers, human or agent, can tell a deliberate choice from an accident.

Section 1 of 9, subsection 5 of 5. Depth: do. A 10-minute read.

Mistakes to catch in review

  1. A public API field named and shipped during a small bug fix, making the name permanent for every client.

  2. An agent-written decision entry that lists options with pros for each but never states what was chosen or what was given up.

  3. A deliberate earlier choice, such as avoiding a message queue, undone by an agent because the reason was never written where the agent reads.

  4. A design document written once before the work started and never updated, so an agent changes the code back to a plan the team had abandoned.

Writing Down Why

An agent is asked to make webhook delivery more reliable. It reads the code and finds a worker that polls a database table every two seconds for unsent webhooks. Then it finds docs/design/webhooks.md, written before the work started, which says order events go to a managed message queue. The agent concludes that the code drifted from the design and proposes to bring it back in line: replace the table with the queue, about 400 lines, with the design document cited as the reason.

Each step of that reasoning holds up, and the conclusion is wrong. Three weeks into the build, the team abandoned the queue on purpose. They had one engineer on call, they already ran the database, and a queue would have been a second stateful system to secure, monitor, back up and wake up for at 03:00. That reasoning lived in a meeting and a chat thread. Nobody updated the design document, because it had done its job once the work started.

The code shows what the team built and says nothing about why, or about the paths they tried and left. For the next reader, human or agent, to tell a deliberate choice from an accident, the reason has to sit where that reader looks, and stay current.

One document, kept current

An agent works from text it can read. A reason can live in three places, and each behaves differently when the agent arrives:

  • In a person's head or a chat thread. The agent never sees it.
  • In a separate design document written before the work. The agent sees it, but it records the plan on the day it was written. Once building teaches the team something, the document is wrong, and it is wrong in a confident, well-formatted way.
  • In the document the work is built against, updated as part of the work. The agent sees it, and it says what is true now.

The third is the ideal-state document from the first lesson of this section: one file per project holding the ideal state in prose, the constraints, the criteria that check it, and a log of decisions. Daniel Miessler, who calls his version an Ideal State Artifact (ISA), describes the log this way: when building teaches you something or changes your mind, "you write it back into the ISA with the date and the reason, so the iteration happens in the articulation instead of getting lost in the code."

Two bands. Top band: a design doc written before the work, which says use a queue, points to an agent with the label reads; the agent proposes the queue. A chat thread holding why the plan changed has a dashed arrow to the agent marked never read. A note under the design doc reads: written once, then wrong. Bottom band: a box labelled ideal-state document holds two entries, 2025-09-08, plan: a queue, and 2025-10-02, supersedes it, with why. An arrow marked reads goes from the document to an agent that checks the revisit line.
The design file still says to use a queue and the reason for dropping it sits in a chat thread, so the agent proposes the abandoned plan. In the living document the 2025-10-02 entry supersedes the queue plan, and the agent checks its revisit line.

The design file in the opening failed because it was written once and then left alone while the plan changed under it. A log written during the work records each change on the day it happens, in the file the agent already reads.

What the criteria cannot say

The criteria in the document say what must be true. For the webhooks: every committed order produces exactly one webhook event, a merchant whose server was down hears about every order once it is back, and checkout never waits on a merchant. The build is checked against them.

Now hold the agent's queue proposal up to those criteria. Built carefully, with the failed-publish case handled, a queue passes every one. The evals go green. The team's reason for the table was the cost of running a second stateful system with one engineer on call, and that cost belongs to the design, so no criterion measures it.

You could add a constraint, "no new stateful systems", and the agent would obey it. It would still have no way to tell when the constraint should be lifted, because the reason and the conditions for reopening it are missing.

Decision entries cover what the criteria leave open. When several designs would all pass, the entry records which one the team chose, what each option cost, and the facts the choice rested on. When building changes what the team wants, the entry records that change, and the ideal state and criteria are edited to match.

A decisions log, worked

Here is part of the webhook project's document a few weeks into the build:

Markdown
# Order webhooks

## Ideal State
When a customer places an order, the merchant's server hears about it within
seconds. Merchants' servers are sometimes down for minutes; a merchant whose
server was down hears about every order once it is back. Checkout never waits
on a merchant. A merchant may receive a webhook twice and deduplicates on
`event_id`. One on-call engineer can run this without being woken for it.

## Constraints
- Runs on the PostgreSQL database we already operate (see 2025-10-02).

## Criteria
- ISC-1: A committed order produces exactly one webhook event; a rolled-back
  order produces none. Check: test that aborts the order transaction.
- ISC-2: A merchant down for up to 3 hours receives every pending webhook
  within 10 minutes of coming back. Check: fake merchant, simulated clock.
- ISC-3: Checkout p95 does not change when a merchant takes 30 s to answer.
  Check: load test against a slow fake merchant.
- ISC-4: Every webhook carries an `event_id` that is the same on a resend.
  Check: test that kills the worker after a send, before it records the send.

## Decisions
- 2025-09-08: Publish order events to a managed message queue. Why: the usual
  tool, and other services may want order events later.
- 2025-10-02: Supersedes 2025-09-08. Write each webhook to an `outbox` table in
  the order's transaction; a worker polls it every 2 s and sends.
  Options: (A) send inside the order request: fails ISC-3, and a failed request
  loses the webhook. (B) outbox table: no new system; delivery starts within
  about 2 s when the worker is idle. (C) queue: far higher volume and fan-out,
  but a second stateful system to secure, monitor and back up, and a new
  failure where the order commits and the publish fails.
  Why B: one engineer on call; PostgreSQL already runs; peak is 20 webhooks/s,
  measured; merchants accept a few seconds of delay but not a lost webhook.
  Gives up: fan-out to other consumers.
  Revisit when: peak passes 500/s, or a second service needs order events.
- 2025-10-20: A worker crash after the send and before COMMIT sends the
  webhook again. Changed the ideal state: a merchant may receive a webhook
  twice and deduplicates on `event_id`. Added ISC-4. Why: three large
  merchants confirmed they can deduplicate, and exactly-once delivery would
  need their cooperation anyway.
- 2025-11-12: Capped retry backoff at 5 minutes, down from 1 hour. Why: ISC-2
  failed; with a 1-hour cap a webhook could wait almost an hour after the
  merchant recovered. Costs: about 290 tries per pending webhook in a day-long
  outage, up from about 30.

The 2025-10-02 entry has the parts every decision entry needs. It names the entry it supersedes, so the queue plan stays readable next to its replacement. It lists the real options, each with its cost beside its benefit. It gives the facts the choice rests on, with numbers, and says the volume was measured. It names what the team gave up. Its last line says when to reopen the question, which turns a future argument into a check anyone can run.

Three paths to a merchant server on the right. Option A, the order request, sends directly, marked slows checkout. Option B is a box labelled one transaction holding the order and the outbox row; a worker that polls every 2 seconds reads the outbox and sends to the merchant. Option C, order commits, has a dashed arrow marked publish can fail into a message queue, a second stateful system, which sends to the merchant. A note under option B reads: both rows or neither.
All three options end at the merchant's server; only option B writes the order and its outbox row in one transaction, so a webhook exists if and only if the order does.

Option B works because the order and its outbox row are written in one transaction: both rows or neither, so a webhook exists if and only if its order does. Option A slows checkout whenever a merchant's server is slow.

The next two entries were written because building taught the team something. Here is the worker that option B needs:

SQL
BEGIN;

SELECT id, event_id, merchant_url, payload
FROM outbox
WHERE sent_at IS NULL AND next_attempt_at <= now()
ORDER BY next_attempt_at, id
LIMIT 50
FOR UPDATE SKIP LOCKED;

-- send each webhook with a 5-second timeout, then for each one that succeeded:
UPDATE outbox SET sent_at = now() WHERE id = $1;

-- and for each one that failed: wait 10 s, 20 s, 40 s ... up to the cap
UPDATE outbox
SET attempts = attempts + 1,
    next_attempt_at = now() + LEAST(interval '5 minutes', interval '10 seconds' * power(2, LEAST(attempts, 5)))
WHERE id = $1;

COMMIT;

FOR UPDATE locks the selected rows until the transaction ends, and SKIP LOCKED tells a second worker running the same query to pass over rows the first one holds instead of waiting. If a worker crashes mid-batch, its transaction rolls back, the locks release, and another worker picks the rows up.

Worker 1 sends the webhook to the merchant, marked send 1, then crashes. Below it a rollback box notes sent_at is still null. Worker 2 picks the row up and sends it again, marked send 2. The merchant box reads: receives it twice. A note reads: handle duplicates.
Worker 1 sends, then crashes before COMMIT, so the row rolls back unsent and worker 2 sends it again.

That recovery has a price nobody saw on 2025-10-02. A worker that sent a webhook and then crashed before COMMIT leaves the row unsent in the database, even though the merchant already has it, so the next worker sends it again. The team chose to change what they promised. The 2025-10-20 entry rewrites the ideal state so a merchant may receive a webhook twice and deduplicates on event_id, and adds ISC-4 to check that the id survives a resend. An entry like this changes the target itself, so the prose and the criteria are edited in the same change, and the document never promises one thing while checking another.

The 2025-11-12 entry came from a failing criterion. The worker first capped its backoff at an hour, and ISC-2 says a merchant down for up to three hours gets every pending webhook within ten minutes of coming back. This block checks both caps against ISC-2:

TypeScriptRuns in your browser
// One webhook, first tried at second 0, to a merchant whose server is down for `downFor` seconds.
// After its nth failure the worker waits min(cap, 10 × 2^(n - 1)) seconds before trying again.
function deliver(downFor: number, cap: number) {
  let at = 0;
  let tries = 0;
  for (;;) {
    tries++;
    if (at >= downFor) return { tries, lateBy: at - downFor };
    at += Math.min(cap, 10 * 2 ** (tries - 1));
  }
}

for (const cap of [3600, 300]) {
  // ISC-2: any outage up to 3 hours, checked every 10 seconds of outage length.
  let worst = 0;
  for (let down = 10; down <= 3 * 3600; down += 10) worst = Math.max(worst, deliver(down, cap).lateBy);
  const day = deliver(24 * 3600, cap);
  const isc2 = worst <= 10 * 60 ? "PASS" : "FAIL";
  console.log(`cap ${cap / 60} min: ${isc2} ISC-2, worst wait after recovery ${worst} s, tries in a 24 h outage ${day.tries}`);
}

With the 1-hour cap, a merchant that recovers just after a failed try waits almost an hour for the next one, so ISC-2 fails. With a 5-minute cap the worst wait is under 5 minutes. The fix costs something too: in a day-long outage each pending webhook is tried 293 times instead of 33. The entry records both, so whoever wants to raise the cap later knows which criterion it protects and what it costs.

Now give the agent from the opening this document instead of the stale design file. It finds the queue plan, sees that 2025-10-02 supersedes it, and reads the revisit line: is peak volume near 500 a second, and does another service need order events? If neither is true, the queue brings back the cost the team chose to avoid and solves nothing they have. If one is true, the agent can say so, cite the entry, and propose a new one. Either way the decision is made against the original reasoning.

Change by appending

The ideal state, the constraints and the criteria are edited in place, so they always say what is true now. The decisions log is the one section that only grows. When a decision changes, you add a dated entry that names the one it replaces, and you leave the old entry where it is.

Rewriting the old entry looks tidier and destroys the record. The 2025-09-08 entry still says "use a queue", and that line earns its place: it shows the next reader that the team already considered the agent's idea, and the entry below it says why they moved off it.

Michael Nygard's architecture decision records, short numbered files with context, decision and consequences, carry the same parts. Here they live in the document the build is checked against, next to the criteria they explain.

Which decisions need an entry

What it costs to reverse a decision should decide how carefully it is made. Jeff Bezos's shareholder letters describe the split as one-way and two-way doors. A two-way door is cheap to walk back through: a function name, an internal library, a log format. Make these quickly and fix them if they turn out wrong. A one-way door is expensive or impossible to reverse. Slow down, get a second opinion, and write the entry before it ships.

The practical test is to count who depends on the choice and whether you control them. An internal function name has callers only in your repository, so you can rename it in one commit. A column in your own database is harder, because data already exists in that shape and you need a migration, but you still control every step. A field in a public API is at the far end. Once a client has written code that reads customer_name, you cannot rename it without breaking that client, and you do not control when they upgrade. The name is effectively permanent.

Three boxes from left to right. Function name, callers in your repo, reverses in one commit. Database column, data already in that shape, reverses with a migration you control. Public API field customer_name, read by clients, is effectively permanent, because you do not control when clients upgrade. Below them an arrow runs from two-way door on the left to one-way door on the right, marked cost to reverse. A note reads: count who depends.
A name gets harder to reverse as more parties outside your control depend on it; once clients read customer_name, it is effectively permanent.

This is how a small change becomes a large decision without anyone noticing. An agent fixing a bug in an order endpoint adds a field to the JSON response because it needed it for the fix, and names it cust_nm to match a database column. The change is ten lines, and it ships as a bug fix. A merchant's integration starts reading the field, and the team now supports that name for years.

The question that finds these is whether a change adds or alters anything a party outside your control will read or write. It can run without a person: a test that compares each public response's fields against the fields the document lists for the API fails the build when a new one appears, which sends the change to someone who can write the entry. Data formats, storage engines, public identifiers and anything customers integrate against are usually one-way. Most internal code structure is two-way, and the code and its commit message are record enough.

Options with their costs

The weakest decision entries list options with an advantage for each and then stop. "Option A is simple. Option B is scalable. Option C is flexible." Nothing is chosen, and the reader learns nothing about what any option costs. Agents produce this shape often when a prompt asks them to compare options and never asks them to choose.

The fix is to require the cost of every option alongside its benefit, in the same units where you can: how many new systems or concepts, how many weeks, a monthly bill, what fails and how badly. Then the entry has to name one option and say what it gives up. An entry that ends with "any of these would work" has no decision in it, and the next reader has to redo the whole analysis.

Estimates belong in the entry

Estimates go in the entry too, written as ranges. "Two to five weeks" tells a reader more than "three weeks", because the width shows how much is still unknown. When the range is wide, find the unknown that makes it wide and settle that first. When the duplicate problem surfaced, the estimate for finishing went from two weeks to two to five, and most of the width came from one question: could the large merchants deduplicate? A day asking three of them narrowed the range more than a week of building the easy parts would have, and their answer became the reason in the 2025-10-20 entry.

Reading a decisions log

When you read an entry, whether a colleague or an agent wrote it, look first for the sentence that states the decision. If there is none, the entry compares options without choosing, and the choice is still open.

Then find the assumption the decision rests on and ask how sure anyone is of it. In the 2025-10-02 entry it is the volume: 20 webhooks a second, and the choice holds while volume stays well below 500. A measured 20 is worth more than a guessed one. Is a sales deal about to add a merchant ten times larger than any current one? An assumption that a known event is about to break deserves a new entry now, before the revisit line fires.

Then check whether the entry changed what the project wants. If it did, the ideal state and the criteria should show the same change. An entry saying merchants may get duplicates, next to a criterion that still demands exactly one delivery, gives the agent two instructions and no way to pick.

An entry is complete when an agent reading it six months later can tell, without asking anyone, whether its change undoes a deliberate choice.

Check your understanding

8 questions on this lesson. Pick an answer to see whether it holds and why.

  1. 1This handler serves the public orders API that merchants integrate against. An agent's pull request, titled Fix missing apartment number on packing slip, adds one line. Which part of the change is hardest to undo later?
    Diff
     return Response.json({
       id: order.id,
       total_cents: order.totalCents,
    +  shipAddr2: order.address.line2,
     });
    Show the answer

    Answer B. Once a merchant's integration reads shipAddr2, renaming it breaks that merchant, and you do not control when they upgrade, so the name is effectively permanent. The packing-slip layout and the way the handler loads the address are internal, and a later commit can change either. A one-way decision inside a small diff deserves a deliberate name and a decision entry, or the value stays off the public response.

  2. 2An agent working on login finds the design file below, then proposes moving sessions to Redis to bring the code back in line with the design. What should happen before anyone weighs the proposal?
    Output
    docs/design/sessions.md, written 2025-03-02 before the work started:
      Decision: store sessions in Redis so any web server can read them.
    
    The code today:
      Sessions are signed cookies. The repository has no Redis client.
      The project's ideal-state document has no entry about sessions.
    Show the answer

    Answer D. A design file written before the work records the plan on the day it was written, so a difference from the code may be a later, deliberate change nobody wrote down. Treating the old file as current intent is how an abandoned plan comes back. Editing the file to match the code hides the same gap: the next reader still cannot tell why cookies won or when Redis would be right again.

  3. 3An agent proposes moving product search to a dedicated search service. The catalog now has 52,000 products, and product management has just made typo tolerance a launch requirement. The project's ideal-state document holds this entry. What should the agent do?
    Markdown
    - 2026-01-14: Keep search in PostgreSQL full-text search on the products
      table, over a dedicated search service. Why: 40,000 products; one on-call
      engineer; searches return in under 100 ms. Gives up: typo tolerance.
      Revisit when: the catalog passes 1 million products or typo tolerance
      becomes a requirement.
    Show the answer

    Answer C. The revisit line joins two conditions with or, and the new typo requirement meets the second, so the decision is open again. The change gets its own dated entry that supersedes the old one, and the criteria gain a check for typo tolerance in the same change. Rewriting the 2026-01-14 entry looks tidy, but it erases why PostgreSQL was chosen and what changed since.

  4. 4A team has four decisions to make this week. Which one deserves a dated entry in the decisions log and a second reviewer before it ships?
    Show the answer

    Answer D. Order numbers on invoices and in a public API are read by customers and their systems, which you do not control, so changing the format later breaks them. The library swap can feel like the big decision because its diff is large, but every caller is inside your service and a revert undoes it. The rename and the log format are internal too.

  5. 5Here is an agent-written entry in a project's decisions log. Which assumption should a reader check first?
    Markdown
    - 2026-02-03: Search runs in memory on each web server. Why: the catalog has
      40,000 products (from last month's export); each of our 4 web servers loads
      the full catalog at startup, about 200 MB per server. Sales is negotiating
      with a marketplace partner that would list its sellers' products.
      Revisit when: memory use passes 2 GB per server.
    Show the answer

    Answer A. The decision holds only while the whole catalog fits comfortably in each server's memory, so catalog size is the number everything rests on, and the entry itself mentions a deal that could multiply it. The revisit line looks like a safety net, but it fires only once memory is already high, and one partner import could cross it overnight.

  6. 6An agent's decision entry for caching product pages reads like this. What should a reader ask for first?
    Markdown
    - 2026-03-10: Cache rendered product pages at the CDN edge for 10 minutes.
      Pages are not purged when a product changes; they expire on their own.
      Consequences: origin traffic drops by about 80%; pages load faster for
      shoppers far from our servers.
      Revisit when: origin traffic passes 5,000 requests a second.
    Show the answer

    Answer B. Every consequence listed is a benefit. With no purge, a changed price or a sold-out item can show its old value for up to 10 minutes, and the entry accepts that cost without saying so. A shorter cache time is tempting, but it changes the design before the tradeoff is written down, and a 1-minute cache is still stale for up to a minute.

  7. 7A team stores uploaded files on the local disk of a single server. An agent proposes moving them to object storage, and every criterion in the project's ideal-state document passes against both designs. What does that tell you?
    Show the answer

    Answer C. Criteria say what must be true, and two designs can both meet them. What separates them is a cost or a fact the criteria do not measure, which is what a decision entry records; if there is none, finding the reason and writing the entry comes first. Adding criteria until one design passes ties the build to a how and still hides why it was chosen, so nobody can tell when it should change.

  8. 8An agent estimates a data migration at 2 to 9 weeks. Most of that width comes from not knowing whether the old system's export includes deleted records. What should happen next?
    Show the answer

    Answer A. A wide range shows how much is unknown, and here one unknown drives most of it, so answering that question first narrows the estimate fastest. Starting with the easy tables feels productive, but the risky unknown is still there when they are done. Reporting the midpoint throws away what the range was telling the reader.

You understand it when you can

Drill

An agent added an entry to a billing system's ideal-state document that compares three databases, ends with 'any of these would work well', and leaves the criteria untouched. Find what the entry never decides, which part of the choice is a one-way door, and what an agent reading the document six months from now would be unable to learn from it.

Topics

Options and Tradeoffs Inside the Ideal-State Document
Writing the options considered, and the one chosen, into the project's living document as the work goes, so the plan and what happened sit in one place an agent reads.
The Dated Decisions Log
Short dated entries saying what changed in the ideal state, the criteria or the design, and why; a changed decision gets a new entry that supersedes the old one, which stays readable.
Reversible and One-Way Decisions
Moving fast on choices that are cheap to undo and slowing down on the few that are expensive to reverse.
Tradeoff Analysis
Making the cost of every option explicit (complexity, speed, money, risk) alongside its benefits.
Estimating Work Under Uncertainty
Giving ranges instead of single numbers, and tackling the riskiest unknown first.

Further reading

Start here

  • Lesson 55 - Architecture Decision Records. Mark Richards, 2019. 10-minute explainer.

    A ten-minute walkthrough of the ADR sections (context, decision, consequences, status) and why the justification is the part later readers need most.

Short reads

Watch

Books

  • Facilitating Software Architecture: Empowering Teams to Make Architectural Decisions. Andrew Harmel-Law, 2024.

    Detailed guidance on writing ADRs, taking advice from affected parties and keeping a decision log that later readers, human or agent, can follow.

  • Fundamentals of Software Architecture: A Modern Engineering Approach. Mark Richards and Neal Ford, 2025, 2nd edition.

    Its chapters on architecture decisions and characteristics teach how to justify a choice against named quality attributes and document it.

  • Software Estimation: Demystifying the Black Art. Steve McConnell, 2006.

    The standard text on the cone of uncertainty, estimating in ranges and separating estimates from targets and commitments.

Primary sources