Architecture Decision Record Practice
The habits that make decision records useful six months later — writing at decision time, recording rejected options, and never editing history.
The format is simple and largely irrelevant. What determines whether ADRs pay off is a handful of practices that are easy to state and commonly violated.
Write it when the decision is made, not afterwards. The reasoning is available only in the moment; reconstructed rationale is rationalisation, and it omits precisely the constraints that were operative.
Record the options rejected and why. This is the highest-value content and the most frequently omitted. Six months later the question is never "what did we choose" — that is visible in the code — it is "did we consider X", and without the rejected options the team relitigates the same debate, usually with less information.
Record the context and constraints as they were. A decision that looks wrong today was often correct given a deadline, a team's skills, or a contract that has since expired. Without the context the record invites contempt for predecessors rather than understanding.
Never edit a decision. Supersede it with a new record that references the old. The history of how thinking changed is part of the value, and editing destroys it.
Keep them with the code so they are found by people working on the system, and keep them short — one page. ADR practices die from length; nobody writes the fifth one if the first took a day.