We want to record decisions made in this project independent whether decisions concern the architecture or the code.
Which format and structure should these project records follow?
MADR (Markdown Architectual Decision Records) for documenting project decisions and architectural decisions striping this project, stored locally in decisions/.
decisions/{NNNN}-use-{tool}-for-{purpose}.md
# ADR-{NNNN}: Use {tool} for {purpose}
## Context and Problem Statement
<!-- What led up to this decision? -->
## Decision
<!-- What is the chosen option. Use links, keep it terse. -->
## Why?
<!-- Make your case. Use links to let others make your case. -->
- First benefit
- Second benefit
## Trade-offs accepted
<!-- What isn't good about the decision? -->
- First consequence
- Second consequence
## Alternatives rejected
<!-- What else was considered? Keep it brief. -->
- Option 1: ~
- Option 2: ~
## Revisit if
<!-- What might cause you to change your mind. -->
- Concrete example where a bad thing reveals itself
- A forseen consequence of a future tech- Implicit assumptions should be made explicit.
- Design documentation is important to enable later editors understanding past decisions.
- Why MADR specifically:
- MADR is loose enough such that it allows for structured capturing of any decision.
- MADR structure is comprehensible to the layperson, facilitating usage & maintenance.
- MADRs can easily be read/written/maintained by commodity agents
- In-project text with searchable filenames pre-empt the need for RAG or MCP tooling for agents
- See also "A rational design process: How and why to fake it".
- MADR does not come with a process for creating it, so that must be adopted a-la-carte (if at all)
- The brevity of the format leaves things up to interpretation
- Michael Nygard's template – The first incarnation of the term "ADR"
- Sustainable Architectural Decisions – The Y-Statements
- Other templates listed at https://github.com/joelparkerhenderson/architecture_decision_record
- Formless – No conventions for file format and structure
- The format turns out to be too lean
- More rituals are needed to force maintenance