| name | document-decision |
| description | Create Architecture Decision Records (ADRs) documenting WHY decisions were made. Uses standard ADR format (Status/Context/Decision/Consequences). |
Document Architecture Decision
Use this skill when recording system design decisions for LikeC4-modeled architectures.
Purpose
Create Architecture Decision Records (ADRs) that explain WHY architectural choices were made in the system diagrams, not HOW the diagrams are built or maintained.
Scope
- ✅ System design decisions (e.g., why Kong API Gateway vs HAProxy, why MongoDB vs PostgreSQL)
- ✅ Container-level technology choices (e.g., why RabbitMQ for queuing, why MinIO for storage)
- ✅ Component architecture patterns (e.g., why async processing, why microservices)
- ✅ Deployment infrastructure choices (e.g., why 3-node replication, why specific VM sizing)
- ❌ NOT repository structure, tooling, CI/CD setup, or LikeC4 modeling decisions
Format
- Filename:
ADR/NNNN-decision-title.md (manually increment NNNN)
- Template: Use
ADR/0000-template.md as reference
- Sections: Status, Context, Decision, Consequences (Positive/Negative/Neutral)
Example
# ADR-0001: API Gateway Selection - Kong vs HAProxy
## Status
Accepted
## Context
Legacy system used HAProxy as a simple load balancer. Microservices architecture requires:
- API-aware routing based on paths, headers, JWT claims
- Built-in authentication (JWT validation, OAuth2)
- Rate limiting and circuit breakers
- Plugin ecosystem for extensibility
Upgrade from HAProxy to Kong API Gateway
Routes to multiple backend services with path-based rules
JWT validation out-of-the-box, reducing custom auth code
Production-grade rate limiting without custom implementation
Extensible via Lua plugins
More complex configuration than HAProxy
Requires learning Kong admin API and declarative config
Higher resource footprint (but acceptable for use case)
