SuperMonstor avatar

adr

Automatically detect architectural decisions and propose creating ADRs (Architecture Decision Record

by SuperMonstor|Open Source

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
Download Skill