ADRs or a decision log: which one a small product team needs
ADRs hold technical decisions agents must follow; a decision log holds product calls made in Slack. See them side by side, and make both agent-readable.
On this page
Most small product teams need both, because they serve different readers. An architecture decision record (ADR) captures a technical decision that the code, and the coding agents writing it, must follow, and it lives in the repo. A decision log captures product calls (scope, priority, what ships to whom) that are usually made in a Slack thread, and it lives where the team talks. If you can only keep one current, keep the one whose decisions get reopened more often on your team.
The reason this question matters more now is the thesis behind this blog: AI-native teams create context faster than people can sync, manage or remember it. When agents open PRs all day and plans change mid-week, a decision that only exists in someone's head or a buried thread is gone by the next session. Both formats are ways of writing a decision down once, in a place the next reader (human or agent) will actually look.
What is an architecture decision record?
An ADR is a short document about one technical decision: what problem you faced, what options you considered, what you chose, and what follows from the choice. The MADR template (Markdown Architectural Decision Records) is a widely used format, and it structures each record around context, considered options, the decision outcome and consequences. The community ADR repository collects several other templates and examples if you want to compare formats.
Two properties make ADRs useful for agents. They are plain markdown files, so they sit in the repo next to the code. And they are written as one decision per file, so a reader can load the one that applies instead of a long design document.
Typical ADR topics: which queue library to use, how services authenticate, where state lives, what the module boundaries are. The reader is an engineer, or an agent, about to touch that area.
What is a decision log?
A decision log is a running list of decisions, usually one row each, with a date, an owner, a short statement and a status. Templates from ProjectManager and Lucid show the general shape. It is lighter than an ADR: no options analysis unless the call was contested.
It fits product calls: cut this feature from the launch, ship to the design partner first, pause the pricing page. These decisions rarely start in a document. They start in a thread, and the log is the place where someone writes down what the thread concluded. We cover a Slack-first version in a decision log template for Slack.
How do ADRs and a decision log compare?
The table below is a reusable way to decide which one a given decision belongs in.
| ADR | Decision log | |
|---|---|---|
| What it records | A technical decision with context, options and consequences | A product or process call with date, owner, status |
| Typical example | Use one queue library across services | Launch to design partners before general release |
| Where it lives | In the repo, as a markdown file per decision | A shared doc, table or pinned page, linked to the Slack thread |
| Who writes it | The engineer or agent session that made the choice, reviewed in a PR | Whoever closed the thread, or the product lead |
| Who reads it | Engineers and coding agents about to change that area | Product, design, marketing and engineering leads |
| How long it is | One page, one decision | One row, one to two sentences |
| How it goes stale | Code changes and nobody updates or supersedes the record | A later thread reverses the call and the log is never touched |
| How an agent can use it | Read it from the repo as a constraint before writing code | Read it only if the log is also in the repo or pasted into context |
| Best trigger to write one | A choice that is costly to reverse | A call that someone will ask about again in two weeks |
How do both of them go stale?
Both fail the same way: the world moves and the record does not. An ADR goes stale when the code changes without a new ADR that supersedes the old one. A log goes stale when a later Slack thread quietly reverses a call.
The rate of change is the real issue. On our own team, Biddle's record holds 448 decisions decided between September 1 and October 3, 2026, and 13 of them were superseded by a later decision (an observation about one team over about a month, not a benchmark). A decision is not a fixed thing; it gets replaced. Whichever format you pick, give it a status field and make superseding a normal move, not an edit-in-place.
When does each one fit?
Choose ADRs when the decision constrains code
If a decision tells an engineer or an agent how to write something, it belongs next to the code. Imagine an agent that adds a second queue library to a service because it never saw that the team chose one. An ADR in the repo, referenced from the agent's instructions, is the cheapest guard against that. This is also where Liouville uses ADRs: for technical decisions that agents must follow.
Choose a decision log when the decision is about the product
If a decision is about scope, sequencing or who gets what, the readers include people who never open the repo. A log in a shared place, with a link to the original thread, keeps design, marketing and engineering from believing different plans. Liouville uses a log for product calls.
Choose both when agents ship product work
Product calls turn into code constraints. A log entry that says "design partners first" may need an ADR for the feature-flag approach that implements it. Link the two: the ADR cites the log row, and the log row cites the ADR and the implementing PRs. If you only have one, add the missing link as a line of text.
How do you make either one readable by coding agents?
Agents forget between sessions, so a decision they cannot find does not exist for them. A few habits help, and none need special tooling.
- Keep ADRs in a predictable folder in the repo (for example docs/adr), one decision per file, named with a number and a short title.
- Put the rule first. Start the decision section with a one-line imperative an agent can obey, and keep the reasoning below it.
- Use a status field (proposed, accepted, superseded by a number) so an agent does not follow an old choice.
- Point your agent instruction file (the one your coding agent reads at session start) at the ADR folder, and say to check it before changing architecture.
- For product calls, keep the log as a markdown file in the repo or paste the active rows into the agent's context. A log in a tool the agent cannot read helps people only.
- Always include a permalink to the source thread and the implementing PR numbers, so the claim can be checked.
An illustration with sample data, showing an ADR header an agent can act on:
# ADR 0014: Use one queue library across services
Status: accepted (supersedes ADR 0009)
Rule: New background jobs use the shared queue client. Do not add another queue library.
Source: Slack thread (permalink), decided 2026-09-12
Implemented in: PR 412, PR 418An illustration with sample data, showing two decision log rows:
2026-09-12 | Ship to design partners first | owner: product lead | active | thread permalink | PR 421
2026-09-20 | Pause the pricing page | owner: product lead | superseded by 2026-09-27 | thread permalinkFor a deeper look at what happens when merged code contradicts a decision like these, see plan drift.
Where does Biddle fit?
Biddle does not replace either format. It reads GitHub and Slack (the only sources today; Linear and Notion are coming, not integrated), keeps a record of decisions with links back to the PR or thread, and puts what needs a decision in front of the leader in a weekday briefing. You can see how that works in how it works. It is in early access and runs every weekday for Liouville's own team, and Biddle is learning to flag a merged PR that contradicts a decision. If you are choosing between ADRs and a decision log because nobody has time to maintain either by hand, you can request early access to Biddle.
Common questions
Can a small team skip ADRs and only keep a decision log?
Yes, if most of your hard calls are product calls and your code is small enough that agents rarely need architectural constraints. Add ADRs the first time an agent or new hire reverses a technical choice by accident.
Should ADRs be in the repo or in a wiki?
In the repo, if coding agents are part of your workflow, because that is where they read. A wiki copy is fine for people, but treat the repo file as the source of truth.
How heavy does an ADR template need to be?
Not very. A short context, decision and consequences, plus a status field, is enough. Heavier formats like MADR are optional; use the parts you will actually fill in.
Read next
- Decisions lost in Slack threads: a decision log template: a one-row-per-decision template with permalinks and superseded status.
- Plan drift: when a merged PR quietly undoes a team decision: what happens when code and decisions diverge, and a three-step check.
- Keeping an AI-native product team on the same page: a shared record of changes and decisions, plus a weekly rhythm.
Want this in your Slack?
Biddle reads your GitHub and Slack and sends you a briefing each weekday morning, with every claim linked to the PR or thread behind it. We’re onboarding a few product teams now, and we set each one up with you.
Request early accessRelated posts
Decisions lost in Slack threads: a decision log template
A decision log template for Slack: one row per decision with thread permalink, implementing PRs and superseded status, plus a one-minute capture habit.
Plan drift: when a merged PR quietly undoes a team decision
Decision drift is when merged code quietly contradicts a team decision. See how it happens and run a three-step drift check this week, no tooling needed.
What is an AI chief of staff for product teams?
What an AI chief of staff for product teams does, how it differs from email assistants and exec dashboards, and how to tell whether your team needs one.