Architecture Decision Records

Seth HobsonCommunityCreated by Seth Hobson

Skill
Guidelines
Software development
MIT
No issues found

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

Download the skill as a ZIP:
https://autogineer.com/agent-skills/wshobson/architecture-decision-records/download

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 ADR	Skip ADR
New framework adoption	Minor version upgrades
Database technology choice	Bug fixes
API design patterns	Implementation details
Security architecture	Routine maintenance
Integration patterns	Configuration 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

ATTRIBUTION.mdAdded by AutoGineer1.0 KiB
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md4.9 KiB
references/decision-templates.md5.0 KiB
references/deprecation-rfc-templates.md3.4 KiB

SKILL.md

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 ADR	Skip ADR
New framework adoption	Minor version upgrades
Database technology choice	Bug fixes
API design patterns	Implementation details
Security architecture	Routine maintenance
Integration patterns	Configuration 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

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

2026-11-09

AutoGineer is not affiliated with or endorsed by Seth Hobson or Seth Hobson.

Download ZIP

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

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Seth Hobson

Architecture Decision Records

When to Use This Skill

Core Concepts

1. What is an ADR?

2. When to Write an ADR

3. ADR Lifecycle

ADR Management

Directory Structure

ADR Index (README.md)

Automation (adr-tools)

Review Process

Best Practices

Do's

Don'ts

Files

SKILL.md

Architecture Decision Records

When to Use This Skill

Core Concepts

1. What is an ADR?

2. When to Write an ADR

3. ADR Lifecycle

ADR Management

Directory Structure

ADR Index (README.md)

Automation (adr-tools)

Review Process

Best Practices

Do's

Don'ts

Requirements and compatibility

Security

Attribution and licence

Related skills

Setup TS Deep Modules

To Spec

Improve Codebase Architecture

Domain Modeling

Codebase Design

Prototype

Download ZIP