create-adr
Create Architecture Decision Records (ADRs) to document significant technical decisions, their context, alternatives considered, and consequences. Use when making architectural choices, selecting libraries/frameworks, or designing system components.
When & Why to Use This Skill
The Create ADR skill automates the generation of Architecture Decision Records (ADRs) to capture the 'why' behind critical technical choices. By systematically documenting context, alternatives, and consequences, it ensures long-term maintainability and provides future developers with essential institutional knowledge regarding system design, library selections, and architectural trade-offs.
Use Cases
- Technology Selection: Documenting the rationale for choosing specific databases, frameworks, or libraries (e.g., Redis vs. Memcached) to ensure team alignment.
- System Component Design: Outlining the architecture of new microservices, modules, or API structures before implementation begins.
- Major Refactoring: Recording the technical trade-offs and risks accepted when restructuring core system logic or changing system patterns.
- Institutional Knowledge Retention: Providing a historical log of decisions for new team members to understand the evolution of the codebase.
- Compliance and Auditing: Maintaining a formal record of significant technical changes and the decision-making process for governance purposes.
| name | create-adr |
|---|---|
| description | Create Architecture Decision Records (ADRs) to document significant technical decisions, their context, alternatives considered, and consequences. Use when making architectural choices, selecting libraries/frameworks, or designing system components. |
Create ADR Skill
Purpose: Document architectural decisions to provide context for future developers and maintain institutional knowledge about why technical choices were made.
When to Use This Skill
Trigger this skill when:
- Making significant architectural decisions
- Choosing between competing technologies or approaches
- Designing new system components or APIs
- Refactoring that changes system structure
- After implementing a feature that involved design trade-offs
Skip ADR Creation If
- Only minor bug fixes or refactoring
- Documentation or test-only changes
- Configuration tweaks without architectural impact
- Trivial changes with obvious implementation
Workflow
1. Gather Context
Review the implementation to understand:
- What technical decisions were made
- Why this approach was chosen
- What alternatives existed
- What trade-offs were accepted
If reviewing existing code:
git diff main...HEAD
git log --oneline main..HEAD
2. Investigate Further
If the diff doesn't provide enough context:
- Read referenced files/functions
- Check configuration files
- Review related tests
- Look at dependencies added
3. Create the ADR
Location: docs/adr/NNNN-descriptive-title.md
Naming convention:
- Sequential number (0001, 0002, etc.)
- Lowercase with hyphens
- Descriptive but concise
Examples:
0001-use-jwt-for-authentication.md0002-adopt-event-sourcing-for-orders.md0003-postgres-over-mysql.md
4. Use the Template
Use the template from assets/adr-template.md to structure the document.
Key sections to complete:
- Status: Proposed, Accepted, Deprecated, or Superseded
- Context: The problem or opportunity driving the decision
- Decision: What was decided and the technical approach
- Consequences: Positive, negative, and risks
- Alternatives: What else was considered and why it wasn't chosen
Quality Guidelines
Good ADRs have:
- Specific technical details (not vague descriptions)
- Concrete examples and code snippets where helpful
- Honest assessment of trade-offs
- Links to relevant resources or prior art
Avoid:
- Vague justifications ("it's better")
- Missing alternatives section
- No discussion of consequences
- Too much implementation detail (that belongs in code comments)
Example
User: "Document the decision to use Redis for caching"
Skill activates:
- Review caching implementation
- Identify alternatives considered (Memcached, in-memory, etc.)
- Document trade-offs (complexity vs performance)
- Create
docs/adr/0005-redis-for-application-cache.md
Integration
Works well with:
- Major feature implementations
- System refactoring efforts
- Technology migrations
- API design decisions