ADRs, Guardrails and Golden Paths

From CitconWiki
Revision as of 14:58, 4 February 2023 by Robpark (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Architectural Decision Records (ADRs)

  • Documenting Architecture Decisions by Michael Nygard
  • Scaling the Practice of Architecture, Conversationally
    • There's also a great ADR template in there.
  • ADRs need to be documented at the time the decision is made
  • Include the reasoning behind why the decision was made at the time
  • A lot of recommendations are to author in markdown and check in to version control
    • I think it should live in the repo for which the decision applies
  • Problems
    • I have seen many cases of making general blanket architecture decisions (or suggestions) and labeling them as ADRs
  • Encourage people to author ADRs as an opportunity towards career growth
  • They could certainly act as an aid when outsourcing a project especially when there is the possibility of the code and maintenance coming back to you at some point.


  • Another type of documentation I've been promoting are "guardrails" which are constraints that are put in place by some central team (e.g. CTO, Security team, etc).
  • These are not ADRs in that they are general constraints that all architectures of the org are expected to be adhered to.

Golden Paths

  • The 3rd type of document I've been promoting is a Golden Path or well-documented, potentially with tooling support, but repeatable path for a specific implementation.
  • Golden Paths at Spotify
    • Aside: there is a system available from Spotify for managing a related developer portal for golden paths: Backstage
  • AKA Paved Roads at Netflix