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