Architecture Decision Records (ADR) documentation practice. Use when documenting architectural decisions, recording technical trade-offs, creating decision logs, or establishing architectural patterns. Trigger keywords - "ADR", "architecture decision", "decision record", "trade-offs", "architectural decision", "decision log".
View on GitHubFebruary 5, 2026
Select agents to install to:
npx add-skill https://github.com/MadAppGang/claude-code/blob/main/plugins/dev/skills/adr-documentation/SKILL.md -a claude-code --skill adr-documentationInstallation paths:
.claude/skills/adr-documentation/# ADR Documentation ## Overview ### What are ADRs? Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions along with their context and consequences. They serve as a historical record of why certain choices were made, helping teams avoid revisiting settled debates and providing context for future developers. **Key characteristics:** - **Immutable**: Once accepted, ADRs are rarely modified (supersede instead) - **Context-rich**: Capture the environment and constraints at decision time - **Outcome-focused**: Document what was decided and why - **Alternative-aware**: Show what options were considered and rejected ### Why Document Decisions? **Context Preservation:** - Future team members understand *why* things are the way they are - Avoid "we've always done it this way" without knowing the reason - Preserve institutional knowledge across team changes **Onboarding:** - New developers can read ADR history to understand system evolution - Reduces repetitive explanations of architectural choices - Provides learning path through project decisions **Avoiding Repeat Mistakes:** - Document why certain approaches were rejected - Prevent re-proposing failed solutions - Learn from past trade-offs **Alignment:** - Create shared understanding across team - Resolve disagreements with documented rationale - Enable asynchronous decision-making ### When to Write an ADR Write an ADR when: - **Significant architectural choices**: Microservices vs monolith, event-driven vs request/response - **Technology selections**: Database choice, framework adoption, language decisions - **Pattern decisions**: State management approach, authentication strategy, error handling patterns - **Breaking changes**: API redesigns, data model changes, migration strategies - **Performance-critical decisions**: Caching strategies, optimization approaches, scalability patterns - **Security-related choices**: Authentication methods, encryption strat