One-Page Decision Records (ADR) for People and for AI

For anyone who works in a team with code, including newcomers and people who hand work to AI agents. No software design background is needed. Every term comes with an everyday example, and the calculation is marked so you can skip it.

The numbers come from public sources listed at the end. Examples labeled "illustration" are made up for this post and do not mention real people or companies. How an AI agent reads and uses documents internally is not fully understood by anyone, so the pictures below are memory aids only. The AI advice in this post is a synthesis of practice, not the result of a controlled experiment.

---

Quick summary#

• The hardest part of a project is often not the code but the reasons behind the code. Reasons tend to live in a few heads, then leave with them.
• An ADR (architecture decision record) is one short page that records one decision: context, decision, consequences and status. Michael Nygard proposed the format in 2011 and recommended one to two pages.
• A newcomer without the reasons has two paths, both bad: accept without understanding, or reverse without knowing the consequences. Nygard describes exactly those two paths.
• An AI agent can end up in a similar spot: it sees a "roundabout" piece of code and tidies it up, not knowing the roundabout shape was deliberate. An ADR linked from the agent's instruction file is a place to check before editing.
• A good ADR needs only one page: written for a reader in the future, naming the options that were rejected and what we accept to lose. A template to paste is included.
• An ADR is not a ritual for every change. Small, easily reversed decisions do not need one. And an ADR only helps if someone keeps its status current and someone reads it.

---

Hard words, plain meaning#

---

1. A picture first: the note in the recipe#

Picture a restaurant with a recipe book. The soup entry says: "No salt, season with fish sauce at the end." A new kitchen helper finds the soup bland and adds salt. That day a guest allergic to salt orders the soup. Nobody meant harm. The book was missing one line: "why no salt".

Now picture the book with that line: "No salt, because this dish also serves guests on restricted diets. Guests add salt at the table." The helper reads it and understands, and if the restaurant changes its policy, there is a place to edit.

An ADR is that note, but for code. And for an AI agent walking into a repository, it is a note the agent can read before it "adds some salt".

Takeaway: what needs saving is not a thick book but the reason for each decision worth remembering, short enough that someone reads it.

---

2. What an ADR is, from the sources#

2.1 Michael Nygard's original (2011)#

In "Documenting Architecture Decisions", published on the Cognitect blog on 15 November 2011, Michael Nygard writes that architecture decisions often come with no record of why. A newcomer to the project has only two options: accept the decision without understanding it, or reverse it without knowing the consequences. He says both can hurt the project, and too many unexplained decisions make a team afraid to change anything.

He proposes that each record has five parts:

• Title: a short noun phrase.
• Context: the forces at play (technological, political, social, project local), stated as fact without judgment.
• Decision: full sentences, active voice, starting with "We will".
• Status: "proposed" until the stakeholders agree, then "accepted". Later it may become "deprecated" or "superseded", with a link to the replacement.
• Consequences: the context after the decision, including the positive, negative and neutral effects.

On length: one to two pages. On voice: write as if having a conversation with a future developer, in full sentences, using bullets only for layout and not to replace sentences with fragments. On storage: in the project repository, for example doc/arch/adr-NNN.md, numbered sequentially and never reused. A reversed decision is not deleted: the old record stays and is marked superseded.

Nygard also shares an experience: after about three months of use on several projects, six to ten developers who rotated through them said the context in the records was valuable. This is the author's own account from a small group, not a controlled study.

2.2 MADR: a popular Markdown template#

MADR (Markdown Architectural Decision Records) is a lean template written in Markdown. According to the official page, its parts are: title, optional front matter (status, date, decision makers, consulted, informed), context and problem statement, optional decision drivers, considered options, decision outcome (with good and bad consequences), optional confirmation of compliance, pros and cons of the options, and more information (which can state conditions for revisiting). The storage convention: the directory docs/decisions, with files named NNNN-title-with-dashes.md in sequence. The latest version the page describes is 4.0.0, released 17 September 2024, dual licensed MIT or CC0.

