Architecture Decision Record

Architecture Decision Record is the original artifact that every modern design decision log copies. It is a short dated structured record of one specific call that includes the decision itself the alternatives that were on the table the constraints that ruled options out the reasoning that led to the choice the owner responsible and the outcome measured after launch. Six tight fields written before the work begins and updated when reality delivers its verdict. The record lives inside the tools the team already uses whether that is a markdown file in the repo a Linear doc a Notion database or a public personal site. Michael Nygard codified the format in 2011. Thoughtworks and Spotify turned it into standard practice for engineering decisions. Designers finally caught on when they realized AI can ship the screen but only a human can defend why that screen and not the seventeen others. Linear adapted the format into design RFCs that ship before any major interface change. Vercel stores them alongside engineering specs so design and code decisions stay linked. The record is judgment made visible and searchable.

It is not a polished case study that makes every choice look inevitable from the start. Case studies sell. Architecture Decision Records document the actual mess the constraints and the call. It is not meeting notes that transcribe discussion. The record only captures what was decided why it won and who owns the result. It is not a post hoc justification written once the metrics are known. Those versions always list alternatives that no one ever considered and outcomes that only celebrate wins. Real records get written early get reviewed honestly and get updated with the bad news when the predicted uplift never materializes. The willingness to state that a decision aged poorly is what separates theater from practice that compounds.

Take the Architecture Decision Record Stripe wrote in 2024 for their new data table component. The entry is dated August 22 2024. Decision states build the table using a virtualized list with fixed headers rather than native table elements. Alternatives lists three real options including standard HTML with CSS sticky positioning a split simple and complex component and adopting Tanstack Table immediately. Constraints cites the need to handle ten thousand rows without jank accessibility requirements that break most third party libraries brand animation needs and limited engineering bandwidth that quarter. Reasoning explains the custom virtualized approach beat the others in testing by forty percent on render time and fit the existing design system patterns established the year before. Owner is listed as Priya Patel with Sam Kim as reviewer. Outcome updated two months later shows render performance twelve percent above projection zero accessibility issues and two animation adjustments that were logged for the next iteration. That single document prevented the same debate from happening again in three subsequent projects. The same pattern appears in Anthropic research notes that log exact training runs and safety benchmarks for model guardrails in 2025 and in the public design diaries Jordan Singer ships with every small product where he calls out the exact miss on a gesture model that tanked first week retention.

Write every entry with strict rules. Decision must be one concrete sentence in present tense. Alternatives must be numbered and real enough that the strongest one creates tension. Constraints must be bulleted sourced and specific from actual support tickets or performance budgets. Reasoning must cite the exact constraint or data point that tipped the scale and link the test results. Owner must name the designer and the reviewer. Outcome must be filled later with real metrics and the sentence that says what you would change next time even when it hurts. Store it in Notion for most product teams Linear when design already lives next to issues markdown in the repo for design engineers who want versioned history or a personal site for designers building a public trail that doubles as portfolio like Brian Lovin does with years of dated entries that explain type scale and layout calls.

Pull this format when the decision will be questioned in six months when multiple squads will inherit the choice when you need to demonstrate senior judgment in an interview or when the tradeoff deserves to be debated in review. The log turns a forty five minute case study into fifteen minutes of pure signal about how you think. Use it for navigation architecture design system evolution onboarding flows or any interface decision where six months from now the team will ask why. Skip it for trivial cosmetic changes that will not compound. Skip it for one off experiments with no lasting impact. Skip it if you intend to spin the alternatives or hide bad outcomes because senior reviewers detect that theater instantly. The practice only sticks when the first entry gets real pushback from a peer. Teams like Stripe Vercel Linear and Anthropic already treat these records as core non optional craft. Designers who adopt them in 2026 pull ahead because their judgment stops disappearing when they change jobs.

Senior judgment that stays in your head instead of the log disappears the day you do.