Architecture Decision Record

Document architectural decisions using ADR format. Use when making significant architectural choices that affect future development.

48 stars 10 forksSoftware Development Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add sethdford/claude-skills

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add sethdford/claude-skills --skill architecture-decision-record
Manual install
git clone --depth 1 https://github.com/sethdford/claude-skills.git /tmp/claude-skills
mkdir -p ~/.claude/skills
cp -r /tmp/claude-skills/architect/decision-making/skills/architecture-decision-record ~/.claude/skills/architecture-decision-record

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Architecture Decision Record

Document architectural decisions with context, rationale, and trade-offs using the ADR format for organizational memory.

## Context

You are documenting an architectural decision. Use ADRs to capture decision rationale and ensure future teams understand why choices were made.

## Domain Context

Based on Michael Nygard's ADR format and decision documentation best practices:

- **Status**: Proposed, Accepted, Superseded
- **Context**: Problem statement and constraints
- **Decision**: What was chosen and why
- **Consequences**: Benefits and drawbacks

## Instructions

1. **Describe Problem**: What decision needed to be made? What constraints?
2. **List Options**: What alternatives were considered?
3. **Explain Rationale**: Why was this option chosen? What trade-offs?
4. **Document Consequences**: What problems does this solve? What new problems does it create?
5. **Link Related Decisions**: ADRs supersede, depend on, or relate to other ADRs.

## Anti-Patterns

- **ADR Without Context**: Decision seems arbitrary. **Guard**: Every ADR explains problem and constraints.
- **Only Documenting Wins**: Never documenting failures or reversals. **Guard**: Include failures and "Superseded" records.
- **ADR Too Late**: Decision made and implemented before documenting. **Guard**: Write ADR before implementation.

## Further Reading

- _Documenting Architecture Decisions_ by Michael Nygard
- _ADR Repository_ at adr.github.io
Read the full skill on GitHub

Details

Skill name
architecture-decision-record
Path
architect/decision-making/skills/architecture-decision-record/SKILL.md
License
MIT
Repo updated
11 March 2026

FAQ

What does the Architecture Decision Record skill do?

Document architectural decisions using ADR format. Use when making significant architectural choices that affect future development.

How do I install the Architecture Decision Record skill?

Claude Code plugin: /plugin marketplace add sethdford/claude-skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Architecture Decision Record popular?

It lives in sethdford/claude-skills, which has 48 GitHub stars and 10 forks.

Related skills

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.