2.3 Y-statement: an ADR in one sentence#

The Y-statement is a short form popularized by Olaf Zimmermann and the authors associated with it, a single sentence in the pattern: "In the context of (situation), facing (concern), we decided for (option) and against (other options), to achieve (quality goal), accepting (downside)." The sources I read word the connectors slightly differently ("and against" or "and neglected"), so treat it as a pattern, not a hard standard. The Y-statement suits simple decisions. For complex ones, the sources suggest fuller formats such as MADR or Nygard's version.

Takeaway: an ADR is not a complicated tool. The core is four questions: what situation are we in, what do we choose, what do we drop, and what do we accept losing.

---

3. Why teams lose decisions, and why AI makes it more visible#

3.1 Data from the Stack Overflow 2026 survey#

The results page of the Stack Overflow Developer Survey 2026 has a section on context-related difficulties. According to the summary I read, about 60.9% of respondents say important context lives in people's heads, 56.5% say information is outdated, 53.4% say it is spread across too many tools and 63.2% say it is incomplete. I read a summary and did not cross-check the tables, the original questions may be broader than technical decisions, and the respondents are people who chose to take the survey. So read this as a general signal that team knowledge tends to be scattered, not as evidence about ADRs.

3.2 With AI agents: it sees the code, not the reason#

Picture an agent as a colleague who is very fast but joined today: it reads all the code in seconds, but does not remember last week's meeting. When it sees a roundabout piece of code, the reasonable reflex is to simplify it. If the roundabout shape is the result of a decision with a reason, the only thing that can stop it is the reason written where it looks.

A limit to state plainly: I found no study that measures how much putting ADRs in context reduces how often agents reverse decisions. This is a practical argument, connected to the post A handbook for AI: AGENTS.md, where we put what the agent needs to know in the place it reads.

3.3 A calculation you can redo (illustration, skippable)#

This is an illustration with made-up numbers, not measurements. Suppose a team of six records two decisions a month, each ADR is 300 words, and technical reading speed is 150 words per minute (an assumption). In a year the team has 24 ADRs.

adr, words, wpm = 24, 300, 150
read_all = adr * words / wpm          # 7200 words, so 48 minutes
index = adr * 12 / wpm                # 24 titles, 12 words per line, so 288 words, almost 2 minutes

asked, explain = 5, 15                # a newcomer re-asks 5 decisions, a senior explains 15 minutes each
without = asked * explain             # 75 minutes of the senior's time
with_adr = asked * words / wpm        # 5 ADRs x 2 minutes = 10 minutes of the newcomer's time
print(read_all, round(index, 2), without, with_adr)
# 48.0 1.92 75 10.0

newcomers = 4
print(newcomers * without, newcomers * with_adr)
# 300 40.0  (minutes per year)

Reading the result: reading all 24 ADRs takes about 48 minutes, reading just the list of titles takes almost 2 minutes, so nobody has to load everything. If each newcomer re-asks 5 decisions and a senior explains each for 15 minutes, that is 75 minutes of senior time per person, or 300 minutes a year with 4 newcomers. With ADRs, the newcomer reads the 5 records in about 10 minutes each, so 40 minutes a year.

To be clear: 300 words, 150 words per minute, 5 questions and 15 minutes are my assumptions. ADRs also take time to write and maintain, which is not counted here. Replace them with your own team's numbers.

---

4. The one-page template#

Picture a submission form: few fields, every field required, small enough to fill in ten minutes. The template below builds on Nygard's version and adds two fields borrowed in spirit from MADR (a condition to revisit and a way to confirm), so the decision has an exit and a check.

# ADR 0007: Send reminders through a queue

Status: accepted (proposed / accepted / superseded by ADR 00NN)
Date: 2026-03-12
Decided by: a name or a role

## Context
The situation and the constraints, stated as fact, no judgment. Who is waiting for what?

## Decision
We will (one or two full sentences, active voice)

## Options rejected
- Option A: why it was not chosen.
- Option B: why it was not chosen.

