Why I log decisions as I make them
A running record of decisions that answers the question you'll have in three months.
Every project I work on has a place where I log decisions. A doc, a Notion page, a dedicated section in my notes. It's not documentation. It's not a README. It's a running answer to the question: why did we do it this way?
The what is in the code. The how is in the commit history. The why disappears the moment the person who made the decision stops thinking about it, which is usually the same day they made it.
What goes in it
Anything where the reasoning isn't obvious from the code. Choosing one library over another. Deciding against a pattern that would seem like the natural choice. A schema design that looks weird until you understand the constraint it was built around. A service split that made sense at the time given what we knew about the usage pattern.
I write it in the moment of the decision, because that's the only time the reasoning is fully available. An hour later I've moved on. A week later I'm not sure I could reconstruct it accurately. Three months later, when you'll need it, it's gone.
The question it answers
Why didn't we just use X here?
This question comes up constantly. A new person joins the project. A senior dev reviews a PR. You come back to a module you haven't touched in four months. The answer is almost never 'we didn't think of X.' It's usually 'we tried X and hit this problem' or 'X would have required Y which we couldn't do at the time' or 'we considered X but the performance profile was wrong for this use case.'
Without a decision log, you either spend an hour in the git history hoping someone wrote a useful commit message, or you make the wrong assumption and introduce the thing that was already ruled out.
Why not just leave it in comments
Comments live next to the code they explain, which means they get deleted when the code changes. A separate log survives refactors. It's also a better place for decisions that span multiple files, or decisions that were made before any code was written.
It takes about ten minutes a week to maintain. It has saved me much more than that: in avoided meetings, in faster onboarding, in not rebuilding things that were already ruled out for good reasons. It's the cheapest habit I've added to my workflow.