ADR
===

An Architecture Decision Record (ADR) is a document that describes, in a structured way, an architecture decision (AD).



Status
------

2026-02-08: Draft
2026-02-08: Accepted
2026-02-09: Reviewed
2026-09-14: Reviewed



Context
-------

The documentation of architecture decisions allows the incremental building of architectural knowledge. The record of an architecture decision contains the reasons that can be shared, discussed and reviewed, by peers and authors at different times, considering new contexts and circunstances.

Even though it requires some time and effort to write an ADR, it allows the author to develop the decision in a structured and concise way.


### Concepts

- Architecture Decision (AD): a justified design choice that addresses a functional or non-functional requirement that is architecturally significant
- Architecturally Significant Requirement (ASR): a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system
- Architectural Decision Record (ADR): captures a single AD and its rationale
- Decision Log (DL): collection of ADRs created and maintained in a project
- Architectural Knowledge Management (AKM): name of the topic


### Sections

An usual ADR should contain the following sections:

- Title
- Status
- Context / Problem
- Considerations / Alternatives
- Decision
- Justifications / Consequences
- References



Considerations
--------------

There are [some ADR templates](https://adr.github.io/adr-templates/):

- Markdown Architectural Decision Records (MADR)
- Nygard ADR
- Y-Statement



Decision
--------

Adoption of markdown ADRs.



Justification
-------------

Markdown is a simple text structure readable by humans. It avoids overheads of dependency tools and complicated formats readable by programs only.

Even though some time is required to review and maintain the decisions, the value of a Decision Log surpasses the cost due to the learning and knowledge building, avoiding rework.



References
----------

- https://adr.github.io/
- https://adr.github.io/adr-templates/
- https://adr.github.io/madr/
- https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html
- https://medium.com/@jhonywalkeer/guia-completo-sobre-architecture-decision-records-adr-defini%C3%A7%C3%A3o-e-melhores-pr%C3%A1ticas-f63e66d33e6
- https://www.infoq.com/articles/sustainable-architectural-design-decisions/
- https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- https://github.com/adr/madr/blob/4.0.0/template/adr-template-minimal.md?plain=1