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技能

Tax Prep

Plan Payroll

Job Post Builder

Contract Review

Close Month

Business Pulse