> Ensures that [[Decision making|decisions]] are made **transparently** and systematically and **can be reviewed** during the life cycle of the software ^definition --- ## [[Impact-oriented decision making]] Bridge the gap by documenting technical decisions in a way that business stakeholders can understand ![[Impact-oriented decision making#^parts|The Ws of Impact-oriented decision making]] ## Problems without ADRs Decisions made by previous teams or architects may be forgotten, leading to repeated discussions or redundant work. ### [[Knowledge management]] #### Lack of [[Single source of truth]] Decisions are often **buried** in emails, Slack messages, or undocumented meetings, making it **difficult to find** them when needed ### [[Team collaboration]] #### [[Onboarding]] New team members often **struggle to understand** why certain architectural choices were made #### [[Tribal knowledge]] When key engineers leave, their **reasoning** behind past decisions is often **lost** #### [[Impact]] One team’s decision may impact another, and without a transparent record, teams may be **unaware of dependencies** #### [[Process quality]] Ad-hoc changes may be made **without proper discussion or alignment** with architectural principles ### [[Tech debt]] accumulation #### [[Change]] and [[Refactorization]] Poorly documented decisions make it **hard to refactor** or improve architecture when business needs change ## Templates - https://github.com/joelparkerhenderson/architecture-decision-record?tab=readme-ov-file#adr-example-templates ## Practices Decompose decisions if needed > Break one decision into multiple if an architectural decision is going to result in multiple phases, such as short-term, mid-term, long-term approaches. Log each phase as its own decision record. #todo/link works in similar manner as [[User Story Splitting]]