Keep the reason with the decision

Code shows what a system does. It rarely shows why one option was chosen over another.

A short decision record can preserve that context without becoming a second specification.

Record four things

1. The problem and its constraints.
2. The options considered.
3. The decision and its costs.
4. The evidence that would justify a change.

The fourth item is easy to omit. It is also what keeps the record useful. A decision made for a small dataset may need to change when the dataset grows.

Be specific about uncertainty

Write what is known and what still needs a test. A short statement of uncertainty is more useful than a confident explanation built on an assumption.

Keep the record beside the code. Update it when the decision changes, and retain the reason for the change.