architecture-decision-guide
Guides software architecture work from requirements to a documented decision: separates functional from non-functional requirements and makes the latter measurable, records constraints, proposes two o
SKILL.mdskills/architecture-decision-guide/SKILL.md
GitHubArchitecture Decision Guide
You lead the user from raw requirements to an architecture decision that is written down and defensible. Along the way you analyze trade-offs, estimate capacity, and capture each decision that would be expensive to reverse in an Architecture Decision Record (ADR).
Context to gather
Pull from whatever tools and sources are connected:
| Source | What to take from it |
|---|---|
| Uploaded documents or connected knowledge sources | Current architecture write-ups, previous ADRs, infra diagrams, inventories of the systems already running |
| Project tracker (Jira, Linear) | Epics, requirement tickets, technical spikes |
| Document output (DOCX, Notion, Confluence) | The place finished ADRs and design documents get exported to |
With nothing connected, ask the user to share this context directly. If they want something to circulate, mention that asking for DOCX output gets them a polished Word file they can hand around.
Method: six phases in order
Run the phases one after another. Don't propose any architectural options until Phases 1 and 2 (requirements and constraints) are finished; a design drawn up without knowing its constraints tends to be one nobody can build.
Phase 1: Pin down the requirements
Split what the system must do (functional requirements) from how well it must do it (non-functional requirements). Both shape the architecture, but the non-functional side usually has more influence on the big choices.
For the functional side, work through four steps:
- Enumerate the core use cases, and for each one name the actor, the action, and the outcome they expect.
- Identify the data entities and how they relate, and for each one note whether the system creates, reads, updates, or deletes it.
- List every integration point: the external systems involved, along with each one's API, data format, and reliability profile.
- Draw the system boundary: what belongs to the system you are designing, and what is an external dependency.
For the non-functional side, probe each quality attribute below. They won't all matter equally, so the user has to rank them.
- Availability: target uptime; what downtime costs per minute or per hour; which components are critical and which can degrade.
- Scalability: expected load (users, requests/sec, data volume) at launch, after 1 year, and after 3 years; whether growth is linear or bursty.
- Latency: response time targets at p50, p95, and p99; which operations are sensitive to latency.
- Durability: how much data loss is tolerable, from zero (financial data) to a small window (analytics).
- Consistency: whether strong consistency is needed (bank transfers) or eventual consistency will do (social feeds).
- Security: data classification levels; which standards bind you (SOC 2, GDPR, HIPAA, PCI-DSS); likely threat actors.
- Operability: how much operational load the team can carry; round-the-clock on-call or business hours only; how mature their observability is.
- Cost: the budget; whether CapEx or OpEx is preferred; how cost optimization ranks against the other attributes.
Exit gate: you have a ranked list of non-functional requirements, each with a measurable target. "It should be fast" doesn't count. "API latency at p95 below 200ms with 10,000 concurrent users" does.
Phase 2: Record the constraints
Constraints are boundaries nobody can negotiate away, and they knock out options before you ever evaluate them. Check five categories:
- Technical: e.g. the system has to integrate with an existing Oracle database, the team knows only Python, or everything must run on-premises
- Organizational: e.g. launch within 3 months, no new engineers can be hired, only vendors from the approved list
- Regulatory: e.g. data has to stay in the EU, PCI-DSS compliance, audit logs kept for 7 years
- Financial: e.g. an infrastructure budget of $X/month, no new license costs, a mandate to cut current hosting spend
- Existing commitments: e.g. a contract already signed with cloud provider X, an SLA already in place with upstream service Y
Write every constraint down. Any that stay unspoken will reappear mid-implementation as blockers.
Phase 3: Lay out distinct options
Produce at least two options, and preferably three, that genuinely differ. A design document with only one option justifies a choice; it doesn't make one.
Describe each option through five lenses:
- Architecture style: for example monolith, modular monolith, microservices, serverless, event-driven, CQRS, or another style.
- Component diagram: the major building blocks, what each is responsible for, and how they talk to each other (sync or async, which protocols, which data formats).
- Data layer: where data is stored, which storage technologies hold it, and how it flows.
- Deployment model: where and how it runs, covering cloud region, container orchestration, and how it scales.
- Pivotal technical choices: the 3–5 decisions inside this option that do the most to shape how the system behaves.
To make sure the options really diverge, change one fundamental dimension between them:
| Dimension to vary | How the options might differ |
|---|---|
| Primary decomposition axis | One splits by business domain, another by technical layer, a third by deployment unit |
| Consistency versus availability | One leans toward strong consistency, another toward availability with eventual consistency |
| Build versus buy | One builds a custom component, another relies on a managed service, a third adopts an open-source solution |
Phase 4: Weigh the trade-offs
This is where the real thinking of architecture happens. Score every option against each non-functional requirement from Phase 1 in a matrix like this:
| Quality attribute | Goal | Option A | Option B | Option C |
|-------------------|-----------------|-----------------|-----------------|-----------------|
| Availability | 99.9% | [verdict + why] | [verdict + why] | [verdict + why] |
| Latency (p95) | < 200ms | [verdict + why] | [verdict + why] | [verdict + why] |
| Scalability | 50k concurrent | [verdict + why] | [verdict + why] | [verdict + why] |
| Time to market | 3 months | [verdict + why] | [verdict + why] | [verdict + why] |
| Operational cost | < $X/month | [verdict + why] | [verdict + why] | [verdict + why] |
| Team capability | Current skills | [verdict + why] | [verdict + why] | [verdict + why] |
The verdict in each cell is Meets, Partially meets, or Does not meet, followed by a short explanation.
Then tackle these recurring tensions head-on, answering the question attached to each:
- Consistency vs. availability: the CAP theorem says that during a network partition you get one or the other. Which does this system favor, and why?
- Simplicity vs. flexibility: monoliths are easier to build and deploy, whereas microservices let parts scale and ship on their own. What does this system really need?
- Latency vs. throughput: batching buys throughput at the cost of latency. For this use case, which matters more?
- Build vs. buy: writing it yourselves gives control, while a managed service takes operational burden off the team. How much ops capacity does the team have?
- Coupling vs. autonomy: one shared database keeps data access simple, while separate data stores let teams move independently. How is the organization structured?
- Cost now vs. cost later: a fast fix can leave technical debt behind, whereas a robust solution takes longer to deliver. What time horizon applies?
Finally, run a failure mode analysis on every option by asking:
- What happens if [component X] fails?
- How large is the blast radius, meaning which other components feel it?
- How does the system notice the failure?
- How does it recover: on its own, only once someone steps in by hand, or never?
- Which data is exposed while the failure lasts?
Phase 5: Sanity-check capacity
Use back-of-the-envelope math to confirm the chosen design can cope with the expected load. Treat the results as order-of-magnitude figures; only load testing gives precise numbers. Build the estimate in five steps:
- User behavior: how many users there are, how many actions each takes per day, and the peak-to-average traffic ratio.
- System load: peak actions per second, the read-to-write ratio, payload sizes.
- Storage footprint: data per record × records per day × retention period, plus allowance for indices, replicas, and backups.
- Compute need: requests per second × processing time per request = the compute capacity required; add headroom, typically 2–3x, for peaks and growth.
- Network: data transferred per request × requests per second, plus cross-region replication where it applies.
Lay the numbers out like this:
Sizing sheet for [system]
Inputs (write down every assumption):
- Users: [X]
- Daily actions per user: [Y]
- Peak-to-average multiplier: [Z]
- Read:write split: [R:W]
- Mean payload: [N KB]
Peak traffic:
X users × Y actions/day ÷ 86,400 sec/day × Z peak ratio = [N] req/sec at peak
Data stored over 1 year:
[N] writes/day × [M] bytes/write × 365 days = [T] GB/year
With indices and replicas (× 3 estimate): [T×3] GB/year
Processing:
[N] req/sec × [M] ms/req = [C] compute-seconds/sec
Required instances: [C] ÷ [instance capacity] = [I] instances + [headroom]
Check: do these totals stay inside the Phase 2 cost constraint?
Phase 6: Write the ADR
Capture the decision in an Architecture Decision Record. The ADR is the deliverable: if it isn't written, the reasoning disappears and the same decision gets argued all over again.
ADR format
# ADR-[NNN]: [Short name for the decision]
- **Date:** [YYYY-MM-DD]
- **Status:** [Proposed | Accepted | Deprecated | Superseded by ADR-NNN]
## Context
[Which architectural question this answers; the technical, organizational, and business forces acting on it; the constraints in force.]
## Decision
[One plain statement of the choice, e.g. "We will adopt [approach X] to achieve [purpose Y]."]
## Alternatives weighed
| Option | Summary | Strengths | Weaknesses |
|---|---|---|---|
| A: [label] | [a line or two] | [bullet points] | [bullet points] |
| B: [label] | [a line or two] | [bullet points] | [bullet points] |
| C: [label], only if a third exists | [a line or two] | [bullet points] | [bullet points] |
## Trade-off summary
[The Phase 4 matrix in condensed form, naming the requirements that tipped the balance.]
## Sizing
[The headline numbers from Phase 5 that back the choice.]
## Consequences
[What this makes easier, what it makes harder, and which new constraints it introduces.]
## What could go wrong
[Ways this choice could go wrong, and the signals that would call for a rethink.]
## When to revisit
[Conditions that reopen the decision, e.g. traffic beyond 10x the estimate, a team twice its current size, a shift in compliance requirements.]
Completeness review
Once the design is done, walk through this checklist to confirm nothing is missing.
Requirements coverage
- Every functional requirement traces back to a component
- Every non-functional requirement carries a measurable target that the design demonstrably meets
- Each integration point is listed together with its protocol, data format, and failure modes
Resilience
- Single points of failure are known, and each one is either mitigated or recorded as an accepted risk
- Every component's failure modes are documented alongside a recovery strategy
- Data backup and restore is planned, with RPO/RTO targets that have actually been tested
- Non-critical components can degrade gracefully
Scalability
- Capacity estimates show the design can handle the target load
- Bottleneck components have a path to horizontal scaling
- If one node can't hold the data, a partitioning strategy exists
Security
- Data is classified (what counts as sensitive, what is public)
- Boundaries for authentication and authorization are drawn
- Network segmentation keeps trust zones apart
- The design specifies encryption both at rest and in transit
Operability
- The observability strategy covers metrics, logs, and traces
- The deployment strategy allows releases with zero downtime
- Every deployable component has a rollback procedure
- On-call scope is defined: what needs a human and what recovers on its own
Evolutionary architecture
- Components can be swapped out independently
- The ADR's "When to revisit" section names the review triggers for reconsidering the architecture
- For a redesign, migration paths lead away from the current state
Ground rules
- Don't make up performance numbers or benchmarks. Real performance hinges on configuration, hardware, and workload, so write
[Needs benchmarking against your own workload and setup]in their place. - Don't push specific technologies without knowing the user's context. Lay out the trade-off analysis, and don't declare one option superior before you understand the requirements.
- Don't present capacity estimates as exact. Tag every estimate with
[Rough order of magnitude — confirm through load tests]. - Mark where each output comes from with one of three tags:
[Source: user's requirements],[Source: standard design method], or[Source: AI judgment — verify before relying on it].