菜单
Document architecture decisions with ADRs (Architecture Decision Records). Outputs decision context, options, trade-offs, and rationale.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/kalilurrahman/kr-claudiator-skills-original-prompts --skill architecture-decision命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| name | architecture-decision |
| description | Document architecture decisions with ADRs (Architecture Decision Records). Outputs decision context, options, trade-offs, and rationale. |
| argument-hint | ["decision type","stakeholders","constraints"] |
| allowed-tools | Read, Write, Bash |
Document architectural decisions with structured records. Not informal notes — formal ADRs with context, options, consequences, and rationale that survive team changes.
Status: Accepted
Date: 2024-01-15
Decision: PostgreSQL for primary database
Alternatives: MySQL, MongoDB
Context: Need ACID, relational data, complex queries
# ADR-001: Choose Database for User Data
**Status:** Accepted
**Date:** 2024-01-15
**Deciders:** Engineering Team, CTO
**Consulted:** Product, Data Science
## Context
We need to select a database for storing user data, orders, and analytics.
**Requirements:**
- ACID transactions (payment processing)
- Complex joins (reporting queries)
- 100k writes/day, 1M reads/day
- Budget: $500/month
**Constraints:**
- Team familiar with SQL
- Must run on AWS
- 99.9% availability SLA
## Decision
We will use **PostgreSQL** (RDS) for the primary database.
## Alternatives Considered
### Option 1: PostgreSQL (Chosen)
**Pros:**
- Strong ACID guarantees
- Excellent SQL support with complex queries
- JSON support for semi-structured data
- Mature ecosystem, good tooling
- Team expertise in SQL
**Cons:**
- Vertical scaling limits
- Slower writes than NoSQL
- More expensive than MySQL
**Estimated Cost:** $450/month (db.m5.large)
### Option 2: MySQL
**Pros:**
- Lower cost ($350/month)
- Good read performance
- Team knows SQL
**Cons:**
- Weaker transactional guarantees
- Less advanced query planner
- Limited JSON support
### Option 3: MongoDB
**Pros:**
- Horizontal scaling
- Flexible schema
- Fast writes
**Cons:**
- No ACID across documents
- Team has no NoSQL experience
- Join operations limited
- Higher cost ($600/month)
## Consequences
### Positive
- ACID transactions prevent payment inconsistencies
- Complex reporting queries are efficient
- Team productive immediately (no learning curve)
- JSON columns allow schema flexibility where needed
### Negative
- Vertical scaling limit at ~50k writes/second
- Will need read replicas if read traffic grows 10x
- More expensive than MySQL
### Neutral
- Standard SQL database, not differentiated
- Vendor lock-in to PostgreSQL dialect (minimal)
## Follow-Up Actions
- [ ] Set up RDS with Multi-AZ
- [ ] Configure automated backups (7-day retention)
- [ ] Set up read replica for analytics queries
- [ ] Document schema migration process
- [ ] Add connection pooling (PgBouncer)
## References
- PostgreSQL vs MySQL comparison: https://...
- RDS pricing calculator: https://...
- Team SQL expertise survey results
docs/adr/
├── README.md # Index of all ADRs
├── 0001-use-postgresql.md
├── 0002-rest-over-graphql.md
├── 0003-kubernetes-deployment.md
├── 0004-event-sourcing-for-orders.md
└── 0005-oauth-for-authentication.md
# Architecture Decision Records
## Active Decisions
- [ADR-001](0001-use-postgresql.md) - PostgreSQL for primary database
- [ADR-002](0002-rest-over-graphql.md) - REST API over GraphQL
- [ADR-003](0003-kubernetes-deployment.md) - Kubernetes for deployment
## Superseded Decisions
- [ADR-004](0004-mongodb-for-analytics.md) - ~~MongoDB for analytics~~ → Replaced by ADR-010
## Rejected Decisions
- [ADR-007](0007-blockchain-for-audit.md) - Blockchain for audit trail (Rejected)
Proposed → Under Review → Accepted → Superseded/Deprecated
↘ Rejected
Proposed: Decision draft, seeking feedback
Under Review: Active discussion
Accepted: Implemented, current state
Rejected: Considered but not chosen
Superseded: Replaced by newer decision (link to new ADR)
Deprecated: Still in use but planned for removal
# ADR-N: Choose [Technology]
**Context:** What problem needs solving?
**Decision:** Technology X
**Alternatives:**
- Technology Y
- Technology Z
**Trade-offs:**
- Performance vs Simplicity
- Cost vs Scalability
# ADR-N: Use [Pattern] for [Component]
**Context:** Current architecture pain points
**Decision:** Implement [pattern]
**Consequences:**
- Increased complexity in [area]
- Better scalability for [use case]
# ADR-N: Build/Buy [Solution]
**Context:** Need [capability]
**Decision:** Build in-house / Buy [vendor]
**Cost Analysis:**
- Build: $X upfront, $Y maintenance
- Buy: $Z/month, $W integration
# ADR-002: Use REST API Instead of GraphQL
**Status:** Accepted
**Date:** 2024-01-20
**Deciders:** Engineering Team
## Context
We need an API for mobile and web clients to access user data, products, and orders.
**Requirements:**
- Support iOS, Android, Web clients
- Simple CRUD operations (90% of use cases)
- Caching via CDN
- Team has no GraphQL experience
## Decision
Use **REST API** with JSON responses.
## Alternatives Considered
### Option 1: REST (Chosen)
**Pros:**
- Team knows REST well
- Simple to cache (HTTP caching)
- Mature tooling (Swagger, Postman)
- Easy to version (/v1/, /v2/)
**Cons:**
- Over-fetching (clients get extra fields)
- Multiple requests for related data
- No real-time subscriptions
### Option 2: GraphQL
**Pros:**
- Clients request exact fields needed
- Single request for nested data
- Strong typing with schema
**Cons:**
- Team learning curve (2-3 months)
- Harder to cache (POST requests)
- N+1 query problem requires DataLoader
- Security challenges (query depth, complexity)
## Consequences
### Positive
- Fast development (team productive day 1)
- CDN caching reduces server load
- Simple to understand and debug
### Negative
- Mobile apps fetch extra data (20% overhead)
- Dashboard needs 3 API calls instead of 1
- Real-time features need separate WebSocket
### Mitigations
- Add `?fields=` query param for sparse fieldsets
- Implement GraphQL in future if needs change (ADR-015)
- Use Server-Sent Events for real-time updates
# ADR-003: Start with Modular Monolith
**Status:** Accepted
**Date:** 2024-02-01
## Context
Early-stage startup, 5 engineers, unclear product-market fit.
## Decision
Build **modular monolith** with clear module boundaries, plan for future microservices split.
## Rationale
**Monolith Advantages (Now):**
- Single deployment (fast iterations)
- Easier debugging (single codebase)
- No distributed system complexity
- Faster development for small team
**Modular Design (Future-Proof):**
- Clear module boundaries (users, orders, payments)
- Independent databases per module
- API contracts between modules
- Easy to extract services later
**Microservices (Later):**
- When team > 20 engineers
- When scaling requirements diverge
- When deployment independence needed
## Success Metrics
- Deploy 10x/day (monolith)
- Extract first service within 12 months if needed
# ADR-004: Use Event Sourcing for Order Processing
**Status:** Accepted
**Date:** 2024-03-01
## Context
Order workflow has many state transitions:
Created → Paid → Confirmed → Shipped → Delivered → Returned
Need full audit trail for compliance and customer support.
## Decision
Implement **event sourcing** for orders.
## Design
**Event Store:**
orders_events
**Current State (Projection):**
orders
## Consequences
### Positive
- Complete audit trail (who did what when)
- Can replay events to rebuild state
- Time-travel queries ("what was order state on Jan 15?")
- Easy to add new projections
### Negative
- More complex than CRUD
- Event schema evolution requires care
- Two tables instead of one (events + projection)
- Team learning curve
### Trade-offs Accepted
- Complexity worth it for compliance requirements
- Event replay enables powerful analytics
- What problem are we solving?
- What are the requirements?
- What are the constraints (time, budget, team)?
- What are the non-negotiables?
Option A: [Current approach or obvious choice]
Option B: [Alternative 1]
Option C: [Alternative 2]
Dimensions to consider:
- Performance
- Cost (upfront + ongoing)
- Complexity
- Maintainability
- Team expertise
- Vendor lock-in
- Time to implement
Choose option with best trade-offs for current context.
Document why other options rejected.
## Decision
Use the best database.
Problem: No specifics, can't evaluate later
## Decision
Use PostgreSQL 15 on AWS RDS (db.m5.large) for user data.
## Decision
We chose PostgreSQL.
Problem: Can't see what was considered
## Alternatives Considered
1. PostgreSQL (chosen)
2. MySQL
3. MongoDB
[Detailed pros/cons for each]
## Decision
Use microservices.
Problem: No discussion of trade-offs
## Consequences
Positive:
- Independent deployments
Negative:
- 3x operational complexity
- Network latency between services
- Debugging harder
We accept these trade-offs because [reason].
Yes:
No:
# Create new ADR
./adr-tools new "Use PostgreSQL for primary database"
# Creates docs/adr/0001-use-postgresql-for-primary-database.md
npm install -g adr-log
adr new "Choose deployment platform"
adr list
adr generate toc
npx log4brains init
npx log4brains preview