Why write Architectural Decision Records

Architectural Decision Records

For the future you

  • captures the decision at the time it's written
  • help you recall what your mindset was when you decided upon that architecture
  • save the future you time, you can just link people to the ADR instead of spending time explain

For your peers

  • Provide understanding of the tradeoffs and the considerations
  • Provide a bigger context of the change, and how it works in a larger system
  • Get better pull request reviews

For your future peers

  • Helps scale onboarding new team members
  • Allow your teammates to write a new ADR that supersededs the current ADR