Auto-generate Architecture Decision Records from your Claude Code conversations.
Quick Start · Installation · Usage · Example · Resources
Tip
When you finish working on a feature or bug fix in Claude Code, simply type /adr to capture the problem, decision, and consequences in a structured, searchable format.
auto-adr is a Claude Code skill that automatically generates Architecture Decision Records from your development conversations. Instead of manually documenting decisions after the fact, let Claude analyze your session and produce a well-structured ADR in seconds.
npx skills add tanRdev/auto-adrThen in your next Claude Code session, type /adr when you're done working. That's it!
npx skills add tanRdev/auto-adrCopy and paste this prompt into your Claude Code session:
Install the ADR skill from tanRdev/auto-adr by running: npx skills add tanRdev/auto-adr
After installation, confirm that the skill is available by checking ~/.claude/skills/adr/ exists and contains SKILL.md.
Claude will run the npx command and verify the installation.
Note
The skill requires no configuration and works out of the box. ADRs are stored in docs/decisions/ with the naming format: ADR-{YYYYMMDD}-{kebab-case-title}.md
- Work on a feature or bug fix in Claude Code as you normally would
- When done, type
/adrin your message - Claude analyzes the conversation and generates an ADR in
docs/decisions/
After implementing a feature, invoke /adr. Claude generates:
# ADR-20260125: Implement In-Memory Caching Layer for User Service
## Context
The user service was making redundant database queries for frequently accessed user profiles, causing high latency. Considered three approaches: (1) Redis-based distributed cache, (2) in-memory LRU cache with TTL, (3) database query optimization with indexing.
## Decision
Implement in-memory LRU cache with 5-minute TTL in the user service. This approach:
- Reduces database load by 60% for read operations
- Zero additional infrastructure (no Redis required)
- TTL-based invalidation prevents stale data
- Can be extended to Redis later if needed
## Files Modified
- src/services/userService.ts (added cache layer)
- src/cache/LRUCache.ts (created)
- tests/userService.test.ts (updated with cache tests)
## Consequences
**Positive:**
- Significant latency improvement for cached reads
- No operational overhead
- Simple to understand and maintain
**Negative:**
- Memory usage increases with cache size
- Possible stale data (mitigated by TTL)
- Single-instance only (not suitable for distributed systems)| Feature | Description |
|---|---|
| Claude-Powered Analysis | Leverages full conversation context instead of fragile regex parsing |
| Michael Nygard Format | Industry-standard ADR format with Context, Decision, and Consequences |
| Automatic File Tracking | Identifies all files created or modified during your session |
| Structured Output | Consistent naming and location in docs/decisions/ |
| Zero Configuration | Works immediately after installation |
The skill uses Claude's full conversation context to:
- Understand the problem you were solving
- Extract the decision made and rationale
- Identify all files created or modified
- Generate a Markdown ADR in the Michael Nygard format
Note
This approach is superior to regex-based parsing because it leverages Claude's comprehension of your work, not fragile string matching.
Architecture Decision Records create a searchable, versioned log of why decisions were made, not just what was built. They're invaluable for:
- Onboarding — Help new team members understand historical context
- Code Reviews — Justify design choices with documented reasoning
- Knowledge Retention — Capture decisions before they're forgotten
- Portfolio Building — Showcase your decision-making process
- Architecture Decision Records (ADR) — Official ADR documentation
- Documenting Architecture Decisions — Michael Nygard's original post
- Claude Code Skills — Learn more about Claude Code extensibility
- Open an Issue — Report bugs or request features
- Discussions — Ask questions and share ideas
