ADR, or Architectural Decision Record, is a concise record of architectural decisions made during the software design process. These records capture the context in which the decision was made, the decision itself, and the consequences of the decision. ADRs should be written whenever a decision has been made that affects the system's architecture, its non-functional requirements, or its development processes. Note that not every change requires an ADR. The intent is to capture meaningful decisions that have a lasting impact on the project or system. If the decision would benefit from additional context or if future developers might wonder 'why was this done?', then it's worth capturing in an ADR. Also, keep in mind that ADRs aren't set in stone. As systems evolve and requirements change, previous architectural decisions might be revisited, and new ADRs can be created to document the evolution.

Case scenarios

• Significant architectural changes: whenever a decision is made that significantly changes the system's architecture, such as adopting a microservices architecture, choosing a specific database system, or introducing a new technology stack.
• New Requirements: when new business or technical requirements lead to architectural changes. For example, a requirement for multi-region support might necessitate decisions around data replication and latency.
• Trade-offs: anytime there are multiple options considered and trade-offs evaluated to make a decision. Documenting why certain options were rejected can be as valuable as documenting why one was chosen.
• Risk mitigation: when a decision is made to address risks, such as security vulnerabilities or potential bottlenecks in the system, it's beneficial to capture the decision and the context.
• Changes to established practices: if the development or deployment practices are changed, such as adopting a new branching strategy or incorporating new CI/CD tools.
• Overturning previous decisions: when an earlier decision is being revisited, modified, or reversed, an ADR can provide insight into what's changed in the interim, be it new information, shifting requirements, or the evolution of technology.
• Regulatory or compliance impacts: in industries where regulatory or compliance requirements are crucial, architectural decisions made to meet these requirements should be documented.
• Knowledge sharing: to ensure that team members, especially those who join later in the project, understand the context and rationale behind certain choices.
• Controversial decisions: when the team is divided on a particular decision or when it could have significant consequences (either positive or negative).