[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75AWFN2ES5ANB020FDVV5C2":3,"skill-same:01M75AWFN2ES5ANB020FDVV5C2":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M75AWFN2ES5ANB020FDVV5C2","architecture-decision-records",null,"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.","ruake\u002FAWARE","ruake","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F253885939?v=4","01M75AVBM7FRFTS61RZRNMZB6C","01M75AVBMYHD7500NHVANF1HKM",0,"MIT","https:\u002F\u002Fgithub.com\u002Fruake\u002FAWARE\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Farchitecture-decision-records\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: architecture-decision-records\ndescription: 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.\n---\n\n# Architecture Decision Records\n\nComprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.\n\n## When to Use This Skill\n\n- Making significant architectural decisions\n- Documenting technology choices\n- Recording design trade-offs\n- Onboarding new team members\n- Reviewing historical decisions\n- Establishing decision-making processes\n\n## Core Concepts\n\n### 1. What is an ADR?\n\nAn Architecture Decision Record captures:\n\n- **Context**: Why we needed to make a decision\n- **Decision**: What we decided\n- **Consequences**: What happens as a result\n\n### 2. When to Write an ADR\n\n| Write ADR                  | Skip ADR               |\n| -------------------------- | ---------------------- |\n| New framework adoption     | Minor version upgrades |\n| Database technology choice | Bug fixes              |\n| API design patterns        | Implementation details |\n| Security architecture      | Routine maintenance    |\n| Integration patterns       | Configuration changes  |\n\n### 3. ADR Lifecycle\n\n```\nProposed → Accepted → Deprecated → Superseded\n              ↓\n           Rejected\n```\n\n## Templates\n\n### Template 1: Standard ADR (MADR Format)\n\n```markdown\n# ADR-0001: Use PostgreSQL as Primary Database\n\n## Status\n\nAccepted\n\n## Context\n\nWe need to select a primary database for our new e-commerce platform. The system\nwill handle:\n\n- ~10,000 concurrent users\n- Complex product catalog with hierarchical categories\n- Transaction processing for orders and payments\n- Full-text search for products\n- Geospatial queries for store locator\n\nThe team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID\ncompliance for financial transactions.\n\n## Decision Drivers\n\n- **Must have ACID compliance** for payment processing\n- **Must support complex queries** for reporting\n- **Should support full-text search** to reduce infrastructure complexity\n- **Should have good JSON support** for flexible product attributes\n- **Team familiarity** reduces onboarding time\n\n## Considered Options\n\n### Option 1: PostgreSQL\n\n- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text\n  search, PostGIS for geospatial, team has experience\n- **Cons**: Slightly more complex replication setup than MySQL\n\n### Option 2: MySQL\n\n- **Pros**: Very familiar to team, simple replication, large community\n- **Cons**: Weaker JSON support, no built-in full-text search (need\n  Elasticsearch), no geospatial without extensions\n\n### Option 3: MongoDB\n\n- **Pros**: Flexible schema, native JSON, horizontal scaling\n- **Cons**: No ACID for multi-document transactions (at decision time),\n  team has limited experience, requires schema design discipline\n\n## Decision\n\nWe will use **PostgreSQL 15** as our primary database.\n\n## Rationale\n\nPostgreSQL provides the best balance of:\n\n1. **ACID compliance** essential for e-commerce transactions\n2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce\n   infrastructure complexity\n3. **Team familiarity** with SQL databases reduces learning curve\n4. **Mature ecosystem** with excellent tooling and community support\n\nThe slight complexity in replication is outweighed by the reduction in\nadditional services (no separate Elasticsearch needed).\n\n## Consequences\n\n### Positive\n\n- Single database handles transactions, search, and geospatial queries\n- Reduced operational complexity (fewer services to manage)\n- Strong consistency guarantees for financial data\n- Team can leverage existing SQL expertise\n\n### Negative\n\n- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)\n- Vertical scaling limits may require read replicas sooner\n- Some team members need PostgreSQL-specific training\n\n### Risks\n\n- Full-text search may not scale as well as dedicated search engines\n- Mitigation: Design for potential Elasticsearch addition if needed\n\n## Implementation Notes\n\n- Use JSONB for flexible product attributes\n- Implement connection pooling with PgBouncer\n- Set up streaming replication for read replicas\n- Use pg_trgm extension for fuzzy search\n\n## Related Decisions\n\n- ADR-0002: Caching Strategy (Redis) - complements database choice\n- ADR-0005: Search Architecture - may supersede if Elasticsearch needed\n\n## References\n\n- [PostgreSQL JSON Documentation](https:\u002F\u002Fwww.postgresql.org\u002Fdocs\u002Fcurrent\u002Fdatatype-json.html)\n- [PostgreSQL Full Text Search](https:\u002F\u002Fwww.postgresql.org\u002Fdocs\u002Fcurrent\u002Ftextsearch.html)\n- Internal: Performance benchmarks in `\u002Fdocs\u002Fbenchmarks\u002Fdatabase-comparison.md`\n```\n\n### Template 2: Lightweight ADR\n\n```markdown\n# ADR-0012: Adopt TypeScript for Frontend Development\n\n**Status**: Accepted\n**Date**: 2024-01-15\n**Deciders**: @alice, @bob, @charlie\n\n## Context\n\nOur React codebase has grown to 50+ components with increasing bug reports\nrelated to prop type mismatches and undefined errors. PropTypes provide\nruntime-only checking.\n\n## Decision\n\nAdopt TypeScript for all new frontend code. Migrate existing code incrementally.\n\n## Consequences\n\n**Good**: Catch type errors at compile time, better IDE support, self-documenting\ncode.\n\n**Bad**: Learning curve for team, initial slowdown, build complexity increase.\n\n**Mitigations**: TypeScript training sessions, allow gradual adoption with\n`allowJs: true`.\n```\n\n### Template 3: Y-Statement Format\n\n```markdown\n# ADR-0015: API Gateway Selection\n\nIn the context of **building a microservices architecture**,\nfacing **the need for centralized API management, authentication, and rate limiting**,\nwe decided for **Kong Gateway**\nand against **AWS API Gateway and custom Nginx solution**,\nto achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,\naccepting that **we need to manage Kong infrastructure ourselves**.\n```\n\n### Template 4: ADR for Deprecation\n\n```markdown\n# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL\n\n## Status\n\nAccepted (Supersedes ADR-0003)\n\n## Context\n\nADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility\nneeds. Since then:\n\n- MongoDB's multi-document transactions remain problematic for our use case\n- Our schema has stabilized and rarely changes\n- We now have PostgreSQL expertise from other services\n- Maintaining two databases increases operational burden\n\n## Decision\n\nDeprecate MongoDB and migrate user profiles to PostgreSQL.\n\n## Migration Plan\n\n1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled\n2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency\n3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor\n4. **Phase 4** (Week 6): Remove MongoDB writes, decommission\n\n## Consequences\n\n### Positive\n\n- Single database technology reduces operational complexity\n- ACID transactions for user data\n- Team can focus PostgreSQL expertise\n\n### Negative\n\n- Migration effort (~4 weeks)\n- Risk of data issues during migration\n- Lose some schema flexibility\n\n## Lessons Learned\n\nDocument from ADR-0003 experience:\n\n- Schema flexibility benefits were overestimated\n- Operational cost of multiple databases was underestimated\n- Consider long-term maintenance in technology decisions\n```\n\n### Template 5: Request for Comments (RFC) Style\n\n```markdown\n# RFC-0025: Adopt Event Sourcing for Order Management\n\n## Summary\n\nPropose adopting event sourcing pattern for the order management domain to\nimprove auditability, enable temporal queries, and support business analytics.\n\n## Motivation\n\nCurrent challenges:\n\n1. Audit requirements need complete order history\n2. \"What was the order state at time X?\" queries are impossible\n3. Analytics team needs event stream for real-time dashboards\n4. Order state reconstruction for customer support is manual\n\n## Detailed Design\n\n### Event Store\n```\n\nOrderCreated { orderId, customerId, items[], timestamp }\nOrderItemAdded { orderId, item, timestamp }\nOrderItemRemoved { orderId, itemId, timestamp }\nPaymentReceived { orderId, amount, paymentId, timestamp }\nOrderShipped { orderId, trackingNumber, timestamp }\n\n```\n\n### Projections\n\n- **CurrentOrderState**: Materialized view for queries\n- **OrderHistory**: Complete timeline for audit\n- **DailyOrderMetrics**: Analytics aggregation\n\n### Technology\n\n- Event Store: EventStoreDB (purpose-built, handles projections)\n- Alternative considered: Kafka + custom projection service\n\n## Drawbacks\n\n- Learning curve for team\n- Increased complexity vs. CRUD\n- Need to design events carefully (immutable once stored)\n- Storage growth (events never deleted)\n\n## Alternatives\n\n1. **Audit tables**: Simpler but doesn't enable temporal queries\n2. **CDC from existing DB**: Complex, doesn't change data model\n3. **Hybrid**: Event source only for order state changes\n\n## Unresolved Questions\n\n- [ ] Event schema versioning strategy\n- [ ] Retention policy for events\n- [ ] Snapshot frequency for performance\n\n## Implementation Plan\n\n1. Prototype with single order type (2 weeks)\n2. Team training on event sourcing (1 week)\n3. Full implementation and migration (4 weeks)\n4. Monitoring and optimization (ongoing)\n\n## References\n\n- [Event Sourcing by Martin Fowler](https:\u002F\u002Fmartinfowler.com\u002FeaaDev\u002FEventSourcing.html)\n- [EventStoreDB Documentation](https:\u002F\u002Fwww.eventstore.com\u002Fdocs)\n```\n\n## ADR Management\n\n### Directory Structure\n\n```\ndocs\u002F\n├── adr\u002F\n│   ├── README.md           # Index and guidelines\n│   ├── template.md         # Team's ADR template\n│   ├── 0001-use-postgresql.md\n│   ├── 0002-caching-strategy.md\n│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]\n│   └── 0020-deprecate-mongodb.md      # Supersedes 0003\n```\n\n### ADR Index (README.md)\n\n```markdown\n# Architecture Decision Records\n\nThis directory contains Architecture Decision Records (ADRs) for [Project Name].\n\n## Index\n\n| ADR                                   | Title                              | Status     | Date       |\n| ------------------------------------- | ---------------------------------- | ---------- | ---------- |\n| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |\n| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |\n| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |\n| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |\n\n## Creating a New ADR\n\n1. Copy `template.md` to `NNNN-title-with-dashes.md`\n2. Fill in the template\n3. Submit PR for review\n4. Update this index after approval\n\n## ADR Status\n\n- **Proposed**: Under discussion\n- **Accepted**: Decision made, implementing\n- **Deprecated**: No longer relevant\n- **Superseded**: Replaced by another ADR\n- **Rejected**: Considered but not adopted\n```\n\n### Automation (adr-tools)\n\n```bash\n# Install adr-tools\nbrew install adr-tools\n\n# Initialize ADR directory\nadr init docs\u002Fadr\n\n# Create new ADR\nadr new \"Use PostgreSQL as Primary Database\"\n\n# Supersede an ADR\nadr new -s 3 \"Deprecate MongoDB in Favor of PostgreSQL\"\n\n# Generate table of contents\nadr generate toc > docs\u002Fadr\u002FREADME.md\n\n# Link related ADRs\nadr link 2 \"Complements\" 1 \"Is complemented by\"\n```\n\n## Review Process\n\n```markdown\n## ADR Review Checklist\n\n### Before Submission\n\n- [ ] Context clearly explains the problem\n- [ ] All viable options considered\n- [ ] Pros\u002Fcons balanced and honest\n- [ ] Consequences (positive and negative) documented\n- [ ] Related ADRs linked\n\n### During Review\n\n- [ ] At least 2 senior engineers reviewed\n- [ ] Affected teams consulted\n- [ ] Security implications considered\n- [ ] Cost implications documented\n- [ ] Reversibility assessed\n\n### After Acceptance\n\n- [ ] ADR index updated\n- [ ] Team notified\n- [ ] Implementation tickets created\n- [ ] Related documentation updated\n```\n\n## Best Practices\n\n### Do's\n\n- **Write ADRs early** - Before implementation starts\n- **Keep them short** - 1-2 pages maximum\n- **Be honest about trade-offs** - Include real cons\n- **Link related decisions** - Build decision graph\n- **Update status** - Deprecate when superseded\n\n### Don'ts\n\n- **Don't change accepted ADRs** - Write new ones to supersede\n- **Don't skip context** - Future readers need background\n- **Don't hide failures** - Rejected decisions are valuable\n- **Don't be vague** - Specific decisions, specific consequences\n- **Don't forget implementation** - ADR without action is waste\n","# Architecture Decision Records\n\nComprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.\n\n## When to Use This Skill\n\n- Making significant architectural decisions\n- Documenting technology choices\n- Recording design trade-offs\n- Onboarding new team members\n- Reviewing historical decisions\n- Establishing decision-making processes\n\n## Core Concepts\n\n### 1. What is an ADR?\n\nAn Architecture Decision Record captures:\n\n- **Context**: Why we needed to make a decision\n- **Decision**: What we decided\n- **Consequences**: What happens as a result\n\n### 2. When to Write an ADR\n\n| Write ADR                  | Skip ADR               |\n| -------------------------- | ---------------------- |\n| New framework adoption     | Minor version upgrades |\n| Database technology choice | Bug fixes              |\n| API design patterns        | Implementation details |\n| Security architecture      | Routine maintenance    |\n| Integration patterns       | Configuration changes  |\n\n### 3. ADR Lifecycle\n\n```\nProposed → Accepted → Deprecated → Superseded\n              ↓\n           Rejected\n```\n\n## Templates\n\n### Template 1: Standard ADR (MADR Format)\n\n```markdown\n# ADR-0001: Use PostgreSQL as Primary Database\n\n## Status\n\nAccepted\n\n## Context\n\nWe need to select a primary database for our new e-commerce platform. The system\nwill handle:\n\n- ~10,000 concurrent users\n- Complex product catalog with hierarchical categories\n- Transaction processing for orders and payments\n- Full-text search for products\n- Geospatial queries for store locator\n\nThe team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID\ncompliance for financial transactions.\n\n## Decision Drivers\n\n- **Must have ACID compliance** for payment processing\n- **Must support complex queries** for reporting\n- **Should support full-text search** to reduce infrastructure complexity\n- **Should have good JSON support** for flexible product attributes\n- **Team familiarity** reduces onboarding time\n\n## Considered Options\n\n### Option 1: PostgreSQL\n\n- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text\n  search, PostGIS for geospatial, team has experience\n- **Cons**: Slightly more complex replication setup than MySQL\n\n### Option 2: MySQL\n\n- **Pros**: Very familiar to team, simple replication, large community\n- **Cons**: Weaker JSON support, no built-in full-text search (need\n  Elasticsearch), no geospatial without extensions\n\n### Option 3: MongoDB\n\n- **Pros**: Flexible schema, native JSON, horizontal scaling\n- **Cons**: No ACID for multi-document transactions (at decision time),\n  team has limited experience, requires schema design discipline\n\n## Decision\n\nWe will use **PostgreSQL 15** as our primary database.\n\n## Rationale\n\nPostgreSQL provides the best balance of:\n\n1. **ACID compliance** essential for e-commerce transactions\n2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce\n   infrastructure complexity\n3. **Team familiarity** with SQL databases reduces learning curve\n4. **Mature ecosystem** with excellent tooling and community support\n\nThe slight complexity in replication is outweighed by the reduction in\nadditional services (no separate Elasticsearch needed).\n\n## Consequences\n\n### Positive\n\n- Single database handles transactions, search, and geospatial queries\n- Reduced operational complexity (fewer services to manage)\n- Strong consistency guarantees for financial data\n- Team can leverage existing SQL expertise\n\n### Negative\n\n- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)\n- Vertical scaling limits may require read replicas sooner\n- Some team members need PostgreSQL-specific training\n\n### Risks\n\n- Full-text search may not scale as well as dedicated search engines\n- Mitigation: Design for potential Elasticsearch addition if needed\n\n## Implementation Notes\n\n- Use JSONB for flexible product attributes\n- Implement connection pooling with PgBouncer\n- Set up streaming replication for read replicas\n- Use pg_trgm extension for fuzzy search\n\n## Related Decisions\n\n- ADR-0002: Caching Strategy (Redis) - complements database choice\n- ADR-0005: Search Architecture - may supersede if Elasticsearch needed\n\n## References\n\n- [PostgreSQL JSON Documentation](https:\u002F\u002Fwww.postgresql.org\u002Fdocs\u002Fcurrent\u002Fdatatype-json.html)\n- [PostgreSQL Full Text Search](https:\u002F\u002Fwww.postgresql.org\u002Fdocs\u002Fcurrent\u002Ftextsearch.html)\n- Internal: Performance benchmarks in `\u002Fdocs\u002Fbenchmarks\u002Fdatabase-comparison.md`\n```\n\n### Template 2: Lightweight ADR\n\n```markdown\n# ADR-0012: Adopt TypeScript for Frontend Development\n\n**Status**: Accepted\n**Date**: 2024-01-15\n**Deciders**: @alice, @bob, @charlie\n\n## Context\n\nOur React codebase has grown to 50+ components with increasing bug reports\nrelated to prop type mismatches and undefined errors. PropTypes provide\nruntime-only checking.\n\n## Decision\n\nAdopt TypeScript for all new frontend code. Migrate existing code incrementally.\n\n## Consequences\n\n**Good**: Catch type errors at compile time, better IDE support, self-documenting\ncode.\n\n**Bad**: Learning curve for team, initial slowdown, build complexity increase.\n\n**Mitigations**: TypeScript training sessions, allow gradual adoption with\n`allowJs: true`.\n```\n\n### Template 3: Y-Statement Format\n\n```markdown\n# ADR-0015: API Gateway Selection\n\nIn the context of **building a microservices architecture**,\nfacing **the need for centralized API management, authentication, and rate limiting**,\nwe decided for **Kong Gateway**\nand against **AWS API Gateway and custom Nginx solution**,\nto achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,\naccepting that **we need to manage Kong infrastructure ourselves**.\n```\n\n### Template 4: ADR for Deprecation\n\n```markdown\n# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL\n\n## Status\n\nAccepted (Supersedes ADR-0003)\n\n## Context\n\nADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility\nneeds. Since then:\n\n- MongoDB's multi-document transactions remain problematic for our use case\n- Our schema has stabilized and rarely changes\n- We now have PostgreSQL expertise from other services\n- Maintaining two databases increases operational burden\n\n## Decision\n\nDeprecate MongoDB and migrate user profiles to PostgreSQL.\n\n## Migration Plan\n\n1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled\n2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency\n3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor\n4. **Phase 4** (Week 6): Remove MongoDB writes, decommission\n\n## Consequences\n\n### Positive\n\n- Single database technology reduces operational complexity\n- ACID transactions for user data\n- Team can focus PostgreSQL expertise\n\n### Negative\n\n- Migration effort (~4 weeks)\n- Risk of data issues during migration\n- Lose some schema flexibility\n\n## Lessons Learned\n\nDocument from ADR-0003 experience:\n\n- Schema flexibility benefits were overestimated\n- Operational cost of multiple databases was underestimated\n- Consider long-term maintenance in technology decisions\n```\n\n### Template 5: Request for Comments (RFC) Style\n\n```markdown\n# RFC-0025: Adopt Event Sourcing for Order Management\n\n## Summary\n\nPropose adopting event sourcing pattern for the order management domain to\nimprove auditability, enable temporal queries, and support business analytics.\n\n## Motivation\n\nCurrent challenges:\n\n1. Audit requirements need complete order history\n2. \"What was the order state at time X?\" queries are impossible\n3. Analytics team needs event stream for real-time dashboards\n4. Order state reconstruction for customer support is manual\n\n## Detailed Design\n\n### Event Store\n```\n\nOrderCreated { orderId, customerId, items[], timestamp }\nOrderItemAdded { orderId, item, timestamp }\nOrderItemRemoved { orderId, itemId, timestamp }\nPaymentReceived { orderId, amount, paymentId, timestamp }\nOrderShipped { orderId, trackingNumber, timestamp }\n\n```\n\n### Projections\n\n- **CurrentOrderState**: Materialized view for queries\n- **OrderHistory**: Complete timeline for audit\n- **DailyOrderMetrics**: Analytics aggregation\n\n### Technology\n\n- Event Store: EventStoreDB (purpose-built, handles projections)\n- Alternative considered: Kafka + custom projection service\n\n## Drawbacks\n\n- Learning curve for team\n- Increased complexity vs. CRUD\n- Need to design events carefully (immutable once stored)\n- Storage growth (events never deleted)\n\n## Alternatives\n\n1. **Audit tables**: Simpler but doesn't enable temporal queries\n2. **CDC from existing DB**: Complex, doesn't change data model\n3. **Hybrid**: Event source only for order state changes\n\n## Unresolved Questions\n\n- [ ] Event schema versioning strategy\n- [ ] Retention policy for events\n- [ ] Snapshot frequency for performance\n\n## Implementation Plan\n\n1. Prototype with single order type (2 weeks)\n2. Team training on event sourcing (1 week)\n3. Full implementation and migration (4 weeks)\n4. Monitoring and optimization (ongoing)\n\n## References\n\n- [Event Sourcing by Martin Fowler](https:\u002F\u002Fmartinfowler.com\u002FeaaDev\u002FEventSourcing.html)\n- [EventStoreDB Documentation](https:\u002F\u002Fwww.eventstore.com\u002Fdocs)\n```\n\n## ADR Management\n\n### Directory Structure\n\n```\ndocs\u002F\n├── adr\u002F\n│   ├── README.md           # Index and guidelines\n│   ├── template.md         # Team's ADR template\n│   ├── 0001-use-postgresql.md\n│   ├── 0002-caching-strategy.md\n│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]\n│   └── 0020-deprecate-mongodb.md      # Supersedes 0003\n```\n\n### ADR Index (README.md)\n\n```markdown\n# Architecture Decision Records\n\nThis directory contains Architecture Decision Records (ADRs) for [Project Name].\n\n## Index\n\n| ADR                                   | Title                              | Status     | Date       |\n| ------------------------------------- | ---------------------------------- | ---------- | ---------- |\n| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |\n| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |\n| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |\n| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |\n\n## Creating a New ADR\n\n1. Copy `template.md` to `NNNN-title-with-dashes.md`\n2. Fill in the template\n3. Submit PR for review\n4. Update this index after approval\n\n## ADR Status\n\n- **Proposed**: Under discussion\n- **Accepted**: Decision made, implementing\n- **Deprecated**: No longer relevant\n- **Superseded**: Replaced by another ADR\n- **Rejected**: Considered but not adopted\n```\n\n### Automation (adr-tools)\n\n```bash\n# Install adr-tools\nbrew install adr-tools\n\n# Initialize ADR directory\nadr init docs\u002Fadr\n\n# Create new ADR\nadr new \"Use PostgreSQL as Primary Database\"\n\n# Supersede an ADR\nadr new -s 3 \"Deprecate MongoDB in Favor of PostgreSQL\"\n\n# Generate table of contents\nadr generate toc > docs\u002Fadr\u002FREADME.md\n\n# Link related ADRs\nadr link 2 \"Complements\" 1 \"Is complemented by\"\n```\n\n## Review Process\n\n```markdown\n## ADR Review Checklist\n\n### Before Submission\n\n- [ ] Context clearly explains the problem\n- [ ] All viable options considered\n- [ ] Pros\u002Fcons balanced and honest\n- [ ] Consequences (positive and negative) documented\n- [ ] Related ADRs linked\n\n### During Review\n\n- [ ] At least 2 senior engineers reviewed\n- [ ] Affected teams consulted\n- [ ] Security implications considered\n- [ ] Cost implications documented\n- [ ] Reversibility assessed\n\n### After Acceptance\n\n- [ ] ADR index updated\n- [ ] Team notified\n- [ ] Implementation tickets created\n- [ ] Related documentation updated\n```\n\n## Best Practices\n\n### Do's\n\n- **Write ADRs early** - Before implementation starts\n- **Keep them short** - 1-2 pages maximum\n- **Be honest about trade-offs** - Include real cons\n- **Link related decisions** - Build decision graph\n- **Update status** - Deprecate when superseded\n\n### Don'ts\n\n- **Don't change accepted ADRs** - Write new ones to supersede\n- **Don't skip context** - Future readers need background\n- **Don't hide failures** - Rejected decisions are valuable\n- **Don't be vague** - Specific decisions, specific consequences\n- **Don't forget implementation** - ADR without action is waste\n",{"name":5,"description":7},"main","6184979e01f673905139589c194eab38198db2f7",".agents\u002Fskills\u002Farchitecture-decision-records",1,"https:\u002F\u002Fgithub.com\u002Fruake\u002FAWARE","https:\u002F\u002Fruake.github.io\u002FAWARE","https:\u002F\u002Fgithub.com\u002Fruake","2026-11-15 04:27:27",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add ruake\u002FAWARE --skill architecture-decision-records",{"tool":37,"command":38},"bunx","bunx skills add ruake\u002FAWARE --skill architecture-decision-records",{"tool":40,"command":41},"pnpm","pnpm dlx skills add ruake\u002FAWARE --skill architecture-decision-records","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fruake\u002FAWARE\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Farchitecture-decision-records\u002FSKILL.md",true,[],[46,52,59,66,73,79],{"skillNo":47,"name":48,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":18},"01M75BPBYT89TEE87CGBDX2KF5","xlsx","https:\u002F\u002Fgithub.com\u002Fruake\u002FAWARE\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fxlsx\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":18},"01M75BPA000S9MTH5MY7CZNYYQ","writing-plans","Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste.","https:\u002F\u002Fgithub.com\u002Fruake\u002FAWARE\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fwriting-plans\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M75BP80ETH9GYVRH8A7QPCSG","web-design-guidelines","Review files for compliance with Web Interface Guidelines.","https:\u002F\u002Fgithub.com\u002Fruake\u002FAWARE\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fweb-design-guidelines\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M75BP5XG8SX5Q2WWZB6QRVFT","web-component-design","Build reusable, maintainable UI components using modern frameworks with clean composition patterns and styling approache","https:\u002F\u002Fgithub.com\u002Fruake\u002FAWARE\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fweb-component-design\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":18},"01M75BP4B1FC4V81QR1VB56H1E","web-artifacts-builder","https:\u002F\u002Fgithub.com\u002Fruake\u002FAWARE\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fweb-artifacts-builder\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":18},"01M75BP1XVRW8WQ2XXAJBAYV2V","vueuse-functions","This skill is a decision-and-implementation guide for VueUse composables in Vue.js \u002F Nuxt projects. It maps requirements","https:\u002F\u002Fgithub.com\u002Fruake\u002FAWARE\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fvueuse-functions\u002FSKILL.md",[],[]]