Skip to content
Structured MADR
Frontmatter meets the record, gate-checked A machine-cyan frontmatter block flows into a human-amber decision record, joined by a validated-checkmark gate badge below. METADATA MEETS THE RECORD frontmatter · machine-parseable status: accepted risk: medium drivers: [cost, latency] relates_to: [...] decision record · human-readable ## Use a managed queue over self-hosted structured-madr Action · gate-checked

Structured MADR

The decision a person writes and the metadata a parser filters on — one record, both readers, gate-checked before it merges.
Getting StartedSchema Reference

Structured MADR is an extension of MADR (Markdown Architectural Decision Records) that adds YAML frontmatter for machine-readable metadata, comprehensive option analysis with risk assessments, and required audit sections for compliance tracking.

Why Structured MADR?

Section titled “Why Structured MADR?”

Traditional ADR formats were designed for human readers. While they capture decisions effectively, they lack machine-readable metadata for programmatic access, structured risk assessment for option evaluation, audit trails for compliance verification, and explicit relationships between decisions.

Structured MADR addresses these gaps while remaining fully human-readable and compatible with existing ADR workflows.

Key Features

Section titled “Key Features”

YAML Frontmatter

Machine-parseable metadata for tooling integration. Filter, search, and query your decisions programmatically.

Risk Assessment

Evaluate technical, schedule, and ecosystem risk for every considered option with a structured three-dimension model.

Audit Trail

Built-in compliance tracking with findings tables. Meet SOC2, HIPAA, and ISO 27001 requirements.

AI-Ready

Structured metadata enables AI tools like Claude Code, GitHub Copilot, and Cursor to filter, understand, and surface relevant decisions.

Section titled “Quick Links”
Getting StartedCreate your first Structured MADR in under 5 minutes
Schema ReferenceComplete JSON Schema field reference
GitHub ActionAutomated CI/CD validation for your ADRs
TemplatesFull and bare templates ready to use
Why Structured MADRMotivation and ideal use cases
Format ComparisonHow Structured MADR compares to other ADR formats

At a Glance

Section titled “At a Glance”
Feature Description
YAML Frontmatter Machine-parseable metadata for tooling integration
Hierarchical Drivers Primary and secondary decision drivers
Risk Assessment Technical, schedule, and ecosystem risk per option
Split Consequences Positive, negative, and neutral outcomes
Audit Section Built-in compliance tracking with findings tables
Explicit Relationships Typed links between related decisions

Current Version

Section titled “Current Version”
  • Specification: 1.0.0
  • Schema: 1.0.0
  • Project: 1.1.0