System Design Review skill for Claude Code

A useful design review turns vague claims (“it scales”) into numbers, follows real requests through the design, and names the specific failure that will happen first. The output is a short list of ranked findings with alternatives, not a rewrite of the design.

Ground rules

• Review against stated requirements. If requirements are missing, write the assumed ones down and flag them as the first finding.
• Every scale claim gets an estimate with units. “High traffic” is not a number.
• Distinguish blockers from preferences. A different but workable database choice is not a finding.
• Prefer the simplest design that meets the numbers. Complexity needs a requirement that justifies it.
• Name the tradeoff the author made, even when you agree with it, so it is explicit.

Workflow

- [ ] 1. Extract requirements and constraints (write assumptions explicitly)
- [ ] 2. Back-of-envelope estimates: QPS, peak, storage, bandwidth, fan-out
- [ ] 3. Trace 2–4 critical use cases end to end
- [ ] 4. Check the data model against access patterns
- [ ] 5. Find bottlenecks at 1x and 10x
- [ ] 6. Walk failure modes component by component
- [ ] 7. Check consistency, security, operability, cost, migration
- [ ] 8. Write ranked findings with alternatives

1. Requirements

Fill this table before judging anything:

Dimension	Question	Example answer
Users and actions	Who does what, how often?	2M DAU, 20 reads + 2 writes per user/day
Latency	Target per operation at p95/p99	Feed read p95 < 200 ms
Availability	SLO and what “down” means	99.9% monthly on read path
Consistency	Which reads must see which writes?	Own posts visible immediately; others within 5 s
Durability	Acceptable data loss (RPO), recovery time (RTO)	RPO 1 min, RTO 30 min
Growth	Horizon and expected multiplier	5x in 18 months
Constraints	Team size, budget, compliance, existing stack	6 engineers, GDPR, AWS, Postgres expertise

2. Estimates

Use round numbers and orders of magnitude. 1 day ≈ 10^5 seconds.

Writes:  2M users x 2/day       = 4M/day   ≈ 46/s avg  → peak x5 ≈ 250/s
Reads:   2M users x 20/day      = 40M/day  ≈ 460/s avg → peak x5 ≈ 2,500/s
Storage: 4M posts/day x 1 KB    = 4 GB/day ≈ 1.5 TB/year (+indexes, replicas: x3)
Fan-out: avg 200 followers x 250 writes/s = 50k timeline inserts/s if fan-out-on-write

The fan-out line is often where designs break. Latency, throughput, and availability rules of thumb are in references/estimation-cheatsheet.md; read it when you need reference numbers for a component.

3. Trace critical paths

For each key use case, list every hop with its expected latency and what happens if it fails:

POST /posts: client → LB (1 ms) → API (5 ms) → Postgres insert (3 ms)
             → outbox → queue → fan-out worker → Redis timelines (async)
Read feed:   client → CDN miss → API → Redis timeline (1 ms) → hydrate 50 posts
             from Postgres (N+1 risk!) → response

Look for: synchronous chains longer than 3–4 services, N+1 hydration, calls across regions on the hot path, work done on the request path that could be async.

4. Data model vs. access patterns

• List every query the hot paths need, with its frequency. Check each has an index or a key-based lookup; check no hot path needs a cross-shard join or full scan.
• Check the partition/shard key distributes load (no celebrity user or single tenant dominating one partition).
• Check data growth: which tables grow unbounded, what is the retention policy?

5. Bottlenecks

Component	Check
Database	Write rate vs. single-primary capacity; connection count vs. pool limits; largest table size; hot rows (counters, locks)
Cache	Hit ratio assumption; behavior on cold start or flush (thundering herd); eviction policy; key cardinality
Queue/stream	Partition count vs. consumer parallelism; ordering requirements; consumer lag at peak
Stateless services	CPU per request x peak QPS; autoscaling lag vs. spike shape
External APIs	Their rate limits and latency at your peak
Network	Payload size x QPS; cross-AZ/region egress cost

Ask “what breaks first at 10x?” and name it. That is usually the most valuable finding.

6. Failure modes

Walk each component and dependency:

Component	Failure	Detection	Impact	Mitigation in design?
Postgres primary	Crash / failover (30–60 s)	Health check	Writes fail	Retries with idempotency?
Redis	Eviction or restart	Hit ratio alert	DB load spike x20	Request coalescing?
Payment provider	Latency 10 s	p99 alert	Threads exhausted	Timeout + circuit breaker?
Queue consumer	Poison message	DLQ depth	Stuck partition	DLQ + skip?
Region	Outage	External probe	Full outage	Required by SLO?

Also check: retries without backoff (amplification), missing timeouts, unbounded queues, cascading failure through shared dependencies, deploys and migrations as failure events.

7. Cross-cutting checklist

• Consistency: where is the source of truth? Dual writes without an outbox? Cache invalidation strategy? Read-your-writes requirements met?
• Idempotency: every retried operation has a key or natural idempotence.
• Security: authn/authz at each entry point, tenant isolation, secrets, PII flows, encryption in transit and at rest.
• Operability: metrics, traces, alerts tied to SLOs, runbooks, feature flags for rollout, backfill and replay tools.
• Cost: biggest line items at expected scale (egress, managed DB size, per-request pricing of third parties).
• Evolution: schema migration strategy, API versioning, how to roll back.
• Simplicity: could a single Postgres + a queue meet the numbers for the next 2 years?

8. Write findings

Severity levels:

• Blocker: will not meet a stated requirement or will lose/corrupt data.
• Major: likely incident or rework within the growth horizon.
• Minor: improvement with clear benefit, not urgent.
• Question: missing information needed to judge.

Output template

# Design review: <design name> (<doc link>, reviewed <date>)

## Summary
One paragraph: overall assessment, the top risk, and whether it can proceed.

## Requirements as understood
<table from step 1; mark assumptions with (assumed)>

## Estimates
<calculations from step 2>

## Findings
1. **[Blocker] Fan-out-on-write cannot sustain peak.** 250 posts/s x 200 followers =
   50k Redis writes/s, with celebrity accounts at 1M followers producing 1M writes per
   post. *Alternative:* hybrid fan-out (push for accounts < 10k followers, pull at read
   time for large accounts). *Tradeoff:* more complex read path.
2. **[Major] Order service calls inventory and payment synchronously with no timeouts.**
   ...
3. **[Question] What is the RPO for the events store?** ...

## Tradeoffs the design makes (agreed)
- Eventual consistency on follower feeds (≤ 5 s) in exchange for write scalability.

## Suggested next steps
- Load test the read path at 3,000 req/s before launch.
- Write an ADR for the fan-out choice.

Gotchas

• Averages hide peaks. Size for peak (often 3–10x average) and for the spike shape.
• “We’ll add caching” without a hit ratio and invalidation story is not a plan.
• Microservices proposed for a small team often fail on operability, not scale.
• Reviews that rewrite the whole design get ignored. Limit to the top 5–8 findings.
• A design without a migration and rollback plan for existing data is incomplete.