Use when documenting significant technical or architectural decisions that need context, rationale, and consequences recorded. Invoke when choosing between technology options, making infrastructure decisions, establishing standards, migrating systems, or when team needs to understand why a decision was made. Use when user mentions ADR, architecture decision, technical decision record, or decision documentation.
View on GitHubskills/adr-architecture/SKILL.md
January 24, 2026
Select agents to install to:
npx add-skill https://github.com/lyndonkl/claude/blob/main/skills/adr-architecture/SKILL.md -a claude-code --skill adr-architectureInstallation paths:
.claude/skills/adr-architecture/# Architecture Decision Records (ADR) ## Table of Contents - [Purpose](#purpose) - [When to Use This Skill](#when-to-use-this-skill) - [What is an ADR?](#what-is-an-adr) - [Workflow](#workflow) - [1. Understand the Decision](#1--understand-the-decision) - [2. Choose ADR Template](#2--choose-adr-template) - [3. Document the Decision](#3--document-the-decision) - [4. Validate Quality](#4--validate-quality) - [5. Deliver and File](#5--deliver-and-file) - [Common Patterns](#common-patterns) - [Guardrails](#guardrails) - [Quick Reference](#quick-reference) ## Purpose Document significant architectural and technical decisions with full context, alternatives considered, trade-offs analyzed, and consequences understood. ADRs create a decision trail that helps teams understand "why" decisions were made, even years later. ## When to Use This Skill - Recording architecture decisions (microservices, databases, frameworks) - Documenting infrastructure choices (cloud providers, deployment strategies) - Capturing technology selections (libraries, tools, platforms) - Logging process decisions (branching strategy, deployment process) - Establishing technical standards or conventions - Migrating or sunsetting systems - Making security or compliance choices - Resolving technical debates with documented rationale - Onboarding new team members who need decision history **Trigger phrases:** "ADR", "architecture decision", "document this decision", "why did we choose", "decision record", "technical decision log" ## What is an ADR? An Architecture Decision Record is a document capturing a single significant decision. It includes: - **Context**: What situation necessitates this decision? - **Decision**: What are we choosing to do? - **Alternatives**: What other options did we consider? - **Consequences**: What are the trade-offs and implications? - **Status**: Proposed, accepted, deprecated, superseded? **Quick Example:** ```markdown # ADR-042: Use PostgreSQL for Prima