## Consequences
- Gain: the good things.
- Loss: what we accept to give up.
- Neutral: what only changes, neither good nor bad.

## When to revisit
A concrete condition that makes us reopen the decision.

## How to confirm
An automated check or an observable sign that the decision is still followed.

Three rules to stay on one page:

1. One ADR, one decision. If the title needs the word "and", it may be two decisions.
2. Full sentences in context and decision. Bullets are for short lists such as options and consequences.
3. Long detail goes elsewhere. Comparison tables, charts, experiment results: link to them, do not paste them in.

---

5. A worked example: a filled-in ADR#

This is an illustration, made up for this post, and does not mention a real company or product. The situation: a small app helps service shops book appointments and sends reminder emails. Every number in the example is invented.

# ADR 0007: Send reminders through a queue, not while handling the request

Status: accepted
Date: 2026-03-12

## Context
When a customer books, the app sends a confirmation email while handling the request.
The email service sometimes takes several seconds to respond and once failed for an hour.
During that time the booking page hangs, and some customers have clicked book twice.

## Decision
We will put email sending into a job queue. The booking request only writes the
appointment to the database and replies at once. A separate worker sends the email
and retries up to three times.

## Options rejected
- Send directly in the request: the simplest, but the page hangs when the service is slow.
- Scan the table every minute with a scheduled job: no queue needed, but emails are
  up to a minute late and the job scans a large table.

## Consequences
- Gain: the booking page responds fast, and an email failure no longer breaks booking.
- Loss: one more component to monitor, and emails may arrive a few seconds late.
- Neutral: the logs gain one more source to read when debugging.

## When to revisit
If for six months fewer than 50 emails a day are sent, or the email provider
offers a built-in queue.

## How to confirm
A test that makes sure the booking request does not call the email service directly.

The Y-statement version of the same decision: "In the context of booking appointments, facing an email service that is slow and fails often, we decided for putting the sending into a queue and against sending directly or scanning the table on a schedule, to keep the booking page fast, accepting one more component to monitor."

The full version is about 230 words, within the one-page target of about 300 words. The point to notice: the "Options rejected" section is what keeps people and AI from drifting back to the simplest option, because the simplest option is the one everyone thinks of first.

---

6. Write ADRs so that an AI agent can read and use them#

Picture leaving a note for the next person on call: the note only helps if it is stuck where that person will look.

1. Keep the ADRs in the repository, for example in a docs/adr folder, next to the code and its change history.
2. Have an index file that lists each ADR's title, status and path, one line each. The agent reads the index and opens the relevant record, so it does not load everything.
3. Point to it from the agent's instruction file. In AGENTS.md or the tool's instruction file, add a few lines like the block below.
4. Put the status on the first line, in fixed words (proposed, accepted, superseded), so both people and machines can filter.
5. Let a person write the first two parts. Context and decision are filled in by a person. AI can suggest rejected options or draft, but a reason that sounds plausible is not necessarily the real reason. A person confirms the reasons, in the spirit of the post Make AI Output Prove Itself.

## Existing decisions
- Before changing an approach already covered in docs/adr, read the index
  docs/adr/README.md and open the relevant ADR.
- If your change goes against an accepted ADR, stop and ask,
  do not edit it yourself.
- When you report done, say which ADRs you read.

Three lines, short enough for a person and an agent to read in full. The last line borrows the fourth way from the evidence post: separate what was read from what was assumed.

---

7. The life of an ADR#

The key point: do not delete the old record. Readers need to see both what we once decided and why we changed.

---

8. When not to write an ADR#

This is my own rule of thumb, not a standard from Nygard or MADR. Picture the kitchen bin: not everything needs its own notebook.

• Do not write one when the decision can be reversed in about an hour of work (renaming a variable, choosing a file name).
• Do not write one when the reason is already in the tool's standard documentation and anyone can look it up.
• Do not write one just to complete a procedure. An ADR nobody reads costs effort and helps nobody.
• Do write one when a newcomer is likely to ask "why is it like this?", when reversing the decision takes more than half a day, or when we just rejected an option that everyone will think of first.

