Architecture Decision Records

Architecture decisions shape systems for years. Yet most teams document them poorly, if at all. Decisions get buried in meeting notes, lost in chat history, or simply forgotten. When someone asks "why did we choose PostgreSQL?" six months later, nobody remembers.

Architecture Decision Records solve this problem. ADRs capture the context, reasoning, and consequences of significant technical decisions in a structured format that remains useful over time.

Decisions That Live With Your Code

NeoArc Studio stores ADRs as JSON files in your repository, typically in a governance/adr directory. This approach provides significant advantages over external documentation tools.

Four ADR Formats

NeoArc Studio supports four established ADR formats, each suited to different documentation needs. Choose the format that matches how your team thinks about decisions.

Nygard Format

The original ADR format created by Michael Nygard. Simple and focused with three core sections: Context, Decision, and Consequences. Best for straightforward decisions where the reasoning is clear.

Rendered using the ADR content block

Structurizr Format

Similar to Nygard but designed for architecture documentation. Uses the same Context, Decision, Consequences structure with an architecture-first perspective. Integrates well with C4 model documentation.

Rendered using the ADR content block

MADR Format

Markdown Any Decision Record (MADR) provides an extended format with explicit options analysis. Each considered option includes a description, pros, and cons. The format makes it clear that alternatives were evaluated and shows the reasoning behind the final choice.

Rendered using the ADR content block

Y-Statement Format

The most concise format, capturing the entire decision in a single structured sentence. The pattern follows: "In the context of [situation], facing [concern], we decided [decision] to achieve [goal], accepting [tradeoff]." Best for quick decisions or as summaries of longer ADRs.

Rendered using the ADR content block

ADR Lifecycle

Decisions evolve over time. NeoArc Studio tracks ADR status through six states:

Editor Features

The ADR editor adapts to each format type, showing only the relevant fields. Common features across all formats include:

• Metadata: ID, title, status, date, deciders, and tags
• Markdown content: Rich text editing for all content fields
• Links: Connect ADRs to related diagrams, other ADRs, and external references
• Auto-generated IDs: Sequential ADR numbering (ADR-0001, ADR-0002, etc.)
• Markdown export: Generate standard markdown files for external tools

Embedding ADRs in Documentation

ADRs can be embedded directly in Content Foundry pages using the ADR content block. This allows you to reference decisions in context, showing the full ADR content inline rather than requiring readers to navigate to a separate location. The examples on this page demonstrate this capability.

Getting Started

To create your first ADR:

Best Practices

Effective ADRs share common characteristics:

• Record decisions when they are made: Context fades quickly. Capture the reasoning while it is fresh.
• Include rejected alternatives: Future readers will wonder why you did not choose the obvious alternative. Tell them.
• Be specific about consequences: Vague consequences are not useful. "Performance may be affected" tells readers nothing. "Query latency increases by 50ms for cross-region requests" is actionable.
• Link to related decisions: Architectural decisions often depend on or constrain other decisions. Make these relationships explicit.
• Update status, do not delete: When decisions change, mark the old ADR as superseded and create a new one. The history matters.