AutoGineer
Generated banner for Architecture Decision Records
Generated logo for Architecture Decision Records

Architecture Decision Records

Seth HobsonCommunityCreated by Seth Hobson

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
— the description by Seth Hobson

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to creating Architecture Decision Records (ADRs). It covers the full lifecycle of technical decision-making, from initial proposal to deprecation. By capturing context, rationale, and consequences, teams can maintain a historical record of why specific technologies or patterns were chosen, facilitating better onboarding, easier reviews, and more consistent architectural evolution.

What it does

  • Defines a standard structure for documenting technical decisions
  • Provides templates for standard, lightweight, and deprecation-focused ADRs
  • Establishes a lifecycle for managing decision status
  • Offers a checklist for reviewing architectural changes
  • Suggests directory structures for organizing documentation
  • Includes guidance on when to document a decision versus when to skip

When to use it

  • When making significant architectural or technology choices
  • When onboarding new team members to explain past design decisions
  • When reviewing historical trade-offs in a project
  • When establishing a formal decision-making process for a team
  • When deprecating old technologies or patterns

Advantages

  • Improves team alignment on technical direction
  • Reduces knowledge silos by documenting the 'why' behind decisions
  • Provides a clear audit trail for architectural evolution
  • Helps teams avoid repeating past mistakes
  • Standardizes the review process for major technical changes

Usage examples

“How should I document the choice of a new database for our project?”
The agent will provide the standard ADR template, guiding you to define context, decision drivers, considered options, and the final rationale.
“We need to replace our current messaging system. How do I record this?”
The agent will guide you to use the deprecation template to link the new decision to the old one, ensuring the history of the change is preserved.
“What should be included in an ADR review?”
The agent will provide a checklist covering context, trade-offs, security implications, and cost, ensuring a thorough review before acceptance.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/wshobson/architecture-decision-records/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip architecture-decision-records.zip -d .agents/skills

Documentation by Seth Hobson

Architecture Decision Records

Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.

When to Use This Skill

  • Making significant architectural decisions

  • Documenting technology choices

  • Recording design trade-offs

  • Onboarding new team members

  • Reviewing historical decisions

  • Establishing decision-making processes

Core Concepts

1. What is an ADR?

An Architecture Decision Record captures:

  • Context: Why we needed to make a decision

  • Decision: What we decided

  • Consequences: What happens as a result

2. When to Write an ADR
Write ADRSkip ADR
New framework adoptionMinor version upgrades
Database technology choiceBug fixes
API design patternsImplementation details
Security architectureRoutine maintenance
Integration patternsConfiguration changes
3. ADR Lifecycle
Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

Before drafting a standard, lightweight, or Y-statement ADR, read decision templates.

Before drafting a deprecation ADR or RFC, read deprecation and RFC templates.

ADR Management

Directory Structure
docs/
├── adr/
│   ├── README.md           # Index and guidelines
│   ├── template.md         # Team's ADR template
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
│   └── 0020-deprecate-mongodb.md      # Supersedes 0003
ADR Index (README.md)
# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for [Project Name].

## Index

| ADR                                   | Title                              | Status     | Date       |
| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |

## Creating a New ADR

1. Copy `template.md` to `NNNN-title-with-dashes.md`
2. Fill in the template
3. Submit PR for review
4. Update this index after approval

## ADR Status

- **Proposed**: Under discussion
- **Accepted**: Decision made, implementing
- **Deprecated**: No longer relevant
- **Superseded**: Replaced by another ADR
- **Rejected**: Considered but not adopted
Automation (adr-tools)
# Install adr-tools
brew install adr-tools

# Initialize ADR directory
adr init docs/adr

# Create new ADR
adr new "Use PostgreSQL as Primary Database"

# Supersede an ADR
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"

# Generate table of contents (to a separate file, so the hand-written
# index and guidelines in README.md are not overwritten)
adr generate toc > docs/adr/toc.md

# Link related ADRs
adr link 2 "Complements" 1 "Is complemented by"

Review Process

## ADR Review Checklist

### Before Submission

