Architecture Decision Records

Captures architectural decisions during Claude Code sessions and writes them as structured ADR documents in `docs/adr/`. It watches for decision moments like "let's go with X instead of Y" and prompts you to record the context, alternatives considered, and consequences. Uses the Michael Nygard ADR format with numbered files and an index. The real value is making implicit decisions explicit before they disappear into Slack history. Works best when you're comparing frameworks, choosing deployment strategies, or making database schema trade-offs. It won't auto-create files without your approval, which is the right default.

install copies · 90 days. Times the install command was copied on this site in the last 90 days, bots filtered.: 6
skills.sh installs: 4.8K
GitHub stars: 229.1K
last updated: Jul 14, 2026

View on GitHub

Install

$ npx -y skills add affaan-m/everything-claude-code --skill architecture-decision-records --agent claude-code

Installs into .claude/skills of the current project.

Files

Architecture Decision Records

Capture architectural decisions as they happen during coding sessions. Instead of decisions living only in Slack threads, PR comments, or someone's memory, this skill produces structured ADR documents that live alongside the code.

When to Activate

User explicitly says "let's record this decision" or "ADR this"
User chooses between significant alternatives (framework, library, pattern, database, API design)
User says "we decided to..." or "the reason we're doing X instead of Y is..."
User asks "why did we choose X?" (read existing ADRs)
During planning phases when architectural trade-offs are discussed

ADR Format

Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development:

# ADR-NNNN: [Decision Title]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]

## Context

What is the issue that we're seeing that is motivating this decision or change?

[2-5 sentences describing the situation, constraints, and forces at play]

## Decision

What is the change that we're proposing and/or doing?

SKILL.md on GitHub