Our review
This skill helps document significant technical decisions using structured ADR templates and best practices.
Strengths
- Provides ready-to-use templates for different decision complexities
- Enforces a review and approval process with senior engineers
- Captures context, alternatives, and consequences before implementation
- Enables long-term traceability and knowledge sharing
Limitations
- Requires discipline to write ADRs before implementing
- Can be time-consuming for small or reversible decisions
- Does not cover non-technical or operational decisions
When making important architectural or technical choices that need documented rationale, team alignment, and future reference.
For routine maintenance, minor version upgrades, or implementation details that don't affect the system's architecture or design.
Security analysis
SafeThe skill is a documentation guideline with no executable code or system-altering instructions. It uses only the Read tool to access reference files, posing no execution risk.
No concerns found
Examples
Create an Architecture Decision Record for choosing PostgreSQL as our primary database. Include context about our need for ACID compliance and JSON support, list 2 alternatives (MySQL and MongoDB), and document the consequences.Review our existing ADRs in the docs/adr/ directory and provide a summary of the key architectural decisions made, highlighting any that are now deprecated or superseded.Draft an ADR template for our team that includes sections for context, decision drivers, options considered, decision, consequences, and mitigations. Use the MADR format.name: architecture-decision-records description: This skill should be used when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes. It provides ADR templates and best practices. allowed-tools: Read
Architecture Decision Records
Capture the context and rationale behind significant technical decisions using structured ADR formats.
When to Use This Skill
| Write ADR | Skip ADR | | -------------------------- | ---------------------- | | New framework adoption | Minor version upgrades | | Database technology choice | Bug fixes | | API design patterns | Implementation details | | Security architecture | Routine maintenance | | Integration patterns | Configuration changes |
Quick Start
- Copy the template:
cp docs/adr/template.md docs/adr/NNNN-your-title.md - Fill in: Context, Decision Drivers, Options, Decision, Consequences
- PR for review (2+ senior engineers)
- Update
docs/adr/README.mdindex after merge
Core Concepts
An Architecture Decision Record captures:
- Context: Why we needed to make a decision
- Decision: What we decided
- Consequences: What happens as a result
ADR Lifecycle
Proposed --> Accepted --> Deprecated --> Superseded
|
Rejected
Read reference/adr-lifecycle.md for status transitions, deprecation patterns, and review checklists.
Process
1. Choose a Template
Pick the format that fits the decision's complexity:
| Decision Complexity | Template | |---------------------|----------| | Simple tech selection | Y-Statement (one paragraph) | | Medium decision | Lightweight ADR (0.5-1 page) | | Significant architecture change | Standard MADR (1-2 pages) | | Retiring a decision | Deprecation ADR | | Major cross-team proposal | RFC Style (2-4 pages) |
Read reference/adr-templates.md for all template formats ready to copy-paste.
2. Write the ADR
- Start with context -- explain the problem before the solution
- List 2-3 real alternatives with honest pros/cons
- State the decision clearly
- Document both positive and negative consequences with specifics
3. Review and Approve
- Submit as PR with 2+ senior engineer reviewers
- Consult affected teams
- Assess security, cost, and reversibility implications
4. Maintain
- Update ADR index after acceptance
- Create implementation tickets
- Never edit accepted ADRs -- write new ones to supersede
Read reference/adr-examples.md for complete worked examples (PostgreSQL selection, TypeScript adoption, MongoDB deprecation, event sourcing RFC).
Minimal Template (Copy-Paste Starter)
# ADR-NNNN: [Title]
## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
## Context
[Why do we need to decide this? What's the problem?]
## Decision
We will [decision].
## Consequences
- **Good**: [benefits]
- **Bad**: [drawbacks]
- **Mitigations**: [how we'll address the bad]
Common Mistakes
| Mistake | Fix | |---------|-----| | Writing ADR after implementation | Write during design phase | | Listing only one option | Always include 2-3 real alternatives | | Vague consequences | Be specific: "Adds ~200ms latency to checkout" | | Editing accepted ADRs | Write new ADR that supersedes | | No decision drivers | List explicit criteria with priorities | | Missing rejected ADRs | Document rejected options too |
Directory Structure
docs/adr/
README.md # Index of all ADRs
template.md # Team's ADR template
0001-use-postgresql.md
0002-caching-strategy.md
Reference Files
| File | Contents |
|------|----------|
| reference/adr-templates.md | All formats: MADR, lightweight, Y-statement, deprecation, RFC |
| reference/adr-examples.md | Complete worked examples for each format |
| reference/adr-lifecycle.md | Status transitions, review checklists, automation with adr-tools |
Resources
Error Handling
Conflicting ADRs: When a new decision contradicts an existing ADR, create a superseding ADR that explicitly references and deprecates the old one.
Missing context: If the decision rationale is unclear or incomplete, flag it and request clarification before recording.
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Documentation Maintenance
Documentation
This skill provides a structured workflow for updating project documentation including CLAUDE.md, README, and CHANGELOG. It walks through phases like inventorying existing docs, analyzing git history for needed changes, optimizing for AI readability, and ensuring cross-document consistency. Use it when synchronizing documentation with code changes or improving documentation effectiveness for AI coding agents.