Architecture decision record (ADR)

An architecture decision record (ADR) is a document that captures an important architecture decision made along with its context and consequences.

[!IMPORTANT] Do your own due dilligence for these resources before using them in any critical systems.

Website: architecture-decision-record.github.io — this README, plus every template and example, as a browsable site.

Contents:

• What is an architecture decision record?
• How to start using ADRs
• How to start using ADRs with tools
• How to start using ADRs with git
• Claude Code skills for ADRs
• File name conventions for ADRs
• Suggestions for writing good ADRs
• ADR example templates
• Teamwork advice for ADRs
• Teamwork questions for ADRs
• Next step concepts for ADRs
• Architecture diagrams & views & viewpoints
• Fitness functions for decisions as code
• Decision guardrails for pull requests
• For more information

Templates:

• Decision record template by Jeff Tyree and Art Akerman
• Decision record template by Michael Nygard
• Decision record template by EdgeX
• Decision record template by arc42
• Decision record template for Alexandrian pattern
• Decision record template for business case
• Decision record template of the MADR project
• Decision record template using Planguage
• Decision record template by Paulo Merson
• Decision record template by Olaf Zimmermann
• Decision record template by Gareth Morgan
• Decision record template by GIG Cymru NHS Wales
• Decision record template for Important Technical Decisions (ITDs) by Ignacio Larrañaga
• Translations into more languages

Examples:

• CSS framework
• Environment variable configuration
• Metrics, monitors, alerts
• Microsoft Azure DevOps
• Monorepo vs multirepo
• Programming languages
• Secrets storage
• Timestamp format
• Many more…

Translations into more languages

Claude Code skills for ADRs

This repository ships two Claude Code skills under skills/, so an AI coding agent can write and maintain ADRs the way this project recommends:

• architecture-decision-record-skill — general purpose, for anyone writing an ADR in any project. Helps decide whether a decision needs an ADR, sets up an adr/ or decisions/ directory, names the file, picks a template from the eleven bundled skeletons, and writes solid Context/Decision/Consequences sections.

• architecture-decision-record-maintainer-skill — for maintainers of this repository specifically. Documents the repo’s layout, the README/locales mirroring convention, and the exact steps for adding a new template, example, or tool link.

To use a skill, copy its folder into .claude/skills/ at the root of the repository you’re working in (or into ~/.claude/skills/ to make it available in every project), then ask Claude Code to write or review an ADR.

ADR example templates

ADR example templates that we have collected on the net:

• ADR template by Michael Nygard (simple and popular)

• ADR template by Jeff Tyree and Art Akerman (more sophisticated)

• ADR template for Alexandrian pattern (simple with context specifics)

• ADR template for business case (more MBA-oriented, with costs, SWOT, and more opinions)

• ADR template of the Markdown Any Decision Records (MADR) project (both simple and elaborate version; the latter emphasizes options and their pros and cons)

• ADR template using Planguage (more quality assurance oriented)

• Template for Important Technical Decisions (ITDs) by Ignacio Larrañaga (lean and decision-first, optimized for fast executive review)

Architecture diagrams & views & viewpoints

An architecture diagram is called an “architecture view”.

An “architecture view” is an instance of a “architecture viewpoint”.

An “architecture viewpoint” has a specific audience with specific concerns in mind.

Architecture viewpoint examples, view examples, and diagram examples:

• Business Capabilities

• High-level Business Processes

• Value Streams

• Software Functions mapped to application components

• C4 Model Context Diagram (TO-BE / AS-IS)

• C4 Model Container Diagram (TO-BE / AS-IS)

• Entity-relationship Diagram (ERD) to map data entities to application components

• Sequence Diagrams to describe functional flows within systems and for integrations

• Business Process Model and Notation (BPMN) diagrams to describe data flows across application components

• Business Process Model and Notation (BPMN) diagrams to describe business processes / user Scenarios

• Identity and Access Management (IAM) diagrams

• Role-Based Access Control (RBAC) diagrams with roles per application component

• Attribute-Based Access Control (ABAC) diagrams with attributes per application component

• Privacy diagrams

Related diagrams:

• A Use Case Diagram shows use cases to management/customers, which precedes requirements, which precedes the software architecture.

• A Deployment Diagram shows the physical hardware/computers that the software components are deployed to.

• A Data Flow Diagram shows how data moves through the system and is transformed.

• A Sequence Diagram is used to show how protocols like HTTP work on a time axis.

• An Activity Diagram depicts the workflow of activities a software system undertakes, like an NPC AI.

Fitness functions for decisions as code

Fitness functions are objective automated checks, written with programming code, that verify decisions are being maintained.

• Fitness functions make decisions testable and assurable.

• Fitness functions for decisions can greatly help quality assurance, regulatory processes, and governance goals.

How fitness functions connect to decisions

A decision record documents the decision, while a fitness function assures the decision.

• Example decision: We use event sourcing for audit requirements.

• Example fitness function: We use the continuous integration server to test that all state changes must produce events.

Why fitness functions help decisions

Objective measurements: Fitness functions pass or fail, so work is visible and clear.

Continuous use: Fitness functions are your living rules, run on every commit and build.

