Architecture Decision Records

作者 wshobson46891e7e60da无许可证收录于 2026年10月8日更新于 2026年10月8日

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.

仅含说明Business & Finance Writing & Content

AI 生成的概览

提供撰写与维护架构决策记录（ADR）的模板和最佳实践。

功能: 该技能提供指导与可复用模板，用于把重要的技术决策记录为架构决策记录。内容涵盖 ADR 的结构（背景、决策、后果）、多种格式（如 MADR、轻量级、Y 陈述、弃用与 RFC 风格），以及生命周期状态、目录结构、索引 README、评审清单和最佳实践。产出的是书面决策文档及相关约定，而非代码或工具。
适用场景: 适用于记录重要的架构或技术选型决策、记录设计权衡，或回顾以往的架构选择。也适合团队建立决策流程，或帮助新成员了解历史背景。
运行要求: 无需脚本或特殊工具，仅为说明与模板。文中提到可选的 adr-tools 命令行工具用于自动化，但遵循这些指导无需安装任何东西。

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

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`

# 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`.

# 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**.

# 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

# 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

# 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)


### 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

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

# 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"

# 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

## 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

来源与署名

来源：wshobson/agents位于plugins/documentation-generation/skills/architecture-decision-records提交46891e7

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Architecture Decision Records

Architecture Decision Records

When to Use This Skill

Core Concepts

1. What is an ADR?

2. When to Write an ADR

3. ADR Lifecycle

Templates

Template 1: Standard ADR (MADR Format)

Template 2: Lightweight ADR

Template 3: Y-Statement Format

Template 4: ADR for Deprecation

Template 5: Request for Comments (RFC) Style

ADR Management

Directory Structure

ADR Index (README.md)

Automation (adr-tools)

Review Process

Best Practices

Do's

Don'ts

来源与署名

更多来自 wshobson/agents 的技能

Uv Package Manager

Web Component Design

Python Type Safety

Visual Design Foundations

Responsive Design

Python Resource Management

更多Business & Finance技能

Gke Cost Optimization

Google Ads Api Account Diagnostics

Cost Optimization

Cost Governance

Cost Estimation

Cost Analysis