Blog · 2026-06-05 · ~8 min read

ADR vs Decision Log vs RFC: when to use each

Q: Can we use a single 'Proposed' ADR as both the proposal and the record?

Some teams do this — file it as an ADR in 'Proposed' status, invite comments via PR, accept via merge. It works well for small teams and avoids the two-document overhead. The downside: 'Proposed' ADRs accumulate and make the accepted ADR list harder to scan. A dedicated RFC format keeps the proposal noise out of the permanent record. Pick the single-document path if the overhead of two documents genuinely kills the practice; use two documents if your team is large enough that the audit trail between proposal and record matters for onboarding.

If you've spent any time on engineering culture blogs, you've encountered all three terms. They're used interchangeably in some organisations, layered carefully in others, and actively confused in most. The confusion is reasonable — they're all artifacts about decisions, produced by people who care about institutional memory. But they do three distinct jobs at three distinct points in a decision's life, and conflating them is why so many documentation practices die quietly at 60 days.

TL;DR

RFC is a pre-decision proposal: you haven't decided yet and you want input. ADR is a post-decision permanent record: the decision is made, the context is captured, the document is immutable from here. Decision log is a collection artifact: it holds the ADRs plus the lighter, non-architectural decisions that don't warrant the full format. The fourth thing none of the three handles — the informal decisions made in AI chat — is where the gap actually lives, and the rest of this essay walks through why each artifact exists and how they fit together.

Three jobs, not three names for the same thing

The cleanest way to separate RFC, ADR, and decision log is by timing and scope:

RFC (Request for Comments) — the proposal. A document that describes a decision you're considering and invites input before anything is committed. Its job is to surface objections and alternatives you haven't thought of. It's open, forward-looking, and incomplete by design — you don't know the answer yet.
ADR (Architecture Decision Record) — the record. A document that captures a decision already made, plus the context that motivated it, the alternatives that were rejected, and the consequences of the choice. Its job is to answer "why did we do it this way" when the original author has left or forgotten. It's closed, backward-looking, and complete — the decision is done.
Decision log — the ledger. A broader collection artifact. It can be a spreadsheet, a database, a folder of ADRs, or an automatically generated list. Its job is to make all the decisions in a system findable in one place. It's neither open nor closed; it's a container, not a document.

The confusion starts because ADRs are often kept in a directory that looks like a "decision log" — and they can be. But "decision log" frequently refers to something lighter than ADRs, covering decisions that don't meet the threshold for full ADR treatment. The two concepts overlap but aren't equivalent. Treating them as synonyms is what produces systems where some entries are 800-word formal records and others are a single sentence, in the same directory, with no clear convention for which shape applies when.

RFC: the proposal

An RFC is the right artifact when:

The decision affects more than one team
You need to surface technical alternatives you might have missed
The decision is reversible enough that input could actually change the outcome
You want a paper trail showing the decision was consulted, not just announced

An RFC is the wrong artifact when the decision is urgent, purely local to one team, or when "RFC" is being used as a word for "announcement" — a document that presents a fait accompli with a polite "any thoughts?" appended. This is common in organizations where the RFC process has been cargo-culted from somewhere that used it well. An RFC that no reviewer could plausibly influence isn't an RFC; it's a notification with extra steps, and engineers who've seen this pattern will stop reading them.

The format for an RFC is looser than for an ADR. A minimal RFC has: Background (the situation and why it requires a decision), Proposal (what you're considering), Alternatives already rejected (so reviewers don't re-litigate what you've already thought through), Open questions (what you genuinely don't know), and a Review deadline. The deadline is essential. Without it, the RFC becomes a discussion that never closes, which is worse than no RFC — unresolved proposals accumulate, reviewers stop engaging because "it'll resolve itself," and the decision gets made implicitly anyway, just without the paper trail.

The RFC-to-ADR handoff is the step most teams miss. An RFC that closes with a decision made should produce exactly one ADR. The ADR's Context section is the RFC's Background plus the summary of what the review surfaced. The ADR's Alternatives section is richer than the RFC's — it now includes options commenters raised that weren't in the original proposal. The RFC itself gets linked from the ADR as the consultation audit trail. This handoff is the highest-leverage documentation habit an engineering team can build. The RFC-vs-ADR disambiguation page has the format comparison in detail.

Teams that run RFCs well have exactly this handoff. Teams that run them poorly close the RFC, ship the decision, and never write the ADR. Six months later they have thirty closed RFC documents nobody reads and no institutional memory of what actually happened.

ADR: the record

An ADR is the right artifact when:

A technical decision will still matter in 12+ months
A new engineer joining the team would reasonably ask "why did we do it this way?"
The decision involves a trade-off that the choice alone doesn't communicate — "picked Postgres" is not an ADR; "picked Postgres over MongoDB because we specifically needed ACID transactions and the ops team already knew Postgres" is the load-bearing information an ADR should preserve

An ADR is the wrong artifact for purely local, reversible implementation decisions. Naming a variable, picking between two equivalent patterns in an existing convention, choosing a CSS class name — none of these warrant an ADR. The test is forward-looking: would a future engineer reading the codebase be better served by a written rationale, or would they correctly infer it from context? If the answer is "they'd infer it," skip the ADR.

The defining property of an ADR is immutability. Once an ADR is accepted, its Decision field should never be edited — the decision it records is historical fact. If the decision is later reversed, a new ADR supersedes the old one. The old record stays in the repo forever with Status: Superseded by ADR-0042. This immutability is the source of the ADR's value: any reader can find the original rationale even if the decision was reversed, which is exactly what makes it useful during an audit, a migration, or a new-CTO onboarding. A "decision document" that gets edited to reflect current thinking isn't an ADR; it's a wiki page, and wiki pages don't preserve the reasoning that led to the original choice.

The minimal ADR — the Nygard format — has five fields:

Title — the name of the decision in active voice ("Chose BullMQ for job dispatch")
Status — Proposed / Accepted / Deprecated / Superseded
Context — the forces at play, why this decision needed to be made now
Decision — the choice made, in one active-voice sentence
Consequences — what becomes easier, what becomes harder, what new decisions this creates

That's the floor. MADR (Markdown Any Decision Records) adds a YAML frontmatter block and a structured Alternatives section if you need machine-parseable output for a CI lint step or a Log4Brains publication layer. Neither format is wrong; MADR is better if you'll ever build tooling on the corpus. The worked Postgres-vs-MongoDB ADR example shows either format on a familiar decision.

One practical note on ADR granularity: when a team has accumulated 100+ ADRs, the common failure is adding records that cover implementation rather than architecture. At that scale, granularity becomes noise and engineers stop reading the corpus. The 3+1 rule gives a useful threshold: document it if the decision will outlast the author, affects the team's ability to make future decisions, or someone will definitely ask "why" in the next 12 months. Below that bar, don't write it.

Decision log: the broader collection

"Decision log" is the most overloaded term of the three. It appears in three distinct contexts:

1. Engineering ADR collections. Some teams call their /doc/decisions/ directory a decision log — accurate, but it conflates the collection (the log) with the artifact (the ADR). The log is the folder; the ADR is the document. The distinction matters when the team debates whether a given call is "worth an ADR" — the real question is whether it's worth putting in the log at all, and ADR-format is the specific shape for the high-bar entries.

2. Product and business decision tracking. "Decision log" here usually means a spreadsheet or lightweight database that captures pricing changes, feature-flag flips, rollback decisions, vendor selections, and hiring calls alongside architectural ones. This is broader than ADRs. It doesn't share the immutability property — a pricing decision can be edited when the price changes; the history is still in git or version history. The job of this log is discoverability across decision types, not permanent immutable record-keeping. The decision log template shows this lighter format.

3. Automatic extraction output. The newest and fastest-growing usage: run a decision extractor over AI chat history, and the output is a decision log — every detected decision, structured, with alternatives and rationale, indexed by date. This log isn't curated like a hand-picked ADR corpus. It includes rough calls alongside architectural ones, and the triage pass is the human job. The value is in completeness: it surfaces decisions that would otherwise be invisible, regardless of whether they rise to ADR level.

The right model for most engineering orgs is a decision log as a superset of the ADR repository:

ADR repository (/doc/decisions/) — formal, immutable, hand-curated, architectural-only. The decisions that must survive staff turnover. Typically 5–15 new ADRs per quarter per team.
Decision log (broader) — includes the ADRs plus product decisions, rollback calls, vendor selections, "we chose not to build X" records that are worth knowing but not worth full ADR ceremony. Typically 20–50 entries per quarter, lighter format.

The decision log's job is discoverability. The ADR's job is immutable authoritative record. They're complementary, not competing.

The fourth type nobody talks about

Here's the practical gap that RFC/ADR/decision log practice doesn't address: most decisions don't get written into any of the three.

In a team of five engineers at a 10-person startup, the architect might write 10 ADRs per quarter if the practice is healthy. Per the ADR staleness data, health is rare — 38 of 40 ADR practices stall inside three months. Even in healthy teams, 10 formal ADRs per quarter represents 5–10% of the durable decisions actually made in that window. The rest are made in AI chat.

