What is the difference between a decision log and an ADR?

An ADR is one document per architecture decision, stored in the code repository, with context, the decision, its status, and its consequences. A decision log is a single running list of decisions of any kind, product, process, or technical, kept where the whole team can read it. ADRs go deep on few decisions; a decision log covers many decisions briefly.

Is a RAID log the same as a decision log?

No. A RAID log tracks Risks, Assumptions or Actions, Issues, and Decisions or Dependencies for one project, and the project manager usually reviews it weekly. Its decisions section is project-bound and usually ends with the project. A decision log is meant to outlive any single project.

Is a changelog a decision record?

No. A changelog lists notable changes per release for the people using the software: what was added, changed, deprecated, removed, fixed, or patched for security. It records what changed, not why the team chose it or what it rejected.

Can a team use a decision log and ADRs together?

Yes, and most growing teams should. Keep ADRs for architecture decisions engineers own, and a decision log for product and cross-team calls. Link an ADR from the decision log entry it relates to, so nobody has to search two places.

Where should a product decision go?

In the decision log. A product decision such as cutting a feature from v1 or changing a pricing rule affects people outside engineering, so it belongs in a record product, design, and engineering all read. If it changes the architecture, add an ADR and link the two.

Decision log vs ADR (vs RAID log and changelog)

A team decides to cut single sign-on from version one. The product lead wants it written down. Engineering has an adr/ folder in the repo. The project manager keeps a RAID log in a spreadsheet. The release notes will eventually need to say something too.

So where does "no SSO in v1" go? The honest answer is that these four records do different jobs, and the decision may belong in one of them, two of them, or none. This guide compares them side by side and gives a simple test for each decision.

Decision log vs ADR vs RAID log vs changelog

The four records differ mainly in scope and reader. An ADR goes deep on one technical decision for engineers. A decision log covers many decisions briefly for the whole team. A RAID log manages one project. A changelog informs users.

	ADR	Decision log	RAID log	Changelog
Records	One architecture decision	Many decisions of any kind	A project's risks, assumptions, issues, decisions	Notable changes per release
Main reader	Engineers	Product, design, engineering, leadership	Project manager and project team	Users of the software
Unit	One document, one to two pages	One entry, a few lines	One row per item	One section per version
Answers	Why is the system built this way?	What did we decide, and why?	What could stop this project?	What changed in this version?
Lives	In the code repository	A shared doc, wiki, or tool	A spreadsheet or PM tool	A file in the repo, or release notes
Lifespan	As long as the code	As long as the decisions apply	Usually the project	Forever, appended per release
Typical owner	The engineer who made the call	Whoever owns each decision	The project manager	Whoever ships the release

What an ADR is

An Architecture Decision Record is a short document that captures one architecturally significant decision. Michael Nygard proposed the format in a 2011 post, and it has barely changed since.

Each ADR has five parts:

Title: a short noun phrase.
Context: the forces at play, described neutrally.
Decision: what the team will do, in active voice.
Status: proposed, accepted, deprecated, or superseded.
Consequences: what follows, good and bad.

Nygard suggested keeping them in the repository as numbered files, such as doc/arch/adr-001.md, and keeping each one to one or two pages. When a decision is reversed, the old ADR is not deleted. It is marked superseded and points to the new one.

What counts as architecturally significant? Nygard's list: decisions that affect structure, non-functional characteristics, dependencies, interfaces, or construction techniques. "Use Postgres, not DynamoDB" qualifies. "No SSO in v1" usually does not. For the full template and when to write one, see the ADR guide.

What a decision log is

A decision log is a running, dated list of the calls that constrain future work: what was decided, why, what was rejected, and who owns it. It is one document or table, not one file per decision.

A decision log takes decisions an ADR would never hold. Product scope, pricing rules, process changes, a customer exception, a deadline trade-off. The format is deliberately light: an entry can be four lines. That lightness is the point. A record that takes ten minutes to write gets written; one that takes an hour mostly doesn't.