Confidence to refactor: Fitness functions automatically catch decision rule errors.

Scalable governance: Fitness functions assure standards without creating bottlenecks.

Can fitness functions use AI?

Fitness functions can leverage AI LLMs for decisions by asking questions for your work, such as your plans, code, schemas, APIs, and more:

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search.

This is a fitness function to evaluate if our work is
using all our decisions, and is correct and accurate.

- Our decisions are here: {url}
- Our work to evaluate is here: {url}

Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.

Architecture unit testing

ArchUnit: check architecture rules of Java code by using any plain Java unit test framework.

ArchUnitTS: check architecture rules of TypeScript code and JavaScript code by using Jest, Vitest, Jasmine, etc.

Decision guardrails for pull requests

Decision Guardian automatically surfaces the right decision records at the right moment — when a developer is actively modifying the code those decisions cover. Instead of hoping developers read a docs folder before merging, the relevant context appears directly on the pull request.

This works for any kind of decision record: architecture decisions, data decisions, compliance decisions, clinical and medical decisions, security decisions, and more.

Works with any CI system (GitLab, Jenkins, CircleCI) and as a pre-commit hook. Open source. MIT license.

ADR Guard is a GitHub Action that fails a pull request when watched code paths change without an architecture decision record being added or updated. Waivers are explicit: an ADR-Exempt: line with a reason passes the gate and is written into the job summary. Template-agnostic, no dependencies. Open source. MIT license.

For more information

Introduction:

• Architectural decision (wikipedia.org)

• Architecturally significant requirements (wikipedia.org)

Templates:

• Documenting architecture decisions - Michael Nygard (thinkrelevance.com)

• Markdown Architectural Decision Records (adr.github.io)

• Template for documenting architecture alternatives and decisions (stackoverflow.com)

In-depth:

• ADMentor XML project (github.com)

• Architectural Decision Guidance across Projects: Problem Space Modeling, Decision Backlog Management and Cloud Computing Knowledge (ifs.hsr.ch)

• The Decision View’s Role in Software Architecture Practice (computer.org)

• Documenting Software Architectures: Views and Beyond (resources.sei.cmu.edu)

• Architecture Decisions: Demystifying Architecture (utdallas.edu)

• ThoughtWorks Technology Radar: Lightweight Architecture Decision Records (thoughtworks.com)

• A Skeptic’s Guide to Software Architecture Decisions (infoq.com)

• Architectural Decisions — The Making Of

• Architectural Retrospectives: the Key to Getting Better at Architecting

• Software Architecture Monday with Mark Richards - free monthly software architecture lesson

• Solution Architecture Decisions - By Gareth Morgan

• “Keep the Why: Code Becomes Legacy When Nobody Remembers Why”

Tools:

• Command-line tools for working with Architecture Decision Records

• Command line tools with python - by Victor Sluiter

• Architectural Design Decision Support Framework (ADvISE)

• Decision Guardian

• Mneme HQ - ADR enforcement for AI coding agents

• Keep the Why - a repo-native convention and agent skill that continuously captures, or retrospectively recovers, the reasoning behind a codebase

• ADR Guard - GitHub Action that fails a pull request changing watched code without an architecture decision record

• kgai - append-only decision log for AI coding agents, a machine-readable companion to ADR files

Company-Specific Guidance:

• Amazon: AWS Prescriptive Guidance: ADR Process

• GitHub: ADR GitHub organization

• RedHat: Why you should use ADRs

Examples:

• Repository of Architecture Decision Records made for the Arachne Framework

Videos:

• An introduction to arc42 with Savvas Kleanthous

• The C4 model for visualising software architecture - by Simon Brown

Podcasts:

• Software Architecture Bookclub Podcast

Books:

• Software Architecture Metrics: Case Studies to Improve the Quality of Your Architecture - by Christian Ciceri, Dave Farley, Neal Ford, Andrew Harmel-Law, Michael Keeling and Carola Lilienthal

• Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives - by Nick Rozanski and Eoin Woods

• Software Architecture in Practice (SEI Series in Software Engineering)

• Documenting Software Architectures: Views and Beyond (SEI Series in Software Engineering)

• The Software Architect Elevator: Redefining the Architect’s Role in the Digital Enterprise

• Fundamentals of Software Architecture: An Engineering Approach - by Mark Richards and Neal Ford

• Building Evolutionary Architectures - by Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage

• Foundations of Decision Analysis by Ronald Howard and Ali Abbas

• Head First Software Architecture - by Raju Gandhi, Neal Ford and Mark Richards

• Communication Patterns: A Guide for Developers and Architects - by Jacqui Read

See also:

• REMAP (Representation and Maintenance of Process Knowledge)

• DRL (Decision Representation Language)

• IBIS (Issue-Based Information System)

• QOC (Questions, Options, and Criteria)

• IBM’s e-Business Reference Architecture Framework

• Decision Reasoning Format (DRF) - A vendor-neutral, machine-readable YAML/JSON format for representing decisions with explicit reasoning, assumptions, cognitive state, and trade-offs. Complements ADRs by adding structured, validatable reasoning to decision documentation.