Architecture Design: Trade-offs, Failures, Threats

What it does

Designs or reviews a system architecture the way a senior reviewer would: requirements as numbers, every trade-off named with what it gives up, how each component fails, a threat model per trust boundary, and three concrete break scenarios. It ends by naming the design's weakest point.

Why it exists

A box-and-arrow diagram isn't an architecture. The decisions that matter (consistency vs. availability, sync vs. async, edge vs. cloud, who owns which state) are usually left implicit and discovered in production. This skill makes them explicit up front.

How it works

1. Sizes the depth to the stakes: a short form for prototypes, the full form for production, money, personal data, ML, or edge systems.
2. Asks for missing numbers in one message of at most three questions, or states assumptions as numbers and continues.
3. Names each trade-off in one line, including what it gives up.
4. Checks every component against a bundled failure-mode and threat catalog (databases, caches, queues, service calls, ML models, edge devices, LLM agents).
5. Breaks the design with 10× load, a 15-minute outage of the key stateful component, and malicious input, and reports what fails first.

What you get

A design document: requirements, trade-offs, a Mermaid diagram with boundary data, failure-mode and threat tables, observability signals, break scenarios, and the weakest point.

When not to use it

Scaffolding a single simple service, or picking a framework. Use it when scale, distributed state, ML, edge, or agents make the decisions non-obvious.

Open source

Part of claude-rigor-skills: 30 MIT-licensed skills that make AI show its work. The demo below, with its inputs, is in the examples folder.

See it in action

Request:

Use the architecture-design skill: design the backend for live driver locations in a ride-hailing app. 40,000 active drivers send GPS every 4 seconds, riders must see nearby drivers within 1 second, target 99.9% availability, one cloud region, a team of 4 engineers.

Result: the complete, unedited output from a fresh Claude Code session is in examples/architecture-design.

Known limitations

• Capacity figures and cost estimates are reasoned from stated assumptions, not measured; validate them with a load test.
• Cloud service names are examples; the design is portable but the details assume the provider it names.
• It flags open product questions (for example, whether another system depends on this one) rather than answering them for you.

FAQ

What if I don't know my numbers yet? It asks once, in at most three questions. If you can't answer, it states its assumptions as numbers so you can correct them, and continues.

Can it review an existing system instead of designing a new one? Yes. Point it at the design doc or code. It says what it would keep and doesn't redesign parts that already work.

Will it draw a diagram? Yes, as a Mermaid diagram that renders on GitHub and in most docs tools, plus a table of what crosses each boundary.

Compatibility

Works with any agent that supports the SKILL.md standard. The demo was run with Claude Code 2.1.296 (claude-sonnet-5-5). No tools required; reads your existing design docs or code if you point it at them.

Documentation: https://github.com/hemapriyan-rk/claude-rigor-skills/tree/main/skills/architecture-design