You join a team with no decision records. Significant choices are made in chat and nobody can explain why the system is shaped as it is. How do you introduce ADRs without it becoming process overhead?
Show the full answer Hide the answer
Start by writing them yourself, retrospectively, for three decisions
Pick three choices that are currently causing confusion — why this database, why this integration is asynchronous, why authentication works the way it does — and write the records. Retrospective records are weaker than contemporaneous ones because they capture the justification rather than the reasoning, and they are enough to show what the artifact is for.
The reaction you are looking for is someone saying "I did not know that was why". That is the argument, and it is more persuasive than describing the practice.
Make the format minimal
Context, decision, options considered with their rejection reasons, consequences including the negative ones. One page. In the repository next to the code it constrains, so it is reviewed in the same pull request as the change.
The two sections that carry the value are rejected options — a record with one option is a press release — and negative consequences, which is the only part anyone reads two years later and the part that makes the next reader trust it.
Set a trigger, not a policy
Not "all decisions need an ADR", which produces either records for trivial choices or quiet non-compliance. Write one when the decision is expensive to reverse, constrains another team, or when you can already imagine someone asking "why on earth did they do that?".
That is a judgement each engineer can apply without a meeting.
Two rules that keep it honest
Never edit an accepted record — supersede it. The sequence is the history, and the history is the value.
Status is real: proposed, accepted, deprecated, superseded, and maintained.
The measure of adoption
Not the count of records. It is whether anyone cites one — in a review, in an onboarding conversation, or when a decision is being revisited. If nobody ever references them, they are documentation rather than a decision log, and something about the format or the placement needs changing.