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.md

GitHub

Architecture 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:

  1. Enumerate the core use cases, and for each one name the actor, the action, and the outcome they expect.
  2. Identify the data entities and how they relate, and for each one note whether the system creates, reads, updates, or deletes it.
  3. List every integration point: the external systems involved, along with each one's API, data format, and reliability profile.
  4. 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:

  1. Architecture style: for example monolith, modular monolith, microservices, serverless, event-driven, CQRS, or another style.
  2. 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).
  3. Data layer: where data is stored, which storage technologies hold it, and how it flows.
  4. Deployment model: where and how it runs, covering cloud region, container orchestration, and how it scales.
  5. 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:

  1. What happens if [component X] fails?
  2. How large is the blast radius, meaning which other components feel it?
  3. How does the system notice the failure?
  4. How does it recover: on its own, only once someone steps in by hand, or never?
  5. 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:

  1. User behavior: how many users there are, how many actions each takes per day, and the peak-to-average traffic ratio.
  2. System load: peak actions per second, the read-to-write ratio, payload sizes.
  3. Storage footprint: data per record × records per day × retention period, plus allowance for indices, replicas, and backups.
  4. Compute need: requests per second × processing time per request = the compute capacity required; add headroom, typically 2–3x, for peaks and growth.
  5. 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].