Keep a Decision Log
A lightweight habit for preserving context before it becomes archaeology.
Projects lose context slowly. A naming convention here, a service boundary there, a tradeoff made during a tight week. Six months later, the code still contains the decision, but not the reason.
A decision log is a low-friction way to preserve that reason. It does not need ceremony. A date, a short title, the options considered, and the reason for the choice are usually enough.
Write for the Next Change
The audience is not a future historian. It is the next person trying to modify the system without accidentally undoing a constraint that still matters.
Useful entries include the pressure around the decision. Was speed more important than flexibility? Was a dependency avoided because of licensing, deployment, or team familiarity? Those details age better than vague statements about best practice.
Keep It Close to the Work
The best decision log is the one people actually update. Put it near the code or docs, keep entries short, and link to pull requests when the implementation matters.
The habit is small, but the payoff is real: fewer repeated debates, faster onboarding, and a codebase with memory.