Our review
This skill helps document significant technical decisions using structured Architecture Decision Record templates.
Strengths
- Standardized format to capture context and rationale
- Clear process with review and ADR lifecycle
- Multiple templates for different decision complexity
- Addresses common mistakes with specific guidance
Limitations
- Requires team discipline to keep ADRs updated
- May be perceived as additional overhead
- Does not cover non-technical decision documentation
Use this skill when adopting new frameworks, choosing database technologies, defining API patterns, or making any architecture-level decision.
Avoid this skill for minor version upgrades, bug fixes, routine maintenance, or implementation details without lasting impact.
Security analysis
SafeThis skill is purely documentation-oriented, providing templates and best practices for writing architecture decision records. It only requires Read access to reference files, and there are no instructions for executing commands or performing any risky operations.
No concerns found
Examples
We're deciding between PostgreSQL and MongoDB for our new user service. Help me draft an ADR covering context, options, decision, and consequences.Show me an overview of our past architecture decisions and identify any that might be outdated or superseded.I need to propose using event sourcing for order processing. Provide a lightweight ADR template with sections for context, decision drivers, options, and consequences.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.
Pivot Decision Framework
Documentation
Documents a strategic pivot or persevere decision with evidence, analysis, and rationale. Use when evaluating whether to change direction on a product, feature, or strategy based on market feedback.