doc-generate-adr

Generate Architecture Decision Records (ADRs) to document significant architectural decisions. Use when making important technical decisions that need documentation.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the generation of Architecture Decision Records (ADRs), enabling engineering teams to systematically document critical technical choices, rationale, and trade-offs. By capturing the 'why' behind architectural shifts in a standardized format, it ensures long-term project maintainability, improves team alignment, and preserves institutional knowledge.

Use Cases

  • Documenting Technology Selection: Record the detailed rationale and comparison data when choosing specific frameworks, databases, or cloud providers for a project.
  • Capturing Design Trade-offs: Formally document the pros, cons, and consequences of architectural patterns (e.g., Microservices vs. Monolith) to provide context for future developers.
  • Standardizing Engineering Workflows: Implement a consistent ADR structure across distributed teams to ensure all major technical pivots are documented uniformly.
  • Facilitating Code Reviews and Audits: Use generated ADRs as a reference point during architectural reviews to justify design decisions to stakeholders and auditors.
  • Onboarding New Developers: Provide a historical log of architectural evolution, helping new team members understand the constraints and decisions that shaped the current codebase.
namedoc-generate-adr
descriptionGenerate Architecture Decision Records (ADRs) to document significant architectural decisions. Use when making important technical decisions that need documentation.
mcp_fallbacknone
categorydoc

Generate ADR Skill

Create Architecture Decision Records for technical decisions.

When to Use

  • Making significant architectural decisions
  • Choosing between technical alternatives
  • Documenting design trade-offs
  • Recording rationale for future reference

Quick Reference

./scripts/create_adr.sh "Decision Title"
# Creates: docs/adr/ADR-XXX-decision-title.md

Workflow

  1. Identify decision - What choice needs documentation?
  2. Research alternatives - Gather evidence and performance data
  3. Create ADR - Run script with title
  4. Fill sections - Context, Decision, Rationale, Consequences, Alternatives
  5. Review - Get team approval
  6. Update status - Change from "Proposed" to "Accepted"

ADR Format

All ADRs follow this structure:

# ADR-XXX: Title

**Status**: Proposed | Accepted | Deprecated | Superseded
**Date**: YYYY-MM-DD
**Deciders**: Names/roles

## Context
What is the issue we're facing?

## Decision
What decision are we making?

## Rationale
Why this decision? Key reasons.

## Consequences
### Positive
- Benefit 1

### Negative
- Drawback 1

### Neutral
- Other impact 1

## Alternatives Considered
### Alternative 1
Why not chosen.

Status Lifecycle

  • Proposed - Under consideration
  • Accepted - Decision made and active
  • Deprecated - No longer recommended
  • Superseded - Replaced by newer ADR

Storage Location

docs/adr/
├── ADR-001-language-selection.md
├── ADR-002-testing-strategy.md
└── README.md

Error Handling

Issue Fix
Missing context Add background and constraints
Unclear decision Make decision more specific
Missing alternatives Document at least 2 alternatives
No consequences Think through positive and negative impacts

References

  • See existing ADRs in /docs/adr/ for examples
  • Related skill: phase-plan-generate for planning