How to Create an Architecture Decision Record
Step-by-step guide to creating Architecture Decision Records in NeoArc Studio, covering four ADR formats (Nygard, MADR, Structurizr, Y-Statement), status management, linking, and Markdown export.
Goal
Create an Architecture Decision Record (ADR) using one of four supported formats. Document the context, decision, and consequences. Set the status, link to related diagrams and ADRs, and export to Markdown for external consumption.
Step 1: Navigate to the ADR Directory
Step 2: Create a New ADR
Step 3: Choose an ADR Format
NeoArc Studio supports four ADR formats. Select the format from the Type dropdown. The editor shows different fields based on the chosen format.
| Format | Best For | Sections |
|---|---|---|
| Nygard | Quick, concise decisions with minimal ceremony | Context, Decision, Consequences |
| MADR (Markdown Any Decision Record) | Decisions requiring options analysis with pros and cons | Context, Problem, Technical Story, Considered Options (with pros/cons lists), Decision Outcome, Consequences |
| Structurizr | Architecture-focused decisions aligned with Structurizr tooling | Context, Decision, Consequences (same structure as Nygard, architecture-focused) |
| Y-Statement | Maximum brevity: a single structured sentence | Single Y-Statement: "In the context of [situation], facing [concern], we decided [decision] to achieve [goal], accepting [tradeoff]" |
Step 4: Fill In Format-Specific Fields
For Nygard or Structurizr Format
For MADR Format
For Y-Statement Format
Step 5: Set the Status
There are 6 status values, each with a colour-coded badge.
| Status | Colour | When to Use |
|---|---|---|
| Draft | Yellow (#eab308) | Decision is being written, not yet proposed |
| Proposed | Blue (#3b82f6) | Decision is under consideration by the review board |
| Accepted | Green (#22c55e) | Decision has been approved and is in effect |
| Rejected | Red (#ef4444) | Decision was declined after review |
| Deprecated | Orange (#f97316) | Decision is no longer valid due to changed circumstances |
| Superseded | Grey (#6b7280) | Decision has been replaced by a newer ADR |
Step 6: Add Links to Diagrams and Other ADRs
Step 7: Export to Markdown
How to Document Risks and NFRs
Step-by-step guide to documenting risks, non-functional requirements, constraints, and assumptions in NeoArc Studio.