Article · 8 min read

Documenting Architecture Decisions

Michael Nygard · Cognitect (Michael Nygard) Free Advanced

The original essay that introduced Architecture Decision Records, a one page format capturing the context, the decision, and its consequences. Asking your engineer to write a short ADR for a contested stack choice is the fairest test in your short answer: if they cannot state the tradeoff in terms of your goals, the record makes that obvious. It turns 'trust me' into a written, revisitable rationale.

  • A decision record forces the tradeoff and consequences to be stated in writing.
  • If the rationale cannot be written in a paragraph, the choice is not yet understood.
  • Recorded decisions let a future team see why, not just what, was chosen.
Open on cognitect.com ↗

The question it answers

  1. When my technical hire and I disagree on the tech stack, whose call is it?

Read with it

  1. 200+ candid conversations with Indian founders and investors on how they actually found their idea, spotted a trend, and... Apple Podcasts Podcast · podcast series (45-90 min episodes) The Neon Show (formerly 100x Entrepreneur) Siddhartha Ahluwalia
  2. YC is the canonical authority on early-stage team formation, and this is their direct playbook for the exact problem a... YC Startup Library Article · ~12 min read How to Find a Technical Co-Founder Y Combinator
  3. Basecamp's battle-tested, opinionated system for shipping meaningful work in fixed cycles without endless backlogs, a primary... Basecamp / 37signals Book · free online book Shape Up: Stop Running in Circles and Ship Work that Matters Ryan Singer
  4. Sometimes the two ideas are a proxy for a deeper problem: you have no agreed way to make a call when you disagree. This HBR... Harvard Business Review Article · ~8 min read Cofounders Need to Learn How to (Productively) Disagree Evelyn Nam
  5. When two cofounders disagree on how big the market is, the fastest way out is to stop arguing opinions and turn the... First Round Review Article · ~12 min read The 6 Decision-Making Frameworks That Help Startup Leaders Tackle Tough Calls First Round Review (featuring Elliot Shmukler)
  6. Run by the managing partners of Prime Venture Partners (Sanjay Swamy, Amit Somani, Shripati Acharya and others), this is a... Prime Venture Partners Podcast Prime Venture Partners Podcast Prime Venture Partners
eChai Partner Brands The partnership →