Architecture Decision Records

This automatically captures architectural decisions during Claude Code sessions and writes them as structured ADRs in a docs/adr directory. It watches for decision moments like "let's go with X instead of Y" and prompts you to record the context, alternatives considered, and trade-offs. The format is Michael Nygard's lightweight ADR template, adapted for AI pair programming. It maintains an index so you can look up why a choice was made months later. The real value is making implicit decisions explicit before they disappear into Slack history. It asks for confirmation before creating files, which is the right move since it's modifying your repo structure.

skills.sh installs: 5.9K
GitHub stars: 300.3K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add affaan-m/ecc --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