If you’ve tried using traditional Architecture Decision Records (ADRs) with AI coding assistants, you’ve likely hit a wall: the AI has to parse prose to understand decisions, metadata queries are impossible, and compliance tracking is manual. The format works for humans, but machines struggle.

Structured MADR solves this. It extends the popular MADR (Markdown Any Decision Records) format with YAML frontmatter for metadata, comprehensive option analysis with risk assessments, and required audit sections for compliance tracking. It’s ADRs designed for the age of AI-assisted development.

The complete specification and templates are available at github.com/zircote/structured-madr.

The Problem with Traditional ADRs

Traditional ADR formats excel at capturing decisions for human readers. They document the “why” behind architectural choices, preserve context, and create historical records. But they have limitations when you need programmatic access:

No structured metadata: Want to find all accepted ADRs tagged “security”? You’re grepping through prose or parsing markdown headings. There’s no standard frontmatter.

Limited queryability: Questions like “show me all database-related decisions made by the architecture team” require custom parsing logic. Each project structures metadata differently.

Manual compliance tracking: Auditing code against ADRs means reading every decision, extracting requirements, and checking implementations by hand. There’s no machine-readable way to track audit status.

AI context challenges: When an AI assistant needs to understand your architectural decisions, it must read and parse full documents. Without structured metadata, it can’t quickly filter relevant decisions or understand relationships between them.

These limitations matter more as codebases grow and AI assistants become core development tools. You need ADRs that work for both human readers and automated systems.

Introducing Structured MADR

Structured MADR extends MADR with three key additions:

YAML frontmatter: Every ADR starts with structured metadata that tools can query without parsing prose. Status, tags, technologies, dates, authors, and relationships are all explicit.

Comprehensive option analysis: Each considered option includes technical, schedule, and ecosystem risk assessments alongside standard pros and cons. Consequences are split into positive, negative, and neutral categories.

Required audit section: A dedicated section for recording compliance findings over time. Each audit gets dated entries with findings tables showing implementation status.

Here’s what the frontmatter looks like:

---
title: "Use PostgreSQL for Primary Storage"
description: "Decision to adopt PostgreSQL for the application database"
type: adr
category: architecture
tags:
  - database
  - postgresql
  - storage
status: accepted
created: 2026-01-15
updated: 2026-01-15
author: Architecture Team
project: my-app
technologies:
  - postgresql
  - rust
audience:
  - developers
  - architects
related:
  - adr_0001.md
---

This metadata enables programmatic queries: “Find all accepted ADRs about databases in the my-app project” becomes a simple filter operation instead of full-text search.

The Machine-Readable Advantage

The YAML frontmatter transforms ADRs from documentation into queryable data structures. This enables:

Programmatic querying: Scripts can filter by any metadata field. Find all accepted ADRs, all security decisions, all PostgreSQL-related choices, or all decisions made in the last quarter.

Automated index generation: Generate navigation pages, decision matrices, or compliance dashboards automatically. The metadata is already structured.

AI context injection: Language models can scan frontmatter to identify relevant decisions without reading full documents. This saves tokens and improves response accuracy.

Documentation pipeline integration: Static site generators, documentation tools, and CI systems can consume ADRs as structured data, not just markdown files.

Compliance automation: Track which decisions need auditing, which have current audits, and which are violated. Status, dates, and author tracking are built-in.

The format bridges the gap between human-readable documentation and machine-processable data. Humans read the markdown prose, machines query the YAML metadata.

AI Discovery and Context Management

In AI-assisted development, context is everything. AI coding assistants work better when they understand your architectural decisions, but feeding them dozens of ADR documents consumes massive token budgets and slows responses.

Structured MADR’s frontmatter solves this:

Fast filtering: An AI can scan status: accepted and tags: [security, authentication] to identify the 3 relevant decisions out of 50 total ADRs. No need to read full documents for initial discovery.

Explicit relationships: The related field creates a decision graph. When working on authentication, the AI can automatically pull in related authorization and session management decisions.

Freshness tracking: created and updated timestamps help AI assistants understand decision age. Recent decisions might still be under implementation, older ones are likely stable.

