adr

SuperMonstor's avatarfrom SuperMonstor

Automatically detect architectural decisions and propose creating ADRs (Architecture Decision Records). Activate when user discusses choosing between options for data models, API design, system architecture, storage solutions, deployment strategies, caching approaches, authentication methods, error handling patterns, performance optimizations, or any decision that impacts system design. Always ask "Should I create an ADR for this decision?" when detected.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 9, 2026
[Architecture Design]

When & Why to Use This Skill

This Claude skill automates the documentation of critical technical choices by detecting architectural discussions and proposing the creation of Architecture Decision Records (ADRs). It helps engineering teams maintain a clear, searchable history of system design decisions, covering aspects like data modeling, API contracts, and deployment strategies to prevent technical debt and improve team alignment.

Use Cases

  • Database Selection & Schema Design: Automatically capture the rationale, benefits, and trade-offs when choosing between SQL and NoSQL or defining complex data relationships.
  • API Contract Governance: Ensure every major decision regarding endpoint design, versioning strategies, and request/response formats is documented for long-term maintainability.
  • Infrastructure & Deployment Strategy: Record the reasoning behind choosing specific cloud services, containerization methods, or CI/CD pipeline structures to provide context for future audits.
  • System Pattern Alignment: Track the adoption of architectural patterns such as event-driven design, microservices, or CQRS to ensure all stakeholders understand the chosen implementation path.
  • Security & Performance Optimization: Document decisions related to authentication methods, caching strategies, and error handling patterns to maintain high standards of system reliability.
nameadr
descriptionAutomatically detect architectural decisions and propose creating ADRs (Architecture Decision Records). Activate when user discusses choosing between options for data models, API design, system architecture, storage solutions, deployment strategies, caching approaches, authentication methods, error handling patterns, performance optimizations, or any decision that impacts system design. Always ask "Should I create an ADR for this decision?" when detected.
allowed-tools[Read, Write, Glob, Bash]

ADR (Architecture Decision Record) Skill

You are responsible for detecting and documenting architectural decisions.

When to Propose an ADR

Monitor conversations for decisions that affect:

  • Data model (schema changes, storage format, data relationships)
  • Module boundaries (service separation, code organization, domain boundaries)
  • API contracts (endpoint design, request/response formats, versioning)
  • Caching strategy (what to cache, TTL, invalidation)
  • Architecture patterns (event-driven, pub/sub, pipelines, CQRS)
  • Branching strategy (git workflow, release process)
  • Deployment method (containerization, serverless, infrastructure)
  • Storage choice (SQL vs NoSQL, file storage, blob storage)
  • Service boundaries (microservices, monolith, service mesh)
  • CI/CD structure (build pipeline, testing strategy, deployment automation)
  • Performance constraints (latency requirements, throughput, scalability)
  • Integration patterns (webhooks, polling, streaming)
  • Authentication/Authorization (auth strategy, session management, permissions)
  • Error handling (retry logic, circuit breakers, fallbacks)

When You Detect an Architectural Decision

Ask the user: "This decision affects [aspect]. Should I create an ADR to document this?"

ADR Template

Use this flexible template (omit sections not relevant to the conversation):

# Decision: [Short Title]

Date: [YYYY-MM-DD]

## Context

[What led to this decision? What requirements, constraints, or problems exist?]

## Approach

[Describe the overall workflow, methodology, or implementation approach - this is often the most important section]

## Options Considered

[ONLY include if alternatives were explicitly discussed in the conversation]
- Option A: [brief description]
- Option B: [brief description]

## Decision Rationale

[Why this approach was chosen - key reasoning and goals]

## Trade-offs

[ONLY include if discussed - structure flexibly based on what was mentioned]

**Benefits:**
- [benefit 1]
- [benefit 2]

**Costs:**
- [tradeoff 1]
- [tradeoff 2]

**Impact:**
- [what systems/modules/workflows this affects]

ADR Numbering

  1. Check /docs/adr/ for existing ADRs
  2. Use sequential numbering: 0001, 0002, etc.
  3. Format: /docs/adr/NNNN-kebab-case-title.md
  4. Never overwrite existing ADRs

ADR Index Maintenance

After creating an ADR, update /docs/adr/index.md:

# Architecture Decision Records

1. [0001 - Decision Title](0001-decision-title.md)
2. [0002 - Another Decision](0002-another-decision.md)

Rules

  • Keep ADRs concise (not essays)
  • One decision per ADR
  • Always update the index
  • Use today's date
  • Focus on traceability, not perfection