Adr Format Nygard

Nygard ADR Format

The Nygard format is the original ADR template created by Michael Nygard in 2011. It is simple, focused, and widely adopted as the classic ADR format.

About Nygard Format

The Nygard format is:

• Simple - Five sections only
• Focused - Emphasizes context, decision, consequences
• Value-neutral - Context describes facts without judgment
• Concise - Designed for quick documentation

Template Structure

# {NUMBER}. {TITLE}

Date: {DATE}

## Status

{STATUS}

## Context

{Describe the forces at play}

## Decision

{State what was decided}

## Consequences

{Describe the resulting context}

Section Guide

Title

Format: # {NUMBER}. {TITLE}

Example: # 4. Use REST for External APIs

Date

The date the decision was made or proposed.

Format: YYYY-MM-DD or natural date

Status

What is the status of this decision?

Values: Proposed, Accepted, Deprecated, Superseded by ADR-XXX

Context

Describe the forces at play:

• Technological factors
• Political factors
• Social factors
• Project-specific factors

Key principle: Language should be value-neutral. Describe facts, not opinions.

Good example:

## Context

The mobile team needs to integrate with our backend services. They have
expertise in React Native and prefer RESTful APIs. Our current internal
services use gRPC, which would require significant mobile-side changes.
External API traffic is expected to be 10% of total traffic.

Decision

State what was decided:

• Record what was decided, not how it was reached
• Keep it brief and direct
• Use active voice

Good example:

## Decision

We will expose external APIs using REST over HTTPS. Internal services
will continue using gRPC. A gateway service will translate between
REST and gRPC for external requests.

Consequences

Describe the resulting context:

• List all consequences, not just positive ones
• Include positive, negative, and neutral outcomes
• Consider future implications

Good example:

## Consequences

External consumers will have a familiar REST interface to work with.
The mobile team can use their existing REST client libraries. We
will need to maintain two API styles (REST external, gRPC internal).
The gateway introduces an additional point of failure and latency.
API versioning will need a clear strategy for the REST endpoints.

When to Use Nygard Format

Best for:

• Quick decision documentation
• Straightforward technical choices
• Teams preferring simplicity
• Decisions with clear single option

Consider other formats when:

• Multiple options need detailed comparison
• Complex trade-off analysis required
• Detailed pros/cons documentation needed

Nygard Format Best Practices

Context Section

• Do describe forces objectively
• Do include constraints
• Don’t include opinions or preferences
• Don’t justify the decision here

Decision Section

• Do state the decision clearly
• Do be specific and actionable
• Don’t explain the reasoning (that’s in consequences)
• Don’t list alternatives

Consequences Section

• Do list all consequences
• Do include negatives
• Don’t only list benefits
• Don’t hide trade-offs

Comparison with Other Formats

Aspect	Nygard	MADR
Sections	5	10
Options documented	Implicit	Explicit
Pros/cons	In consequences	Separate section
Complexity	Low	Medium

Additional Resources

Templates

Template available at: ${CLAUDE_PLUGIN_ROOT}/templates/nygard/adr-template.md

Related Skills

• adr-fundamentals - ADR basics and lifecycle management
• adr-quality - Quality criteria and review process
• adr-format-madr - Alternative: Feature-rich MADR format
• adr-format-y-statement - Alternative: Concise Y-Statement format
• adr-format-alexandrian - Alternative: Pattern-based format

External Resources

• Original blog post: Documenting Architecture Decisions by Michael Nygard (2011)