Architecture Decision Records
1. What is it?
Architecture Decision Records are a lightweight document format to concisely describe relevant technical decisions, the context behind it and its consequences in the context of a software project. ADRs are stored directly in the source code repository (the convention is to place them on the folder docs/adr/. They create an immutable, append-only log that helps future teams understand “why” a system was built a certain way.
Michael Nygard[1] coined the term “Architecture Decision Record” with an ADR-formatted article in 2011.
2. Why to use them?
Good architects when asked: Is X the best technology for Z? without any additional context will always respond “It depends”. Depends a lot on the particular context, particular requirements and its precedence (yes, requirements sometimes are contracting and decisions are trade-offs).
In this context, ADRs are great to document key decisions of a project and to have a clear story of why the developers decided to do X instead of Y.
This is good for humans, but now, also good for LLM (Large Language Models). Without this explicit knowledge it is difficult to extract from the code such decisions and motivating context. Moreover, humans or LLMs without these tradeoffs in mind can introduce Technical Debt and Architecture Drift.
Making them explicit, immutable and versionable with the code allows an audit at any moment if the code is still in conformance with such technical decisions.
Software Architecture Archaeology will definitely benefit from making explicit the key technical decision to better understand the tradeoffs of the choices.
3. How we use them in Structura
With Structura, first we create opinionated software architectures to satisfy a certain domain. Later, we create a deterministic code generator to implement such architecture. The natural next step is to make explicit such technical decisions with ADRs. Therefore, backend and frontend Structura code generators follow the ADRs practice and we encourage developers to use it and maintain them properly.
References
- Documenting Architecture Decisions, Michael Ngmar Decisions. Michael Nygard - November, 2011.
- Architecture Decision Records. Martin Fowler - May, 2026.