Architecture decision records (ADRs) are a well-known technique for keeping the reasoning behind a decision. As I recall, the common format (popularized by Michael Nygard) has a title, status, context, decision and consequences. That works well for decisions a team will live with for years. I’ve been thinking about a much lighter version for something smaller: a single working session, where the “next reader” is you after a break, a teammate picking up the branch, or an AI assistant starting a fresh session.
Here’s how I’d map the full format to five lines (this is my own adaptation, not a standard):
| Full ADR field |
ADR-lite line |
Note |
| Title + Decision |
Decision: one sentence |
“Retry in the gateway, not the client.” |
| Context |
Reason: one sentence |
Why this and not the obvious alternative |
| Consequences / alternatives considered |
Rejected: what you ruled out, and why |
The line most summaries lose |
| (Often missing) |
Open: what’s still undecided |
Keeps unknowns from looking settled |
| (Not in ADR) |
Next: the next concrete step |
For resuming work |
| Status |
dropped |
Supersede or delete the old entry instead |
An example, hypothetical (from a refactor scenario I wrote about, not a real project):
Decision: Retry in the gateway, not the client.
Reason: Gateway can see which requests are safe to retry.
Rejected: Client-side retry (some requests are unsafe to repeat).
Open: How to mark requests as safe to retry.
Next: Update integration tests for the gateway path.
Why “Rejected” matters most: the code shows what was chosen, not what was ruled out. A rejected design leaves no trace in the repository, so it tends to get proposed again, and then argued again.
A test for whether to write one: could someone reasonably propose the opposite later? If not, skip it.
Where the lighter version loses something:
- No “status” means you have to keep the log current yourself. A stale entry that confidently says the wrong thing is worse than none.
- Five lines can’t carry a decision with a long list of trade-offs. That’s what a full ADR is for.
- It’s only useful if the next reader actually reads it. A record nobody opens is just overhead.
For teams already using ADRs: do you have a lighter format for day-to-day decisions, or do small decisions just live in PR descriptions and chat?
I wrote about this with three claims and the strongest objection to each. I’m the author, and the article ends with two resources of mine on AI sessions (one free, one paid), so treat the link as optional: https://medium.com/@nagatomopedro05/what-a-session-summary-forgets-three-claims-three-objections-dc35b96909d2