home / skills / dexploarer / hyper-forge / architecture-decision-recorder

architecture-decision-recorder skill

safe

/.claude/skills/architecture-decision-recorder

This skill helps you create and manage Architecture Decision Records to document decisions, tradeoffs, and rationales for architectural history.

npx playbooks add skill dexploarer/hyper-forge --skill architecture-decision-recorder

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.8 KB

---
name: architecture-decision-recorder
description: Create and manage Architecture Decision Records (ADRs) for documenting important architectural decisions, tradeoffs, and rationale.
allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
---

# Architecture Decision Recorder

Systematically document architectural decisions using the ADR pattern.

## When to Use

- Documenting significant architectural decisions
- Recording technology choices
- Tracking design tradeoffs
- Maintaining architectural history
- Facilitating team communication

## ADR Template

```markdown
# ADR-NNNN: [Title]

**Date:** YYYY-MM-DD
**Status:** [Proposed | Accepted | Deprecated | Superseded]
**Decision Makers:** [Names]

## Context

What is the issue we're trying to solve? What are the forces at play?

### Business Context
- Business goal or requirement
- Constraints (time, budget, team)
- Stakeholder concerns

### Technical Context  
- Current system state
- Technical constraints
- Integration requirements

## Decision

We will [decision statement].

### Rationale
Why this approach over alternatives?

## Consequences

### Positive
- Benefit 1
- Benefit 2

### Negative  
- Tradeoff 1
- Tradeoff 2

### Risks
- Risk 1 → Mitigation strategy
- Risk 2 → Mitigation strategy

## Alternatives Considered

### Option 1: [Name]
**Pros:** [List]
**Cons:** [List]  
**Rejected because:** [Reason]

### Option 2: [Name]
**Pros:** [List]
**Cons:** [List]
**Rejected because:** [Reason]

## Implementation

- [ ] Action item 1
- [ ] Action item 2

## References

- [Link to research]
- [Related ADR]
```

## Best Practices

- ✅ Create ADRs for all major decisions
- ✅ Keep ADRs immutable (supersede, don't edit)
- ✅ Store in version control
- ✅ Link related ADRs
- ✅ Review quarterly
- ✅ Include quantitative data

## Related Commands

- `/adr-create` - Create new ADR

Overview

This skill creates and manages Architecture Decision Records (ADRs) to capture important architectural decisions, tradeoffs, and rationale. It provides a consistent ADR template, enforces best practices like immutability and version control, and helps teams maintain an accessible architectural history. Use it to improve transparency and onboarding across engineering and product teams.

How this skill works

The skill scaffolds ADRs using a standard template with sections for context, decision, rationale, consequences, alternatives, and implementation actions. It automates numbering, date stamping, status tracking, and linking of related ADRs, and generates Markdown files ready for version control. You can create, view, and supersede ADRs while preserving previous records.

When to use it

Before making or formalizing any major architectural or technology choice
When evaluating tradeoffs between frameworks, services, or system designs
To capture decisions that affect multiple teams or long-term maintenance
When onboarding new engineers who need historical context
During architecture reviews, design docs, or roadmap planning

Best practices

Create ADRs for decisions that change system shape, dependencies, or costs
Keep ADRs immutable: supersede older records instead of editing them
Store ADRs in the repository and link them from design docs and tickets
Include measurable data and clear mitigation strategies for risks
Review ADRs periodically (quarterly) to validate status and relevance

Example use cases

Choosing between self-hosted services and managed cloud offerings
Selecting a TypeScript architecture pattern or module boundary approach
Documenting the decision to adopt or deprecate a third-party library
Recording migration plans and tradeoffs when refactoring core systems
Capturing cross-team API contract decisions and rollout strategies

FAQ

How should I update an ADR when requirements change?

Do not edit the original ADR. Create a new ADR that supersedes the previous one, reference the older record, and explain the new context and rationale.

What decisions merit an ADR?

Focus on decisions that impact architecture, scalability, security, costs, or long-term maintenance and that require team alignment or future traceability.