adr
Manage Architecture Decision Records and ADR-aligned development. Use when user says "we should use", "let's go with", asks "why did we choose X?", implements a feature that may have an ADR, updates ADR status, or needs to check alignment with existing decisions.
When & Why to Use This Skill
This Claude skill streamlines the management of Architecture Decision Records (ADRs) using the MADR framework. It enables development teams to document technical choices, track the rationale behind architectural shifts, and ensure that ongoing implementation remains strictly aligned with established project standards and long-term goals.
Use Cases
- Documenting Technical Decisions: Capture the context, drivers, and trade-offs when choosing between different technologies or frameworks to ensure future clarity and accountability.
- Architectural Alignment Checks: Automatically verify if a new feature implementation or code change adheres to existing ADRs to prevent technical debt and architectural drift.
- Knowledge Transfer & Onboarding: Provide new team members with a searchable, structured history of why specific architectural paths were chosen, significantly reducing the learning curve.
- Decision Lifecycle Management: Systematically update, deprecate, or supersede old architectural decisions as the project evolves, maintaining an accurate and up-to-date record of the system's evolution.
| name | adr |
|---|---|
| description | Manage Architecture Decision Records and ADR-aligned development. Use when user says "we should use", "let's go with", asks "why did we choose X?", implements a feature that may have an ADR, updates ADR status, or needs to check alignment with existing decisions. |
INSTRUCTIONS
Manage Architecture Decision Records (ADRs) throughout their lifecycle: read existing decisions, write new ones, and ensure development aligns with documented decisions.
- Template: See
template.mdfor the MADR structure (status, context, drivers, options, consequences) - Operations: See
operations.mdfor directory discovery, naming conventions, commit integration, deprecation (_prefix), and ADR-aligned development workflow - Queries: See
queries.mdfor finding ADRs by topic, status, or relationship
Modes
Read Mode
Trigger: "why did we choose X?", "what's our approach to Y?", "is there an ADR for Z?"
- Discover ADR directory (see
operations.md) - Search for relevant ADRs by keyword/topic
- Summarize the decision and its rationale
- Note if the ADR is active, deprecated, or superseded
Write Mode
Trigger: "we should use", "let's go with", "I've decided to", trade-off discussions
- Check for existing ADRs on the topic (may need to supersede)
- Gather information through clarifying questions
- Draft ADR using
template.md - Save and commit (amend later if needed)
ADR-Aligned Development Mode
Trigger: Implementing features, making architectural changes, deviating from existing patterns
- Before implementation: Check for relevant ADRs
- During implementation: Reference ADR in commits
- On completion: Update ADR status (proposed → accepted)
- On deviation: Create superseding ADR, deprecate old one with
_prefix
Quality Checklist
Before finalizing an ADR:
- Title clearly states the decision (not the problem)
- Context explains WHY this decision is needed now
- At least 2 options were genuinely considered
- Decision drivers link to actual project constraints
- Consequences include both positive AND negative impacts
- Confirmation section describes how to validate the decision
Anti-Patterns
- Decision without options: Always document alternatives considered
- Vague consequences: Be specific about trade-offs
- Missing "why": The ADR should answer "why this, why now"
- Orphan ADRs: Link to related ADRs when relevant
- Stale ADRs: Update status when implemented or superseded
- Undocumented deviation: If you deviate from an ADR, create a new one
Reference
Based on MADR - Markdown Architectural Decision Records (Version 4.0, 2024)