Version Your Decisions
16 March 2026
There's a specific kind of confusion that only happens when you return to your own code after a long absence. Not the ordinary confusion of unfamiliar syntax or forgotten logic — that clears up in a few minutes. This is the confusion of finding a pattern that looks wrong, and not knowing whether it's wrong or whether there was a reason for it that you no longer remember.
You can read the git log. You can see that the file changed fourteen months ago, in a commit that says "refactor auth flow." You can see what changed. What you can't see is why you made that specific choice instead of the obvious alternative — or whether the constraint that made it the right call still exists.
That missing context is the most expensive thing in software development that nobody talks about.
What git doesn't version
Git versions your code. It doesn't version your reasoning.
The reasoning is the part that decays. The code is still there, frozen exactly as you left it. The context that made it correct — the constraint you were working around, the alternative you considered and rejected, the thing that was true about the system at the time — that lives in your head, and it evaporates.
In a team environment this is a well-understood problem. Architecture Decision Records (ADRs) exist precisely to address it: short documents that capture a decision, the context in which it was made, the alternatives considered, and the tradeoffs accepted. Teams that use them can look up why a system is structured the way it is without having to reconstruct the reasoning from first principles.
Solo developers almost never do this. The assumption is that you'll remember, or that the code is obvious enough. Neither tends to be true after six months.
The context is the valuable part
An ADR doesn't need to be long. The minimum useful version is a paragraph that answers three questions: what did you decide, what were you choosing between, and what made you land here.
In Barba Studio, at some point I decided to store appointment pricing at booking time rather than referencing the current service price. The code is clear about what it does — the embedded price is right there in the document. What the code doesn't explain is why: that changing a service's price shouldn't retroactively alter what was agreed in a past booking, and that this behavior matters legally in an invoicing context.
Without that context, the next person to touch that code — including me in eighteen months — might look at the denormalization, assume it was an oversight, and "fix" it. The fix would introduce a genuine bug. The code looked wrong. It wasn't wrong. The difference was invisible.
You don't need a framework
The overhead of formal ADR tooling is the reason people skip the practice entirely. You don't need tooling. You need a decision log, and a decision log can be a directory of numbered Markdown files, a section of your project wiki, or even a well-placed comment in the code that says: "this is intentional, here's why."
The format that's worked for me is a simple file: the decision, the date, the alternatives I considered, the constraint that ruled them out, and a note on what would make me revisit it. That last part is important. Decisions aren't permanent. The constraint that made one approach correct might disappear — the system might change, the scale might shift, the requirement might evolve. Knowing what to watch for is as useful as knowing why you made the original call.
The thing you'll thank yourself for
The version of this that's easiest to start is also the most effective: write a note every time you make a non-obvious call. Not for every function you write — for the moments where you considered two approaches and chose one. Where you worked around a constraint. Where you accepted a tradeoff deliberately.
It takes three minutes. It pays off every time you return to that part of the codebase and don't have to excavate the reasoning from scratch. It pays off even more when you're about to change something and you find the note, and you realize the constraint it was written around is still there.
Code is a record of decisions. Most of the decisions — especially the important ones — leave no trace of the reasoning behind them. Fixing that doesn't require process or tooling. It requires the habit of writing down why, at the moment when you still know.
You'll forget. Write it down.