Claude and ChatGPT sessions are the new whiteboard. The reasoning happens there, the alternatives get explored there, and the rejected options are named explicitly — often in more detail than any hand-written ADR would capture, because the engineer is thinking out loud and the model is asking follow-up questions. The decision gets made. The chat stays in history, readable and searchable by the engineer who was there — but not visible to the team, not indexed in the repo, not findable when the new engineer asks "why did we pick this" six months later. Per the new-CTO scenario: the answer to "why did we pick Postgres?" is in someone's Claude session from fourteen months ago. It's there. It's just not surfaced.

The open-source extractor is the tool that bridges this gap. It runs against a ChatGPT export or a Claude export and emits decision records — each one in the five-section ADR shape, each one with the alternatives that were named and the reasons they were rejected. The output isn't a replacement for hand-written ADRs; it's the tier-1 decision log that catches everything the ceremony-dependent tier-2 misses. Most of what it surfaces won't warrant promotion to the formal ADR repository — but it becomes findable, which is 80% of the value.

Quick-reference: which artifact for which situation

Artifact	Timing	Scope	Immutable?	Best for
RFC	Pre-decision	Multi-team, reversible, cross-boundary	No — it's a live proposal	Surfacing alternatives, documenting consultation, cross-team alignment
ADR	Post-decision	Architectural, durable, multi-engineer impact	Yes — never edit the Decision field	"Why did we do this?" at staff turnover, migrations, audits
Decision log	Ongoing	Broad — architecture + product + operations	Typically no — entries are updated	Discoverability, quarterly review, non-architectural decisions
Chat extraction	Retroactive (quarterly)	All informal decisions in AI sessions	Yes (read-only source)	Recovering decisions that weren't written up; feeding the decision log

A practical decision tree if you're building the system from scratch:

Does this decision affect more than one team, AND could input change the outcome? → Write an RFC. Set a review deadline (5–10 days). Close with a decision.
Has a decision been made that is architectural, durable, and would cause a future engineer to ask "why"? → Write an ADR (either after the RFC, or directly for single-team decisions that skip the RFC). Reference the RFC if one exists.
Is this decision worth logging but not worth a full ADR? → Add a lightweight entry to the decision log. One or two sentences, date, who made the call, what was rejected.
Did this decision happen in an AI chat session without any of the above? → Quarterly extraction pass. Triage the output. Promote any records that meet the ADR bar; keep the rest in the decision log as findable context.

Putting it together: the layered practice

The teams with the most durable institutional memory don't use just one artifact — they run a layered stack. RFCs catch decisions before they're made and make the consultation auditable. ADRs preserve the load-bearing architecture calls in a repository that survives staff turnover. A lightweight decision log captures the second tier of decisions that don't rise to ADR level but are still worth knowing. Quarterly chat extraction surfaces the 80% of decisions that happened informally in AI sessions and would otherwise be invisible.

The common failure mode is using one artifact for all four jobs. RFCs used for every decision become bureaucracy and reviewers stop reading them. ADRs that cover every implementation detail become noise and the corpus becomes unscannable. A decision log with 300 entries is harder to triage than one with 40 curated ones. The trick is matching the artifact to the job: RFC for pre-decision consultation, ADR for post-decision permanent record, decision log for the broader everything-findable requirement, extraction for the decisions the ceremony would never have caught.

The RFC-to-ADR handoff is the highest-leverage habit an engineering team can build: close every RFC with an ADR that references it. The quarterly chat extraction is the highest-leverage habit an individual engineer can build: run the extractor on your own history once per quarter, promote the 3–5 records that rise to ADR level, and keep the rest in your personal decision log. Together they close the gap between "we care about decision history" and "our decision history is actually findable."

Without chat extraction, the best-maintained ADR corpus covers roughly 10% of the real decisions the team made — the ones that were formal enough to warrant the ceremony. With extraction, coverage jumps to 70–90%. The difference is not a cultural shift or a process overhaul; it's a 30-minute quarterly habit and a small Node script that you can read in full before running it. The adr-tools vs WhyChose comparison goes into when you need both and when one layer is enough.

Try the extractor on your own export. The open-source extractor takes a ChatGPT or Claude conversations.json and emits decision records to JSON, JSONL, or Markdown. ~500 lines of dependency-free Node, MIT-licensed, runs locally. Or join the waitlist for the hosted version with team sharing, search, and Notion / Linear export.