Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
Add this skill
npx mdskills install sickn33/architecture-decision-recordsComprehensive ADR documentation guide with excellent templates and lifecycle management patterns
1---2name: architecture-decision-records3description: Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.4---56# Architecture Decision Records78Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.910## Use this skill when1112- Making significant architectural decisions13- Documenting technology choices14- Recording design trade-offs15- Onboarding new team members16- Reviewing historical decisions17- Establishing decision-making processes1819## Do not use this skill when2021- You only need to document small implementation details22- The change is a minor patch or routine maintenance23- There is no architectural decision to capture2425## Instructions26271. Capture the decision context, constraints, and drivers.282. Document considered options with tradeoffs.293. Record the decision, rationale, and consequences.304. Link related ADRs and update status over time.3132## Core Concepts3334### 1. What is an ADR?3536An Architecture Decision Record captures:37- **Context**: Why we needed to make a decision38- **Decision**: What we decided39- **Consequences**: What happens as a result4041### 2. When to Write an ADR4243| Write ADR | Skip ADR |44|-----------|----------|45| New framework adoption | Minor version upgrades |46| Database technology choice | Bug fixes |47| API design patterns | Implementation details |48| Security architecture | Routine maintenance |49| Integration patterns | Configuration changes |5051### 3. ADR Lifecycle5253```54Proposed → Accepted → Deprecated → Superseded55 ↓56 Rejected57```5859## Templates6061### Template 1: Standard ADR (MADR Format)6263```markdown64# ADR-0001: Use PostgreSQL as Primary Database6566## Status6768Accepted6970## Context7172We need to select a primary database for our new e-commerce platform. The system73will handle:74- ~10,000 concurrent users75- Complex product catalog with hierarchical categories76- Transaction processing for orders and payments77- Full-text search for products78- Geospatial queries for store locator7980The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID81compliance for financial transactions.8283## Decision Drivers8485* **Must have ACID compliance** for payment processing86* **Must support complex queries** for reporting87* **Should support full-text search** to reduce infrastructure complexity88* **Should have good JSON support** for flexible product attributes89* **Team familiarity** reduces onboarding time9091## Considered Options9293### Option 1: PostgreSQL94- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text95 search, PostGIS for geospatial, team has experience96- **Cons**: Slightly more complex replication setup than MySQL9798### Option 2: MySQL99- **Pros**: Very familiar to team, simple replication, large community100- **Cons**: Weaker JSON support, no built-in full-text search (need101 Elasticsearch), no geospatial without extensions102103### Option 3: MongoDB104- **Pros**: Flexible schema, native JSON, horizontal scaling105- **Cons**: No ACID for multi-document transactions (at decision time),106 team has limited experience, requires schema design discipline107108## Decision109110We will use **PostgreSQL 15** as our primary database.111112## Rationale113114PostgreSQL provides the best balance of:1151. **ACID compliance** essential for e-commerce transactions1162. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce117 infrastructure complexity1183. **Team familiarity** with SQL databases reduces learning curve1194. **Mature ecosystem** with excellent tooling and community support120121The slight complexity in replication is outweighed by the reduction in122additional services (no separate Elasticsearch needed).123124## Consequences125126### Positive127- Single database handles transactions, search, and geospatial queries128- Reduced operational complexity (fewer services to manage)129- Strong consistency guarantees for financial data130- Team can leverage existing SQL expertise131132### Negative133- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)134- Vertical scaling limits may require read replicas sooner135- Some team members need PostgreSQL-specific training136137### Risks138- Full-text search may not scale as well as dedicated search engines139- Mitigation: Design for potential Elasticsearch addition if needed140141## Implementation Notes142143- Use JSONB for flexible product attributes144- Implement connection pooling with PgBouncer145- Set up streaming replication for read replicas146- Use pg_trgm extension for fuzzy search147148## Related Decisions149150- ADR-0002: Caching Strategy (Redis) - complements database choice151- ADR-0005: Search Architecture - may supersede if Elasticsearch needed152153## References154155- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)156- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)157- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`158```159160### Template 2: Lightweight ADR161162```markdown163# ADR-0012: Adopt TypeScript for Frontend Development164165**Status**: Accepted166**Date**: 2024-01-15167**Deciders**: @alice, @bob, @charlie168169## Context170171Our React codebase has grown to 50+ components with increasing bug reports172related to prop type mismatches and undefined errors. PropTypes provide173runtime-only checking.174175## Decision176177Adopt TypeScript for all new frontend code. Migrate existing code incrementally.178179## Consequences180181**Good**: Catch type errors at compile time, better IDE support, self-documenting182code.183184**Bad**: Learning curve for team, initial slowdown, build complexity increase.185186**Mitigations**: TypeScript training sessions, allow gradual adoption with187`allowJs: true`.188```189190### Template 3: Y-Statement Format191192```markdown193# ADR-0015: API Gateway Selection194195In the context of **building a microservices architecture**,196facing **the need for centralized API management, authentication, and rate limiting**,197we decided for **Kong Gateway**198and against **AWS API Gateway and custom Nginx solution**,199to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,200accepting that **we need to manage Kong infrastructure ourselves**.201```202203### Template 4: ADR for Deprecation204205```markdown206# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL207208## Status209210Accepted (Supersedes ADR-0003)211212## Context213214ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility215needs. Since then:216- MongoDB's multi-document transactions remain problematic for our use case217- Our schema has stabilized and rarely changes218- We now have PostgreSQL expertise from other services219- Maintaining two databases increases operational burden220221## Decision222223Deprecate MongoDB and migrate user profiles to PostgreSQL.224225## Migration Plan2262271. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled2282. **Phase 2** (Week 3-4): Backfill historical data, validate consistency2293. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor2304. **Phase 4** (Week 6): Remove MongoDB writes, decommission231232## Consequences233234### Positive235- Single database technology reduces operational complexity236- ACID transactions for user data237- Team can focus PostgreSQL expertise238239### Negative240- Migration effort (~4 weeks)241- Risk of data issues during migration242- Lose some schema flexibility243244## Lessons Learned245246Document from ADR-0003 experience:247- Schema flexibility benefits were overestimated248- Operational cost of multiple databases was underestimated249- Consider long-term maintenance in technology decisions250```251252### Template 5: Request for Comments (RFC) Style253254```markdown255# RFC-0025: Adopt Event Sourcing for Order Management256257## Summary258259Propose adopting event sourcing pattern for the order management domain to260improve auditability, enable temporal queries, and support business analytics.261262## Motivation263264Current challenges:2651. Audit requirements need complete order history2662. "What was the order state at time X?" queries are impossible2673. Analytics team needs event stream for real-time dashboards2684. Order state reconstruction for customer support is manual269270## Detailed Design271272### Event Store273274```275OrderCreated { orderId, customerId, items[], timestamp }276OrderItemAdded { orderId, item, timestamp }277OrderItemRemoved { orderId, itemId, timestamp }278PaymentReceived { orderId, amount, paymentId, timestamp }279OrderShipped { orderId, trackingNumber, timestamp }280```281282### Projections283284- **CurrentOrderState**: Materialized view for queries285- **OrderHistory**: Complete timeline for audit286- **DailyOrderMetrics**: Analytics aggregation287288### Technology289290- Event Store: EventStoreDB (purpose-built, handles projections)291- Alternative considered: Kafka + custom projection service292293## Drawbacks294295- Learning curve for team296- Increased complexity vs. CRUD297- Need to design events carefully (immutable once stored)298- Storage growth (events never deleted)299300## Alternatives3013021. **Audit tables**: Simpler but doesn't enable temporal queries3032. **CDC from existing DB**: Complex, doesn't change data model3043. **Hybrid**: Event source only for order state changes305306## Unresolved Questions307308- [ ] Event schema versioning strategy309- [ ] Retention policy for events310- [ ] Snapshot frequency for performance311312## Implementation Plan3133141. Prototype with single order type (2 weeks)3152. Team training on event sourcing (1 week)3163. Full implementation and migration (4 weeks)3174. Monitoring and optimization (ongoing)318319## References320321- [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)322- [EventStoreDB Documentation](https://www.eventstore.com/docs)323```324325## ADR Management326327### Directory Structure328329```330docs/331├── adr/332│ ├── README.md # Index and guidelines333│ ├── template.md # Team's ADR template334│ ├── 0001-use-postgresql.md335│ ├── 0002-caching-strategy.md336│ ├── 0003-mongodb-user-profiles.md # [DEPRECATED]337│ └── 0020-deprecate-mongodb.md # Supersedes 0003338```339340### ADR Index (README.md)341342```markdown343# Architecture Decision Records344345This directory contains Architecture Decision Records (ADRs) for [Project Name].346347## Index348349| ADR | Title | Status | Date |350|-----|-------|--------|------|351| [0001](0001-use-postgresql.md) | Use PostgreSQL as Primary Database | Accepted | 2024-01-10 |352| [0002](0002-caching-strategy.md) | Caching Strategy with Redis | Accepted | 2024-01-12 |353| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles | Deprecated | 2023-06-15 |354| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 |355356## Creating a New ADR3573581. Copy `template.md` to `NNNN-title-with-dashes.md`3592. Fill in the template3603. Submit PR for review3614. Update this index after approval362363## ADR Status364365- **Proposed**: Under discussion366- **Accepted**: Decision made, implementing367- **Deprecated**: No longer relevant368- **Superseded**: Replaced by another ADR369- **Rejected**: Considered but not adopted370```371372### Automation (adr-tools)373374```bash375# Install adr-tools376brew install adr-tools377378# Initialize ADR directory379adr init docs/adr380381# Create new ADR382adr new "Use PostgreSQL as Primary Database"383384# Supersede an ADR385adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"386387# Generate table of contents388adr generate toc > docs/adr/README.md389390# Link related ADRs391adr link 2 "Complements" 1 "Is complemented by"392```393394## Review Process395396```markdown397## ADR Review Checklist398399### Before Submission400- [ ] Context clearly explains the problem401- [ ] All viable options considered402- [ ] Pros/cons balanced and honest403- [ ] Consequences (positive and negative) documented404- [ ] Related ADRs linked405406### During Review407- [ ] At least 2 senior engineers reviewed408- [ ] Affected teams consulted409- [ ] Security implications considered410- [ ] Cost implications documented411- [ ] Reversibility assessed412413### After Acceptance414- [ ] ADR index updated415- [ ] Team notified416- [ ] Implementation tickets created417- [ ] Related documentation updated418```419420## Best Practices421422### Do's423- **Write ADRs early** - Before implementation starts424- **Keep them short** - 1-2 pages maximum425- **Be honest about trade-offs** - Include real cons426- **Link related decisions** - Build decision graph427- **Update status** - Deprecate when superseded428429### Don'ts430- **Don't change accepted ADRs** - Write new ones to supersede431- **Don't skip context** - Future readers need background432- **Don't hide failures** - Rejected decisions are valuable433- **Don't be vague** - Specific decisions, specific consequences434- **Don't forget implementation** - ADR without action is waste435436## Resources437438- [Documenting Architecture Decisions (Michael Nygard)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)439- [MADR Template](https://adr.github.io/madr/)440- [ADR GitHub Organization](https://adr.github.io/)441- [adr-tools](https://github.com/npryce/adr-tools)442
Full transparency — inspect the skill content before installing.