Scope awareness: The project, category, and tags fields let AI tools scope decisions to specific contexts. A microservice’s authentication decisions don’t need to consider monolith patterns.

Technology targeting: The technologies array helps AI assistants apply decisions correctly. A PostgreSQL decision doesn’t apply to a Redis cache implementation.

Audience filtering: The audience field indicates who needs to know about this decision. Backend developers don’t need frontend build tool decisions.

This structured approach transforms ADRs from passive documentation into active context for AI assistants. The assistant reads metadata first, then fetches full content only for relevant decisions.

The ADR Plugin for Claude Code

The ADR plugin provides full lifecycle management for Structured MADR in Claude Code:

/adr-new command: Creates properly formatted ADRs with all frontmatter fields, decision drivers hierarchy, risk assessments, and audit sections. Template selection lets you choose between Structured MADR, standard MADR, Nygard, or Y-Statement formats.

/adr-new "Use PostgreSQL for Primary Storage"

This generates a complete ADR skeleton with placeholder sections, properly structured frontmatter, and guidance comments. Fill in the decision details, delete the guidance, and you’re done.

/adr-list and /adr-search commands: Query ADRs using frontmatter metadata. Find accepted decisions, search by tag, filter by status, or scope to specific projects.

/adr-list status:accepted tags:database
/adr-search "PostgreSQL AND authentication"

The search leverages both metadata and full-text content, returning relevant decisions with context snippets.

adr-compliance agent: Audits your codebase against accepted ADRs. It reads decision requirements from ADRs, searches code for compliance evidence and violations, then appends audit findings to the ADR’s audit section.

The agent creates dated audit entries with findings tables showing which files comply, which violate, and which requirements have gaps. This automated compliance checking catches architectural drift early.

adr-author agent: Proactively detects architectural discussions in conversations and offers to capture them as ADRs. When you’re debating database choices or discussing authentication strategies, the agent recognizes the context and suggests creating a decision record.

This prevents the common problem where teams make architectural decisions in chat or PRs but forget to document them formally.

Skill documentation: The plugin includes interactive skill documentation that teaches the format through examples. Claude Code learns how to structure decisions, write effective option analyses, and create meaningful audit sections.

The combination of commands, agents, and skills provides end-to-end ADR lifecycle support: creation, querying, auditing, and opportunistic capture.

When to Use Structured MADR

Structured MADR adds overhead compared to simpler formats. Use it when that overhead provides value:

Compliance-focused organizations: If you need audit trails for SOC2, HIPAA, or industry regulations, the built-in audit section and metadata tracking justify the structure.

Teams using AI coding assistants: When Claude Code, GitHub Copilot, or Cursor are active development tools, machine-readable metadata improves AI context quality significantly.

Large codebases with many decisions: Projects with 20+ ADRs benefit from programmatic querying. Humans can’t keep all decisions in working memory, tools can.

Long-lived projects: Systems maintained for years need comprehensive decision history. The audit section shows how adherence evolves over time.

Organizations wanting decision analytics: If you plan to analyze decision patterns, measure time-to-decision, or generate compliance reports, structured metadata enables this.

The format scales well: it’s not overkill for 10 ADRs, and it remains manageable at 100+.

When NOT to Use Structured MADR

Don’t use Structured MADR for every decision:

Quick, informal decisions: For minor choices or temporary workarounds, Nygard format or Y-Statement format is sufficient. Structured MADR’s comprehensiveness slows you down unnecessarily.

Small teams with minimal process: If your team is 2-3 developers who discuss architecture constantly, the formality is overhead without benefit. Use whatever captures decisions fastest.

Prototypes or throwaway projects: Code that will be rewritten or discarded doesn’t need comprehensive ADRs. Document if it helps thinking, but don’t add formal metadata.

When traceability doesn’t matter: If nobody will audit decisions against code or query the decision history, simpler formats suffice.

The key question: will you programmatically query, audit, or analyze these decisions? If not, use a lighter format.

Format Comparison

How does Structured MADR compare to other ADR formats?

