The feedback
Early at Zipy I was building features end to end — schema, what went into Redis and why, architecture. My CTO told me I kept reworking those decisions every time I came back to the code, because none of the reasoning was written down. Every design decision needed to be recorded with its reasoning, not just the decision.
Why it landed
Soon after, inside the browser SDK, I hit a condition handling a special error object. It was clearly deliberate, but nothing said why. A live customer issue pointed straight at it.
That left a coin flip: change it and risk breaking something existing customers depended on, or leave it and fail to fix the new issue. A production decision resting entirely on reasoning nobody had written down.
What I did
- Every special-case condition got a comment with the actual use case behind it.
- Design decisions went into a short doc inside the feature's own folder, so reasoning lives next to the code it explains.
Outcome
Rework dropped substantially. Not to zero — some of that is systems genuinely evolving — but I stopped re-deriving decisions I'd already made, because I could go and read why.
What I learned
Reasoning ages far slower than code. Documenting why protects future decisions; documenting what goes stale.