This Claude skill streamlines the creation and management of Architecture Decision Records (ADRs) using the standardized MADR template. It helps engineering teams document critical technical choices, evaluate alternatives, and track the long-term consequences of architectural changes, ensuring a clear, searchable, and professional history of a project's technical evolution.

When should I use adr?

adr is useful in the following scenarios: • Case 1: Documenting the selection of a core technology stack (e.g., choosing a specific database or frontend framework) to provide historical context for current and future team members. • Case 2: Recording the rationale, trade-offs, and rejected alternatives during a major system refactoring or infrastructure migration to ensure transparency. • Case 3: Standardizing technical documentation across a distributed engineering team by enforcing the MADR format and maintaining an updated index in CLAUDE.md. • Case 4: Facilitating architectural audits and onboarding by providing a structured 'paper trail' of why specific design patterns and technical directions were chosen.

name	adr
description	Create Architecture Decision Records (ADRs) following the MADR template. Use this when documenting significant architectural decisions, design choices, or major technical direction changes.

Architecture Decision Record (ADR)

Instructions

When creating an ADR, follow these steps:

Get the context - Understand the problem that requires an architectural decision
Identify alternatives - Gather options that were considered
Document the decision - Record what was chosen and why
Capture consequences - Note the impacts and tradeoffs
Update CLAUDE.md - Add a reference to the new ADR in the "Current ADRs" section of CLAUDE.md with a brief summary and link

ADR Structure

Use the MADR (Markdown Architecture Decision Records) template with these sections:

Title

A concise heading like: "ADR-001: {Decision Title}" (e.g., "ADR-001: Use React for Frontend Framework")

Context and Problem Statement

Explain the situation and constraints
State the specific issue being addressed
Include relevant background information

Considered Options

List alternatives that were evaluated:

Option A: Description and key characteristics
Option B: Description and key characteristics
Option C: Description and key characteristics

Decision Outcome

Chosen option: State which option was selected
Rationale: Explain why this option was chosen
Tradeoffs: Document what was gained and sacrificed

Consequences

Positive outcomes: Benefits of the decision
Negative outcomes: Drawbacks or risks
Neutral impacts: Side effects or changes in approach

File Naming

Save ADRs in docs/adr/ with sequential numbering:

ADR-001-framework-choice.md
ADR-002-database-architecture.md
ADR-003-authentication-strategy.md

Syncing with CLAUDE.md

Every new ADR must be registered in CLAUDE.md to maintain a discoverable index of all architectural decisions. When you create an ADR:

Save the ADR file to docs/adr/ADR-NNN-title.md
Update the "Current ADRs" section in CLAUDE.md with an entry like:

- **[ADR-NNN: {Title}](docs/adr/ADR-NNN-title.md)**
  - Brief description of what was decided
  - Why this matters to the project
  - Key tradeoff or benefit

This keeps CLAUDE.md as the single source of truth for discovering what architectural decisions have been made.

Template Reference

The project uses the MADR bare minimal template located at docs/adr/TEMPLATE.md.

Example

A complete ADR typically spans 200-500 words and addresses one significant decision. When you need to create an ADR, provide me with:

The decision title
The context/problem
The alternatives considered
Your chosen option
Key reasoning and consequences

I'll help you structure it following the MADR format.

adr

When & Why to Use This Skill

Use Cases