---

9. Where ADRs fail too#

Picture the recipe book: some are thick and nobody opens them, some have been wrong for years.

9.1 Illustration: a morning with and without an ADR#

This is an illustration, not a real case, and it names no person or product. It reuses the example from section 5.

Without an ADR:

• 09:00. A dev asks the agent: "Tidy up the booking code, remove redundant parts."
• 09:20. The agent sees the email queue as an extra layer and changes it to a direct call. All existing tests pass.
• 11:00. The dev reads the diff, finds it reasonable and merges.
• 15:30. The email service is slow. The booking page hangs and a customer books twice.

With an ADR and AGENTS.md pointing to it:

• 09:00. The same request.
• 09:10. The agent reads the ADR index, opens ADR 0007 and says: "This queue is an accepted decision. I will not change it. Do you want to open a new ADR to replace it?"
• 09:20. The dev answers: "Keep it. Only tidy the other parts."
• 09:50. The agent submits the change and notes "read ADR 0007, did not touch the queue".

What to do in both cases: stop at the point where the agent wants to remove something that looks redundant and ask whether it had a reason. This is an illustration, so it proves nothing. The signal from the Stack Overflow survey (section 3) and Nygard's account only show that missing context is real and that a short record may help.

---

10. The numbers and documents used#

Read it correctly: the sources above support recording short reasons. I did not find a controlled study that measures whether ADRs reduce errors or help AI agents avoid reversing decisions. The AI parts of this post are a synthesis of practice.

---

11. Habits to apply from tomorrow#

11.1 Eight questions before finalizing an ADR#

1. Is this one decision, or two glued together?
2. Would a reader a year from now understand the context without asking anyone?
3. Does the decision start with "We will" and use full sentences?
4. Are the rejected options and the reasons for rejecting them written down?
5. Do the consequences include the losses and neutral effects, not just the gains?
6. Is there a concrete condition to revisit and a way to confirm?
7. Are the status and date on the first line, and is the index updated?
8. Does AGENTS.md or the README point to this ADR?

11.2 Three things to do right away#

1. Create a docs/adr folder and an empty index.
2. Pick one recent decision that newcomers keep asking about and write the first ADR in about 15 minutes.
3. Add the three lines from section 6 to your AI agent's instruction file.

---

12. A balanced view: what ADRs do and do not do#

What they do: keep the reasons, help newcomers find answers themselves, give an agent a place to check before editing, and force the team to name the loss in each decision.

What they do not do:

• An ADR does not guarantee the decision is right. It only records what we thought at the time.
• An ADR that is not kept current can do more harm than no ADR, because it states the wrong thing as in force.
• An agent is not obliged to read ADRs, and I have not seen a test that measures how well it follows them. Check by asking the agent to report which ADRs it read.
• ADRs take effort to write and maintain. For a very small team or a short project, one sentence in the README may be enough.
• A reason drafted by AI can sound fluent without being true. A person needs to confirm it.

Do not oversell it: an ADR does not replace communication in the team. Do not dismiss it: the cost of a lost decision usually arrives at the end, when someone reverses it because nobody knew it once had a reason.

---

13. Conclusion#

Code shows what we did, an ADR shows why. One short page, written at decision time, including the options we dropped and what we accept to lose, with a path from where people and AI will read, is enough to keep many decisions from being reversed just because nobody knew they had a reason. Start with a decision that newcomers keep asking about.

---

References#

The numbers come from public sources as of October 2026. Some figures were read through a summary, so open the original sources to check before quoting.

• Michael Nygard, Documenting Architecture Decisions (Cognitect, 15 November 2011)
• Architectural Decision Records, adr.github.io and MADR (version 4.0.0)
• Olaf Zimmermann, Y-Statements (the one-sentence ADR pattern)
• Stack Overflow, 2026 Developer Survey (read through a summary, tables not cross-checked)