adr-format-madr

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:

1. Title (H1)
2. Status
3. Context and Problem Statement
4. Decision Drivers
5. Considered Options
6. Decision Outcome
7. Consequences (Good/Bad)
8. Confirmation
9. Pros and Cons of the Options
10. More Information

Minimal Template

Only mandatory sections. Use for simpler decisions or when brevity is preferred.

Sections:

1. Title (H1)
2. Status
3. Context and Problem Statement
4. 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:

1. Free-form prose (2-3 sentences)
2. Illustrative story
3. 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.