- [ ] Context clearly explains the problem
- [ ] All viable options considered
- [ ] Pros/cons balanced and honest
- [ ] Consequences (positive and negative) documented
- [ ] Related ADRs linked

### During Review

- [ ] At least 2 senior engineers reviewed
- [ ] Affected teams consulted
- [ ] Security implications considered
- [ ] Cost implications documented
- [ ] Reversibility assessed

### After Acceptance

- [ ] ADR index updated
- [ ] Team notified
- [ ] Implementation tickets created
- [ ] Related documentation updated

Best Practices

Do's

  • Write ADRs early - Before implementation starts

  • Keep them short - 1-2 pages maximum

  • Be honest about trade-offs - Include real cons

  • Link related decisions - Build decision graph

  • Update status - Deprecate when superseded

Don'ts

  • Don't change accepted ADRs - Write new ones to supersede

  • Don't skip context - Future readers need background

  • Don't hide failures - Rejected decisions are valuable

  • Don't be vague - Specific decisions, specific consequences

  • Don't forget implementation - ADR without action is waste

Files

references/deprecation-rfc-templates.md

Template 4: ADR for Deprecation
# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL

## Status

Accepted (Supersedes ADR-0003)

## Context

ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility
needs. Since then:

- MongoDB's multi-document transactions remain problematic for our use case
- Our schema has stabilized and rarely changes
- We now have PostgreSQL expertise from other services
- Maintaining two databases increases operational burden

## Decision

Deprecate MongoDB and migrate user profiles to PostgreSQL.

## Migration Plan

1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled
2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency
3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor
4. **Phase 4** (Week 6): Remove MongoDB writes, decommission

## Consequences

### Positive

- Single database technology reduces operational complexity
- ACID transactions for user data
- Team can focus PostgreSQL expertise

### Negative

- Migration effort (~6 weeks)
- Risk of data issues during migration
- Lose some schema flexibility

## Lessons Learned

Document from ADR-0003 experience:

- Schema flexibility benefits were overestimated
- Operational cost of multiple databases was underestimated
- Consider long-term maintenance in technology decisions
Template 5: Request for Comments (RFC) Style
# RFC-0025: Adopt Event Sourcing for Order Management

## Summary

Propose adopting event sourcing pattern for the order management domain to
improve auditability, enable temporal queries, and support business analytics.

## Motivation

Current challenges:

1. Audit requirements need complete order history
2. "What was the order state at time X?" queries are impossible
3. Analytics team needs event stream for real-time dashboards
4. Order state reconstruction for customer support is manual

## Detailed Design

### Event Store

OrderCreated { orderId, customerId, items[], timestamp } OrderItemAdded { orderId, item, timestamp } OrderItemRemoved { orderId, itemId, timestamp } PaymentReceived { orderId, amount, paymentId, timestamp } OrderShipped { orderId, trackingNumber, timestamp }


### Projections

- **CurrentOrderState**: Materialized view for queries
- **OrderHistory**: Complete timeline for audit
- **DailyOrderMetrics**: Analytics aggregation

### Technology

- Event Store: KurrentDB, formerly EventStoreDB (purpose-built, handles projections)
- Alternative considered: Kafka + custom projection service

## Drawbacks

- Learning curve for team
- Increased complexity vs. CRUD
- Need to design events carefully (immutable once stored)
- Storage growth (events never deleted)

## Alternatives

1. **Audit tables**: Simpler but doesn't enable temporal queries
2. **CDC from existing DB**: Complex, doesn't change data model
3. **Hybrid**: Event source only for order state changes

## Unresolved Questions

- [ ] Event schema versioning strategy
- [ ] Retention policy for events
- [ ] Snapshot frequency for performance

## Implementation Plan

1. Prototype with single order type (2 weeks)
2. Team training on event sourcing (1 week)
3. Full implementation and migration (4 weeks)
4. Monitoring and optimization (ongoing)

## References

- [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
- [KurrentDB Documentation](https://docs.kurrent.io/)

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs a command-line tool

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Seth Hobson
Publisher
Seth Hobson (Community)
Source
wshobson/agents · plugins/documentation-generation/skills/architecture-decision-records · commit 4bde316
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Seth Hobson.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download architecture-decision-records.zip