ADR Anti-Patterns
Common ways ADRs go wrong and how to spot them in review.
Why
Most teams that adopt ADRs abandon them within a year because the records degrade into one of a few failure modes: the essay (no structure), the post-hoc rationalization (written after the code to justify what was already built), or the parking lot (Proposed forever). Naming these anti-patterns lets reviewers catch them in the PR instead of discovering the rot six months later when nobody trusts the docs anymore.
When
Reference during ADR review. No setup needed — just a checklist to apply.
How
1. In review, check for these anti-patterns:
a. "The Essay" — no Status/Date/Context headers, just prose → reject, ask for template
b. "Post-hoc" — Context describes the code that already exists, not the forces
that drove the decision → reject, ask for the pre-decision context
c. "Parking Lot" — Status=Proposed for >2 weeks with no reviewer movement
→ ping author or close
d. "The Memo" — Decision made by edict with no alternatives considered
→ reject, ask for at least one rejected alternative
e. "Crystal Ball" — Consequences only list positives → reject, require negatives
2. Add these checks to your adr lint config so CI catches them automatically
3. Share the anti-pattern list in onboarding so new authors learn the shapeExample
Rejected ADR (anti-pattern: "The Memo"): # 0014. Use gRPC - Status: Accepted - Decision: We will use gRPC for all internal communication. (No Context, no alternatives, no Consequences — pure edict) Reviewer: "This is 'The Memo' anti-pattern. What forces drove gRPC over REST/GraphQL? What breaks if we adopt it? Please add Context with at least one rejected alternative and a Consequences section."
Common Problems
- ⚠Treating the anti-pattern list as a gate rather than coaching — rejecting without explaining the fix breeds resentment; always show the corrected shape.
Best Practices
- ✓Keep the anti-pattern list to 5 entries — too many and reviewers stop checking all of them.
- ✓When you catch an anti-pattern, link the author to a good ADR example so they can pattern-match instead of reading rules.
- ✓Track which anti-patterns recur most; if 'Post-hoc' dominates, your process is forcing ADRs too late — move them earlier in the design flow.