Format Frontmatter Sections Risk Assessment Audit Support Complexity
Structured MADR Required YAML 9 comprehensive Per-option (3 types) Built-in audit section High
MADR Optional 5 standard No No Medium
Nygard No 4 minimal No No Low
Y-Statement No 1 (single sentence) No No Very Low
Tyree-Akerman No 6 detailed No No Medium-High

Structured MADR is the most comprehensive format, suitable for projects needing full traceability and machine readability.

MADR balances structure with simplicity. Good for most projects that don’t need automated compliance.

Nygard is the original ADR format: minimal sections, fast to write, sufficient for basic decision recording.

Y-Statement captures decisions in a single sentence: “In the context of X, facing Y, we decided Z to achieve A, accepting B.” Ultra-lightweight.

Tyree-Akerman adds architectural views and quality attribute analysis to traditional ADRs. Comprehensive but human-focused.

Choose based on project needs: lightweight formats for speed, structured formats for automation and compliance.

The Audit Section

The required audit section is what makes Structured MADR compliance-ready. It provides a standardized location for recording verification results over time.

Each audit gets a dated subsection:

## Audit

### 2026-01-15

**Status:** Compliant

**Findings:**

| Finding | Files | Lines | Assessment |
|---------|-------|-------|------------|
| PostgreSQL connection pooling implemented | `src/db/pool.py` | L12-45 | compliant |
| Prepared statements used consistently | `src/api/*.py` | multiple | compliant |
| Connection strings in environment vars | `.env.example`, `config.py` | L8, L34 | compliant |

**Summary:** All database access follows the ADR. No violations found.

**Action Required:** None

For violations:

### 2026-02-20

**Status:** Violated

**Findings:**

| Finding | Files | Lines | Assessment |
|---------|-------|-------|------------|
| SQLAlchemy ORM used instead of raw SQL | `src/features/reports.py` | L15-89 | violation |
| String formatting in query | `src/api/search.py` | L45 | violation |

**Summary:** Reports feature bypasses decision by using SQLAlchemy ORM. Search endpoint uses string formatting (SQL injection risk).

**Action Required:**
- Rewrite reports feature to use psycopg2 with prepared statements
- Refactor search.py L45 to use parameterized query
- Add pre-commit hook to prevent SQLAlchemy imports

The audit section creates a compliance timeline showing whether adherence improves or degrades. Multiple audits track how decisions are maintained (or violated) as the codebase evolves.

This historical record is valuable during architectural reviews, incident postmortems, and compliance audits. You can demonstrate that decisions were followed or explain when and why they weren’t.

Real-World Origin

Structured MADR emerged from a practical need. The Subcog project required comprehensive documentation for 60+ architectural decisions with full audit trails. Standard MADR lacked machine-readable metadata, making it difficult to track decision status, query by technology, or automate compliance checking.

The format proved valuable enough to standardize as an open specification at github.com/zircote/structured-madr and integrate into the ADR plugin. Other projects with similar needs, compliance requirements, or AI assistant integration have adopted it.

Getting Started

To start using Structured MADR:

1. Install the ADR plugin from the Claude Code marketplace:

/plugin add https://github.com/zircote/marketplace
/plugin install adr

2. Configure it to use Structured MADR by default:

Edit your project’s .claude/settings.json:

{
  "plugins": {
    "adr": {
      "default_format": "structured-madr",
      "storage_location": "docs/adrs/"
    }
  }
}

3. Create your first ADR:

/adr-new "Your First Architectural Decision"

The plugin creates a properly formatted ADR skeleton with all sections and metadata fields. Fill in your decision details, option analysis, and consequences.

4. Try querying your ADRs:

/adr-list
/adr-search tags:security

As you add more ADRs, the metadata-based querying shows its value.

5. Run a compliance audit:

/adr-compliance

The compliance agent analyzes your code against accepted decisions and adds audit findings to each ADR.

The format has a learning curve, but the plugin handles most of the complexity. You focus on decision content, the tooling manages structure.

The Structured MADR specification is maintained at github.com/zircote/structured-madr with templates, examples, and full documentation. Implementation support is available through the ADR plugin for Claude Code. For interactive format documentation, see the skill guide.