Every project accumulates decisions that seemed obvious at the time and mysterious eighteen months later. We keep a running log of them specifically because the moment they stop being obvious is always well after the person who could explain them has moved on.
What goes in it
Not every decision — a log of everything is a log nobody reads. We record the ones where a reasonable alternative existed and was rejected for a reason that will not be visible from the code itself: why a queue is separate from the main database, why a particular table is denormalised against the usual convention, why an integration is polled rather than subscribed to.
The format that gets used
One entry per decision: the situation, the options that were seriously considered, the choice, and the reason. No more than a short paragraph. A log entry that takes ten minutes to write and three minutes to read gets written and read. A log entry that takes an hour to produce properly gets skipped under deadline pressure, which is precisely the condition under which the decision it would record is most likely to be forgotten.
Why this is not the same as commit messages
A commit message explains what changed in the code. A decision log entry explains why an approach was chosen over its alternatives, which is often invisible from the code even with a perfect commit history — the code shows what was built, not what was deliberately not built instead.
Nobody has ever regretted a paragraph explaining a decision. Several teams we have audited have lost real time reconstructing a decision that a single paragraph, written at the time, would have settled in thirty seconds.
Where it gets read
Almost never in the week it is written. It gets read during an audit, during a handover, during an incident when someone is trying to work out whether an unusual piece of architecture is intentional or accidental, and during onboarding, when a new engineer asks "why is it built this way" about something nobody currently on the team originally built.
The discipline that keeps it alive
The log is checked briefly in retrospectives — not for volume, but for whether anything decided that sprint deserved an entry and did not get one. This is a small, recurring cost. Reconstructing a decision from memory or from old chat messages, months later, under time pressure, is a much larger one, and we have paid that larger cost often enough on other people's projects to keep paying the smaller one on our own.