architecture-adr

When making significant architectural decisions that need to be documented. Used by ARCHITECT-AGENT.

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

When & Why to Use This Skill

This Claude skill facilitates the systematic documentation of critical technical choices through Architecture Decision Records (ADRs). It provides a standardized framework for capturing context, evaluating alternative options, and outlining the long-term consequences of architectural shifts, ensuring transparency and maintainability across the software development lifecycle.

Use Cases

  • Technology Stack Selection: Formally documenting the rationale behind choosing specific frameworks, databases, or cloud providers to ensure future alignment.
  • Architectural Pattern Transitions: Recording the decision-making process when moving between patterns, such as transitioning from a monolith to microservices.
  • Structured Option Evaluation: Comparing multiple technical solutions using standardized criteria like effort, risk, scalability, and team expertise.
  • Governance and Compliance: Tracking breaking API changes or security model modifications to maintain a clear audit trail of system evolution.
  • Onboarding and Knowledge Transfer: Providing new team members with a historical context of why certain technical paths were taken or rejected.
namearchitecture-adr
descriptionWhen making significant architectural decisions that need to be documented. Used by ARCHITECT-AGENT.
version1.0.0
tokens~400
confidencehigh
- https//cognitect.com/blog/2011/11/15/documenting-architecture-decisions
last_validated2025-01-10
next_review2025-01-24
tags[architecture, adr, decisions, documentation]

When to Use

When making significant architectural decisions that need to be documented. Used by ARCHITECT-AGENT.

Patterns

ADR Structure

# ADR-001: {Decision Title}

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXX

## Context
{What situation requires a decision?}

## Decision Drivers
- {Driver 1}
- {Driver 2}

## Considered Options
1. **Option A** - {brief description}
2. **Option B** - {brief description}
3. **Option C** - {brief description}

## Decision
We will use **Option B** because {reasoning}.

## Consequences
### Positive
- {benefit 1}

### Negative
- {tradeoff 1}

Option Evaluation

| Criteria | Option A | Option B | Option C |
|----------|----------|----------|----------|
| Effort | High | Medium | Low |
| Risk | Low | Medium | High |
| Scalability | Good | Good | Poor |
| Team expertise | Low | High | Medium |

When to Write ADR

- Technology choice (framework, database, cloud)
- Architecture pattern (monolith vs microservices)
- Integration approach (sync vs async)
- Security model changes
- Breaking changes to APIs

Anti-Patterns

  • Decisions without documented alternatives
  • Missing "why not" for rejected options
  • No consequences section
  • ADR written after implementation
  • Superseded ADRs not linked

Verification Checklist

  • Context explains the problem
  • At least 2 options considered
  • Decision clearly stated with reasoning
  • Both positive and negative consequences
  • Status is current
  • Related ADRs linked