architecture-decision-records
Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is.
Best for Development teams needing d…Works with GitHubLow risk
⌘source
- author
@affaan-m- language
- JavaScript
★159kstars
25kforks
Apr 17, 2026
✦overview.md
Key Features
- ·Auto-detects decision moments during coding sessions
- ·Records context, alternatives, and rationale in structured format
- ·Maintains an ADR log alongside the codebase
- ·Uses lightweight ADR format adapted for AI-assisted development
Use Cases
- →Capturing framework, library, or pattern choices during development
- →Documenting database or API design decisions as they are made
- →Answering 'why did we choose X?' by reading existing ADRs
- →Recording architectural trade-offs discussed during planning phases
Best for
- ✓Development teams needing decision traceability
- ✓Projects with evolving architecture
name
architecture-decision-records
description
Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is.
origin:ECC
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?
$install
1-click copynpx skills add affaan-m/everything-claude-code --skill architecture-decision-recordsSafety assessment
★
Clarity score
How clear and easy to understand the SKILL.md instructions are, rated from 1 to 5.
4/ 5
very goodClear and well structured, with only minor parts that might need a second read.
◎
Actionability score
How directly an agent can act on the SKILL.md instructions, rated from 1 to 5.
3/ 5
mediumPartially actionable with several concrete steps, but still missing important details.