tomevault-io MADR Format
MADR (Markdown Architectural Decision Records) is a lean, developer-friendly ADR format that emphasizes considered options and their pros/cons. It is the default format for the ADR plugin.
About MADR
MADR is:
- Lean - Focuses on essential decision documentation
- Markdown-native - Designed for version control
- Option-focused - Emphasizes alternatives considered
- Flexible - Offers full and minimal variants
Current version: MADR 4.0.0
Template Variants
Full Template
All sections including optional ones. Use for important decisions requiring comprehensive documentation.
Sections:
- Title (H1)
- Status
- Context and Problem Statement
- Decision Drivers
- Considered Options
- Decision Outcome
- Consequences (Good/Bad)
- Confirmation
- Pros and Cons of the Options
- More Information
Minimal Template
Only mandatory sections. Use for simpler decisions or when brevity is preferred.
Sections:
- Title (H1)
- Status
- Context and Problem Statement
- Decision Outcome
Bare Templates
Same sections as full/minimal but without explanatory text. For experienced teams who know the format.
Section Guide
Title (Required)
Format: # {Short Title}
The title should:
- Be a short noun phrase
- Describe the decision topic
- Use title case
Examples:
# Use PostgreSQL for Primary Storage# Adopt Event-Driven Architecture
Status (Required)
The current status of the decision.
Valid values: proposed, accepted, deprecated, superseded
Include metadata if needed:
## Status
Accepted
Supersedes ADR-0003
Context and Problem Statement (Required)
Describe the context and the problem requiring a decision.
Format options:
- Free-form prose (2-3 sentences)
- Illustrative story
- Question format
Example:
## Context and Problem Statement
Our order processing system experiences high latency during peak hours.
We need to decouple order submission from order processing to improve
responsiveness. The current synchronous architecture cannot scale to
meet projected growth of 5x order volume.
Decision Drivers (Optional)
Forces and concerns influencing the decision.
Format: Bullet list
## Decision Drivers
* Need to handle 10x current load
* Team familiarity with technology
* Budget constraints (max $5K/month)
* Must integrate with existing systems
Considered Options (Optional)
List of options seriously considered.
Format: Bullet list of option titles
## Considered Options
* RabbitMQ
* Apache Kafka
* AWS SQS
* Redis Pub/Sub
Decision Outcome (Required)
State the chosen option and why.
Format:
## Decision Outcome
Chosen option: "{option title}", because {justification}.
Example:
## Decision Outcome
Chosen option: "Apache Kafka", because it provides the durability and
replay capability we need for order processing, and the team has
existing experience with it.
Consequences (Optional)
Positive and negative outcomes of the decision.
Format:
### Consequences
* Good, because {positive outcome}
* Good, because {another positive}
* Bad, because {negative outcome}
* Bad, because {another negative}
Confirmation (Optional)
How compliance with the decision will be verified.
Example:
### Confirmation
The implementation will be verified through:
* Architecture review before deployment
* Load testing against performance requirements
* ArchUnit tests to enforce message-based communication
Pros and Cons of the Options (Optional)
Detailed analysis of each option.
Format:
## Pros and Cons of the Options
### {Option 1 Title}
{Brief description}
* Good, because {pro}
* Good, because {pro}
* Neutral, because {neutral point}
* Bad, because {con}
### {Option 2 Title}
{Brief description}
* Good, because {pro}
* Bad, because {con}
More Information (Optional)
Additional context, links, or notes.
Include:
- Links to related documents
- Team agreement notes
- Implementation timeline
- Conditions for revisiting
Creating MADR ADRs
With Full Template
# Copy full template
cp ${CLAUDE_PLUGIN_ROOT}/templates/madr/adr-template-full.md docs/adr/0001-title.md
With Minimal Template
# Copy minimal template
cp ${CLAUDE_PLUGIN_ROOT}/templates/madr/adr-template-minimal.md docs/adr/0001-title.md
MADR Best Practices
Do
- Keep context focused on the problem
- List 2-5 realistic options
- Include both pros and cons for each option
- Be specific about consequences
- Update status when it changes
Don't
- Include options just to reject them
- List only positive consequences
- Leave placeholder text
- Forget to link related ADRs
- Let status become stale
MADR vs Other Formats
| Aspect | MADR | Nygard | Y-Statement |
|---|---|---|---|
| Focus | Options comparison | Decision recording | Concise statement |
| Length | Medium | Short | Very short |
| Options | Detailed | Implicit | Single |
| Best for | Tech decisions | Quick records | Simple decisions |
Additional Resources
Reference Files
references/madr-examples.md- Complete MADR examples
Templates
Templates available at ${CLAUDE_PLUGIN_ROOT}/templates/madr/:
adr-template-full.md- All sections with guidanceadr-template-minimal.md- Required sections onlyadr-template-bare.md- All sections, no guidanceadr-template-bare-minimal.md- Required sections, no guidance
Related Skills
- adr-fundamentals - ADR basics and lifecycle management
- adr-decision-drivers - Identifying and documenting decision drivers
- adr-quality - Quality criteria and review process
- adr-format-structured-madr - Extended: MADR with frontmatter and audit sections
- adr-format-nygard - Alternative: Classic Nygard format
- adr-format-y-statement - Alternative: Concise Y-Statement format
External Resources
- MADR GitHub: https://github.com/adr/madr
- MADR Documentation: https://adr.github.io/madr/
Converted and distributed by TomeVault — claim your Tome and manage your conversions.