PaperclipOrg
Claude Agent Skill · by Wshobson

Architecture Decision Records

Creates proper Architecture Decision Records using proven templates like MADR, Y-statements, and RFC formats. Generates the full ADR structure with context, dec

Install
Terminal · npx
$npx skills add https://github.com/wshobson/agents --skill architecture-decision-records
Works with Paperclip

How Architecture Decision Records fits into a Paperclip company.

Architecture Decision Records drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md441 lines
Expand
---name: architecture-decision-recordsdescription: 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.--- # Architecture Decision Records Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions. ## When to Use This Skill - Making significant architectural decisions- Documenting technology choices- Recording design trade-offs- Onboarding new team members- Reviewing historical decisions- Establishing decision-making processes ## Core Concepts ### 1. What is an ADR? An Architecture Decision Record captures: - **Context**: Why we needed to make a decision- **Decision**: What we decided- **Consequences**: What happens as a result ### 2. When to Write an ADR | 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  | ### 3. ADR Lifecycle ```Proposed → Accepted → Deprecated → Superseded              ↓           Rejected``` ## Templates ### Template 1: Standard ADR (MADR Format) ```markdown# ADR-0001: Use PostgreSQL as Primary Database ## Status Accepted ## Context We need to select a primary database for our new e-commerce platform. The systemwill handle: - ~10,000 concurrent users- Complex product catalog with hierarchical categories- Transaction processing for orders and payments- Full-text search for products- Geospatial queries for store locator The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACIDcompliance for financial transactions. ## Decision Drivers - **Must have ACID compliance** for payment processing- **Must support complex queries** for reporting- **Should support full-text search** to reduce infrastructure complexity- **Should have good JSON support** for flexible product attributes- **Team familiarity** reduces onboarding time ## Considered Options ### Option 1: PostgreSQL - **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text  search, PostGIS for geospatial, team has experience- **Cons**: Slightly more complex replication setup than MySQL ### Option 2: MySQL - **Pros**: Very familiar to team, simple replication, large community- **Cons**: Weaker JSON support, no built-in full-text search (need  Elasticsearch), no geospatial without extensions ### Option 3: MongoDB - **Pros**: Flexible schema, native JSON, horizontal scaling- **Cons**: No ACID for multi-document transactions (at decision time),  team has limited experience, requires schema design discipline ## Decision We will use **PostgreSQL 15** as our primary database. ## Rationale PostgreSQL provides the best balance of: 1. **ACID compliance** essential for e-commerce transactions2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce   infrastructure complexity3. **Team familiarity** with SQL databases reduces learning curve4. **Mature ecosystem** with excellent tooling and community support The slight complexity in replication is outweighed by the reduction inadditional services (no separate Elasticsearch needed). ## Consequences ### Positive - Single database handles transactions, search, and geospatial queries- Reduced operational complexity (fewer services to manage)- Strong consistency guarantees for financial data- Team can leverage existing SQL expertise ### Negative - Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)- Vertical scaling limits may require read replicas sooner- Some team members need PostgreSQL-specific training ### Risks - Full-text search may not scale as well as dedicated search engines- Mitigation: Design for potential Elasticsearch addition if needed ## Implementation Notes - Use JSONB for flexible product attributes- Implement connection pooling with PgBouncer- Set up streaming replication for read replicas- Use pg_trgm extension for fuzzy search ## Related Decisions - ADR-0002: Caching Strategy (Redis) - complements database choice- ADR-0005: Search Architecture - may supersede if Elasticsearch needed ## References - [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md```` ### Template 2: Lightweight ADR ```markdown# ADR-0012: Adopt TypeScript for Frontend Development **Status**: Accepted**Date**: 2024-01-15**Deciders**: @alice, @bob, @charlie ## Context Our React codebase has grown to 50+ components with increasing bug reportsrelated to prop type mismatches and undefined errors. PropTypes provideruntime-only checking. ## Decision Adopt TypeScript for all new frontend code. Migrate existing code incrementally. ## Consequences **Good**: Catch type errors at compile time, better IDE support, self-documentingcode. **Bad**: Learning curve for team, initial slowdown, build complexity increase. **Mitigations**: TypeScript training sessions, allow gradual adoption with`allowJs: true`.``` ### Template 3: Y-Statement Format ```markdown# ADR-0015: API Gateway Selection In the context of **building a microservices architecture**,facing **the need for centralized API management, authentication, and rate limiting**,we decided for **Kong Gateway**and against **AWS API Gateway and custom Nginx solution**,to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,accepting that **we need to manage Kong infrastructure ourselves**.``` ### Template 4: ADR for Deprecation ```markdown# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL ## Status Accepted (Supersedes ADR-0003) ## Context ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibilityneeds. Since then: - MongoDB's multi-document transactions remain problematic for our use case- Our schema has stabilized and rarely changes- We now have PostgreSQL expertise from other services- Maintaining two databases increases operational burden ## Decision Deprecate MongoDB and migrate user profiles to PostgreSQL. ## Migration Plan 1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor4. **Phase 4** (Week 6): Remove MongoDB writes, decommission ## Consequences ### Positive - Single database technology reduces operational complexity- ACID transactions for user data- Team can focus PostgreSQL expertise ### Negative - Migration effort (~4 weeks)- Risk of data issues during migration- Lose some schema flexibility ## Lessons Learned Document from ADR-0003 experience: - Schema flexibility benefits were overestimated- Operational cost of multiple databases was underestimated- Consider long-term maintenance in technology decisions``` ### Template 5: Request for Comments (RFC) Style ```markdown# RFC-0025: Adopt Event Sourcing for Order Management ## Summary Propose adopting event sourcing pattern for the order management domain toimprove auditability, enable temporal queries, and support business analytics. ## Motivation Current challenges: 1. Audit requirements need complete order history2. "What was the order state at time X?" queries are impossible3. Analytics team needs event stream for real-time dashboards4. Order state reconstruction for customer support is manual ## Detailed Design ### Event Store``` OrderCreated { orderId, customerId, items[], timestamp }OrderItemAdded { orderId, item, timestamp }OrderItemRemoved { orderId, itemId, timestamp }PaymentReceived { orderId, amount, paymentId, timestamp }OrderShipped { orderId, trackingNumber, timestamp } ``` ### Projections - **CurrentOrderState**: Materialized view for queries- **OrderHistory**: Complete timeline for audit- **DailyOrderMetrics**: Analytics aggregation ### Technology - Event Store: EventStoreDB (purpose-built, handles projections)- Alternative considered: Kafka + custom projection service ## Drawbacks - Learning curve for team- Increased complexity vs. CRUD- Need to design events carefully (immutable once stored)- Storage growth (events never deleted) ## Alternatives 1. **Audit tables**: Simpler but doesn't enable temporal queries2. **CDC from existing DB**: Complex, doesn't change data model3. **Hybrid**: Event source only for order state changes ## Unresolved Questions - [ ] Event schema versioning strategy- [ ] Retention policy for events- [ ] Snapshot frequency for performance ## Implementation Plan 1. Prototype with single order type (2 weeks)2. Team training on event sourcing (1 week)3. Full implementation and migration (4 weeks)4. Monitoring and optimization (ongoing) ## References - [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)- [EventStoreDB Documentation](https://www.eventstore.com/docs)``` ## ADR Management ### Directory Structure ```docs/├── adr/│   ├── README.md           # Index and guidelines│   ├── template.md         # Team's ADR template│   ├── 0001-use-postgresql.md│   ├── 0002-caching-strategy.md│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]│   └── 0020-deprecate-mongodb.md      # Supersedes 0003``` ### ADR Index (README.md) ```markdown# Architecture Decision Records This directory contains Architecture Decision Records (ADRs) for [Project Name]. ## Index | ADR                                   | Title                              | Status     | Date       || ------------------------------------- | ---------------------------------- | ---------- | ---------- || [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 || [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 || [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 || [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 | ## Creating a New ADR 1. Copy `template.md` to `NNNN-title-with-dashes.md`2. Fill in the template3. Submit PR for review4. Update this index after approval ## ADR Status - **Proposed**: Under discussion- **Accepted**: Decision made, implementing- **Deprecated**: No longer relevant- **Superseded**: Replaced by another ADR- **Rejected**: Considered but not adopted``` ### Automation (adr-tools) ```bash# Install adr-toolsbrew install adr-tools # Initialize ADR directoryadr init docs/adr # Create new ADRadr new "Use PostgreSQL as Primary Database" # Supersede an ADRadr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL" # Generate table of contentsadr generate toc > docs/adr/README.md # Link related ADRsadr link 2 "Complements" 1 "Is complemented by"``` ## Review Process ```markdown## ADR Review Checklist ### Before Submission - [ ] Context clearly explains the problem- [ ] All viable options considered- [ ] Pros/cons balanced and honest- [ ] Consequences (positive and negative) documented- [ ] Related ADRs linked ### During Review - [ ] At least 2 senior engineers reviewed- [ ] Affected teams consulted- [ ] Security implications considered- [ ] Cost implications documented- [ ] Reversibility assessed ### After Acceptance - [ ] ADR index updated- [ ] Team notified- [ ] Implementation tickets created- [ ] Related documentation updated``` ## Best Practices ### Do's - **Write ADRs early** - Before implementation starts- **Keep them short** - 1-2 pages maximum- **Be honest about trade-offs** - Include real cons- **Link related decisions** - Build decision graph- **Update status** - Deprecate when superseded ### Don'ts - **Don't change accepted ADRs** - Write new ones to supersede- **Don't skip context** - Future readers need background- **Don't hide failures** - Rejected decisions are valuable- **Don't be vague** - Specific decisions, specific consequences- **Don't forget implementation** - ADR without action is waste