The weakness is the same lightness. A decision log rarely captures consequences in depth, and without an owner it stops being filled within a quarter. For the four fields every entry needs, see the engineering decision log.

What a RAID log is

A RAID log is a project management register. RAID stands for Risks, Assumptions or Actions, Issues, and Decisions or Dependencies. The letters vary by team. According to Asana's guide, the project manager usually owns it, the whole team contributes, and it is reviewed in weekly status meetings and updated whenever a new risk, issue, or key decision comes up.

The "D" overlaps with a decision log, but the purpose is different. A RAID log exists to keep one project on track. Its decisions are the ones that unblock that project, and the log is usually archived when the project ends. A decision about how invoices are rounded should not disappear because the billing migration project closed.

What a changelog is

A changelog is, in the words of Keep a Changelog, a curated, chronologically ordered list of notable changes for each version of a project. Its readers are the people using the software. Its standard categories are Added, Changed, Deprecated, Removed, Fixed, and Security.

A changelog is not a decision record. It says "Removed: CSV export for free plans." It does not say who decided, why, or what else was considered. It is where a decision becomes visible to users, not where it is kept.

Which one does a decision belong in?

Ask four questions in order. A decision can pass more than one.

Does it change the system's structure, interfaces, dependencies, or quality attributes? Write an ADR.
Does it constrain future work for people beyond the person who made it? Add it to the decision log.
Does it unblock or change the risk of a current project? Add it to that project's RAID log.
Will users notice it in a release? Note it in the changelog when it ships.

Applied to a few real decisions:

Decision	ADR	Decision log	RAID log	Changelog
No SSO in v1	No	Yes	Yes, as a scope decision	Later, when SSO ships
Move sessions from cookies to signed tokens	Yes	Yes, one line linking the ADR	Only if it affects a project	If users must log in again
Free plan capped at 3 projects	No	Yes	Yes, during the pricing project	Yes
Use an external vendor for tax calculation	Yes	Yes	Yes, as a dependency	No
Weekly release train on Tuesdays	No	Yes	No	No

The decision log appears in every row. That is the real difference: it is the one record broad enough to hold every decision that constrains future work. ADRs, RAID logs, and changelogs each hold a slice of it.

Use them together

Most teams past twenty people need at least two of these: ADRs for engineering, a decision log for everyone. The pattern that works is to link instead of copying. A decision log entry for an architecture call is one line plus a link to the ADR. A RAID log decision points to its decision log entry. A changelog line can link to the decision behind it.

That way the full reasoning lives in one place, and every other record stays short.

Where all four fall short

All four records share one failure: they are written but not read at the moment it matters. An engineer starting a feature does not open the RAID log. A product manager does not browse the adr/ folder. An AI coding agent reads the repository, so it can see ADRs if something points it there, but it cannot see a decision log in a wiki at all.

This matters more now that agents write a growing share of code. A decision that sits in a log nobody consults reaches neither the people nor the agents building against it. For how ADRs work as agent context, see ADRs for AI coding agents.

Where Lockstep fits

Lockstep is a decision log that goes to the reader instead of waiting for one. It captures decisions from PRDs, Slack, and pull requests, and each becomes binding when its owner approves it. Approved decisions brief Claude Code at the start of a session, and any MCP agent can query them mid-session. When a decision is replaced, the old version stays visible as replaced, the same idea as a superseded ADR.

It does not replace ADRs, RAID logs, or changelogs. Keep ADRs in the repo for deep architecture reasoning, keep the RAID log for project management, and keep the changelog for users. Lockstep holds the decisions that need to reach people and agents before they build. Session briefings work with Claude Code today. See how it works.

Sources checked 4 November 2026

For the ADR template in full, read the ADR guide. For a decision log you can start today, use the decision log template. To compare tools, see the best decision log tools for product and engineering teams.

Frequently asked questions