Decision Log and ADR: Why Yours Died and How to Keep One Alive

A decision log dies the same way every time. It starts as a clean folder of architecture decision records, gets written carefully for two months, and then goes quiet. Nobody updates it because nobody trusts it, and nobody trusts it because the one fact that mattered - why - was never written down, or was written down and then drifted out of date. The fix is not more discipline. It is capturing decisions where they actually happen and letting the record evolve with a diff, so the log stays alive without anyone babysitting it.

This is a how-to. Below: what a decision log and an ADR really are, why both rot, the format that holds up, and how to keep one a team of twenty will still open in a year.

What a decision log and an ADR actually are

A decision log is a running record of the choices a team made, why, and when. An architecture decision record (ADR) is the same idea with a tighter scope and a fixed shape, popularized by Michael Nygard in 2011: one short document per architecturally load-bearing decision, with a status, the context, the decision, and the consequences. The log is the practice; an ADR is one entry in it.

The format is deliberately small. Here is the canonical skeleton.

The discipline that makes the collection trustworthy is one rule: you do not edit an accepted ADR. If the conclusion changes, you write a new one that supersedes the old and flips its status. Six months later you can read ADR-0007 and know exactly what was true the day it was written. The truth of your architecture is the full chain, not the latest entry. That is the whole point, and it is also the thing most teams quietly abandon first.

Why decision logs and ADRs go stale

They do not die from laziness. They die from three structural problems that no amount of "we should really keep this updated" ever fixes.

The why never gets captured

Most logs record what was decided and skip why. "We moved auth to a separate service." Fine. But the three constraints that forced it - a vendor contract, a latency ceiling, a single engineer who knew the old flow - are the only part that matters when someone asks the question again in a year. A record without its rationale is a fact with no half-life. The moment circumstances shift, nobody can tell whether the decision still holds, so they re-litigate it from scratch.

The log lives where nobody decides

Real decisions happen in a Slack thread at 4pm, in a Linear comment, in the third reply on a pull request, in a hallway and then a coding-agent session. The log lives in a wiki nobody opens. So the engineer closest to the decision, with the freshest context, has to stop, switch tools, and translate a live argument into a formal document at exactly the moment they want to ship. The friction wins. The decision ships; the record does not.

The maintenance burden lands on the wrong person

The people who could keep an ADR current are the ones who made the original call, and they have moved on. The person who eventually trips over the stale record is the new joiner, who has the least context and the least authority to change it. So the burden falls structurally on whoever knows the least. The repository turns archaeological, and new decisions get made without anyone checking it, which is how two services end up enforcing contradictory invariants nobody chose on purpose.

A decision log that goes stale is worse than none. It looks authoritative and lies.

How to keep a decision log a team actually uses

Four rules. The first two are about where the record lives. The last two are about how it changes.

Capture from where decisions happen

Stop asking people to author decisions in a second place. Capture them from the surface where the decision was actually made - the Slack thread, the Linear ticket, the PR description, the coding-agent transcript - and let the log assemble itself from that signal. The fix that pulls most failing ADR practices back from the dead is moving the record next to the work instead of off to the side. If your engineers have to leave their flow to log a decision, you have already lost the ones made under deadline, which are the ones you most need recorded.

This is the design behind Ody. It reads the surfaces a team already uses and stitches scattered signal into the work it belongs to, so a decision argued across a Slack thread and a Linear comment becomes one record, without anyone writing a doc. The same idea runs through the week-in-one-team story: the record is a byproduct of working, not a second job.

Keep the entry small

If your log has more than about ten fields, nobody fills it out. The Nygard skeleton survived fifteen years because it fits on one screen. Resist the urge to add owner, reviewer, risk score, and quarterly tags. A decision with its context and its reason beats a decision with twelve empty metadata columns. Capture the why; let the rest be optional.

Let it evolve with a diff, not an edit

Here is where the immutable-ADR rule and a living log finally agree. You do not overwrite the old decision. You write the new state and keep the old one, linked, with the reason and the date the direction changed. Done by hand, that is the superseding-ADR discipline. Done well, it is a before-to-after diff you can read in ten seconds: this was the call, this is the call now, this is why it changed, and this is when.

That diff is what a team of twenty needs. Not a museum of accepted records, and not a wiki page someone silently rewrote so the history is gone. A decision that carries its own change history is one you can trust without asking the person who made it, which matters most when that person has left. This is the heart of a decision log that doesn't rot: the record changes, but the change is visible, dated, and reasoned. We go deeper on the mechanics in change, not conflict.

Make agents read from the same record

A decision log used to be for humans. Now your coding agents act on the same architecture, and they will happily contradict a decision they cannot see. Keep the record where both can reach it. Ody is callable over MCP, so Claude Code and Cursor read the team's decisions directly before they write code, instead of cheerfully reinventing the reason you picked Postgres last quarter. A decision log that only humans can read is half a log on an AI-native team.

A quick test for your current log

Open it. Pick the three most load-bearing decisions of the last quarter. For each one, can you answer, without asking anyone: what changed, why, and when? If you can, your log is alive. If you are reaching for Slack search, it is already archaeology, and the next person to make that call will make it blind.

A decision log is not paperwork. It is the difference between a team that compounds what it learns and one that re-argues the same three questions every quarter. Capture from where decisions happen, keep the entry small, and let it evolve with a visible diff. That is a log people open.

If you want to see a decision log that assembles itself and carries its own diffs, book a demo or join the waitlist.