tomevault-io 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)
Converted and distributed by TomeVault — claim your Tome and manage your conversions.