write-adr
Document architectural decisions with context and consequences.
When & Why to Use This Skill
This Claude skill streamlines the creation of Architectural Decision Records (ADRs), helping engineering teams document the rationale, context, and consequences of critical technical choices. By standardizing the documentation of software architecture, it ensures long-term project maintainability, improves team alignment, and preserves institutional knowledge regarding system design.
Use Cases
- Onboarding new developers: Providing a clear historical record of why specific technologies or patterns were chosen to help new hires understand the codebase faster.
- Technical Debt Management: Tracking the trade-offs made during development to better plan for future refactoring or system evolution.
- Design Reviews and Audits: Creating a structured audit trail of architectural changes for compliance, governance, or internal peer reviews.
- Preventing Decision Regression: Documenting rejected alternatives to ensure the team doesn't waste time re-discussing previously dismissed solutions.
| name | write_adr |
|---|---|
| description | Document architectural decisions with context and consequences. |
| short-description | Write ADRs |
Purpose
Capture architectural decisions for audit and future work.
Steps
- Fill the ADR template in
DECISIONS.md. - Include context, decision, alternatives, consequences.
- Link the ADR in relevant docs.