> [!definition] Architecture Decision Record > Ensures that [[Decision making|decisions]] are made **transparently** and systematically and **can be reviewed** during the life cycle of the software ^definition ## [[Business-oriented implementation decisions]] Bridge the gap by documenting technical decisions in a way that business stakeholders can understand ![[Business-oriented implementation decisions#^parts]] ## Problems without ADRs Decisions made by previous teams or architects may be forgotten, leading to repeated discussions or redundant work. ### [[Knowledge management]] > [!warning] 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]] > [!warning] [[Onboarding]] > New team members often **struggle to understand** why certain architectural choices were made > [!warning] [[Tribal knowledge]] > When key engineers leave, their **reasoning** behind past decisions is often **lost** > [!warning] [[Impact]] > One team’s decision may impact another, and without a transparent record, teams may be **unaware of dependencies** > [!warning] [[Process quality]] > Ad-hoc changes may be made **without proper discussion or alignment** with architectural principles ### [[Tech debt]] accumulation > [!warning] [[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 > [!hint] 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 works in similar manner as [[User Story Splitting]]