98 lines
4.9 KiB
Markdown
98 lines
4.9 KiB
Markdown
---
|
|
name: write_adr
|
|
description: "Produce Architectural Decision Records with Context, Decision, Consequences, and Alternatives. A deliverable skill referenced by design-architecture."
|
|
---
|
|
|
|
This skill provides guidance and format requirements for producing Architectural Decision Records (ADRs) within the architecture document.
|
|
|
|
This is a deliverable skill, not a workflow skill. It is referenced by `design-architecture` when documenting significant architectural decisions.
|
|
|
|
## Purpose
|
|
|
|
The Architect must document significant architectural decisions using the ADR format. ADRs provide a permanent record of the context, decision, consequences, and alternatives considered for each important choice.
|
|
|
|
## When to Write an ADR
|
|
|
|
Write an ADR for any decision that:
|
|
- Affects the system structure or service boundaries
|
|
- Involves a technology selection (language, framework, database, queue, cache, infra)
|
|
- Involves a consistency model choice (strong vs eventual, idempotency strategy)
|
|
- Involves a security architecture decision
|
|
- Involves a significant trade-off (performance vs consistency, complexity vs simplicity)
|
|
- Would be difficult or costly to reverse
|
|
- Other engineers would question "why was this chosen?"
|
|
|
|
## ADR Format
|
|
|
|
Each ADR must follow this format:
|
|
|
|
```markdown
|
|
### ADR-{N}: {Decision Title}
|
|
|
|
- **Context**: Why this decision was needed. What is the problem or situation that requires a decision? Which PRD requirements drove this decision? What constraints exist?
|
|
|
|
- **Decision**: What was decided. State the decision clearly and specifically. Include the specific technology, pattern, or approach chosen.
|
|
|
|
- **Consequences**: What trade-offs or implications result from this decision. Include both positive and negative consequences. Address:
|
|
- What becomes easier?
|
|
- What becomes harder?
|
|
- What are the risks?
|
|
- What are the operational implications?
|
|
|
|
- **Alternatives**: What other options were considered. For each alternative:
|
|
- Brief description
|
|
- Why it was not chosen
|
|
- Under what circumstances it might be the better choice
|
|
```
|
|
|
|
## ADR Numbering
|
|
|
|
- Start with ADR-001 for the first decision
|
|
- Number sequentially (ADR-001, ADR-002, etc.)
|
|
- Each ADR in the architecture document gets a unique number
|
|
|
|
## ADR Examples
|
|
|
|
### ADR-001: Use Cassandra for Job Storage
|
|
|
|
- **Context**: The system needs to handle high write throughput (10,000+ writes/second) for job status updates. Jobs are write-once with frequent status updates. Queries are primarily by job ID and by status+created_at. The PRD requires 99.9% availability for job status writes.
|
|
|
|
- **Decision**: Use Cassandra as the primary storage for job data. Use PostgreSQL for relational data that requires complex queries and transactions.
|
|
|
|
- **Consequences**:
|
|
- (+) High write throughput for job status updates
|
|
- (+) Horizontal scalability for job storage
|
|
- (+) 99.9% availability for job writes
|
|
- (-) Eventual consistency for job reads (stale reads possible within replication window)
|
|
- (-) No complex joins for job data
|
|
- (-) Additional operational complexity of managing two database systems
|
|
- (-) Data migration if requirements change
|
|
|
|
- **Alternatives**:
|
|
- PostgreSQL only: Simpler operations, but may not handle write throughput under peak load. Would be appropriate if write throughput stays below 5,000 writes/second.
|
|
- MongoDB: Good balance of write throughput and query flexibility, but less mature for time-series-like access patterns.
|
|
- Redis + PostgreSQL: Redis for hot job data, PostgreSQL for cold storage. Adds complexity of data synchronization.
|
|
|
|
### ADR-002: Use Event-Driven Architecture for Order Processing
|
|
|
|
- **Context**: The PRD requires orders to be processed asynchronously with decoupled services. Order processing involves multiple steps (validation, payment, inventory, notification) that may fail independently. Each step must be retryable.
|
|
|
|
- **Decision**: Use event-driven architecture with the outbox pattern for order processing. Publish OrderCreated events from the Order Service, consumed by downstream services.
|
|
|
|
- **Consequences**:
|
|
- (+) Services are decoupled and can evolve independently
|
|
- (+) Individual steps can be retried without reprocessing the entire order
|
|
- (+) Natural fit for saga pattern for distributed transactions
|
|
- (-) Eventual consistency — downstream services may see stale data
|
|
- (-) More complex debugging and tracing
|
|
- (-) Requires outbox pattern implementation to ensure at-least-once delivery
|
|
|
|
- **Alternatives**:
|
|
- Synchronous orchestration: Simpler to implement and debug, but creates tight coupling and doesn't handle partial failures well. Appropriate for simple, synchronous workflows.
|
|
- Saga orchestration with a central coordinator: More control over flow, but adds a single point of failure and operational complexity.
|
|
|
|
## Embedding in Architecture Document
|
|
|
|
All ADRs must be embedded within the `## ADR` section of `docs/architecture/{feature}.md`.
|
|
|
|
Do NOT produce separate ADR files. All ADRs must be within the single architecture document. |