Architecture Decision Records

Document and track architecture decisions using industry-standard ADR formats including MADR, Nygard, Structurizr, and Y-Statement

February 5, 2026

The ADR directory stores Architecture Decision Records. ADRs capture important technical decisions along with their context, rationale, and consequences, creating a permanent record that helps teams understand why architectural choices were made.

Supported ADR Formats

MADR

Markdown Any Decision Records. The most detailed format with problem statements, technical stories, considered options with pros/cons, and decision outcomes. Ideal for complex decisions requiring detailed analysis.

Nygard

The original ADR format created by Michael Nygard. A straightforward structure with context, decision, and consequences. Perfect for simple, clear-cut architectural decisions.

Structurizr

Compatible with Structurizr tooling. Similar to Nygard format with context, decision, and consequences. Useful when integrating with Structurizr-based architecture documentation.

Y-Statement

A concise format focusing on a single declarative statement. Captures decisions in a structured sentence format: In the context of X, facing Y, we decided Z. Best for rapid documentation.

Format Comparison

Each format includes different sections based on its documentation philosophy:

Section	MADR	Nygard	Structurizr	Y-Statement
Context	Yes	Yes	Yes	No
Problem Statement	Yes	No	No	No
Technical Story	Yes	No	No	No
Decision	Yes	Yes	Yes	No
Decision Outcome	Yes	No	No	No
Considered Options	Yes	No	No	No
Consequences	Yes	Yes	Yes	No
Y-Statement	No	No	No	Yes
Notes	Yes	Yes	Yes	Yes

Creating an ADR

ADR Statuses

Track the lifecycle of each decision:

Best Practices

Learn more

Getting Started with ADRs

Document architectural decisions with Architecture Decision Records. NeoArc supports multiple ADR formats with status tracking, markdown export, and linked diagrams.

ADR Formats

Choose from four ADR formats: Nygard for classic simplicity, Structurizr for architecture focus, MADR for options analysis, or Y-Statement for single-sentence decisions.

ADR Workflows

Manage the ADR lifecycle from draft to accepted. Export to markdown, organise with directories, and track decision evolution over time.

Architecture Decision Records

Capture architectural decisions in structured, searchable formats that live alongside your code. NeoArc Studio supports 4 industry-standard ADR formats with full editor and viewer components.