Skill · Version 1.0.0

Architecture planning

Shapes the smallest viable architecture around measurable requirements, explicit data ownership and the operational trade-offs your team faces.

architecture-planning

See how it helps

When is it useful?

Use when a feature needs clear responsibilities, data ownership and realistic operational requirements before development.

What does it help you do?

Maps components and interfaces to measurable performance, recovery and budget requirements.
Compares viable architectural options with their operating costs and failure modes.
Records consequential decisions and unresolved assumptions without designing for imaginary scale.

Try asking this

Plan a document-processing service for our existing application, comparing a background worker with a separate service. Use the expected daily document volume and recovery deadline. Deliver a decision with deployment steps, failure handling and the conditions that would justify revisiting it.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Architecture Planning

Design the simplest system that meets the real requirements and that the team can build, run and change. Start from the existing system, never from a blank page.

Workflow

Requirements: the functional ones, the non-functional ones with numbers, and the constraints (budget, timeline, team, existing stack). Do not design until they are covered; name what is missing and ask.
Options: map the requirements to patterns, and keep at least one alternative to the favorite.
Design: components and their responsibilities, data ownership, the interfaces between them, and a diagram (Mermaid or ASCII) when it helps.
Decide: state each key decision with its trade-off; record the ones that pass the ADR gate.
Review: check the design against the requirements and the failure modes; on a gap, return to step 3.

Non-functional requirements, with numbers

Performance: p95 latency per key endpoint (for example under 200 ms), throughput, batch volume.
Scale: concurrent users, requests per second, data volume and growth, peak versus average.
Availability: 99.9% allows about 8.8 hours of downtime a year, 99.99% about 53 minutes. Choose by need; every extra nine costs.
Recovery: RPO (data you may lose) and RTO (time to restore), and the backups that meet them.
Security and compliance: authentication, authorization model, data sensitivity, encryption, tenant isolation, regulations.
Operations and cost: deploy frequency, monitoring, on-call, monthly budget.

Patterns

Pattern	Fits	Cost
Monolith	Simple domain, small team	Parts cannot scale separately
Modular monolith	Growing domain, one deploy	Module boundaries need discipline
Microservices	Large organization, clear boundaries, different scaling	Distributed failures, eventual consistency, heavy operations
Serverless	Spiky, event-driven load	Cold starts, vendor lock-in
Event-driven	Asynchronous work, loose coupling	Harder debugging, ordering, eventual consistency
CQRS	Reads far outnumber writes or need other shapes	Two models to keep in sync
Prefer the left column's simpler option until a concrete requirement and the team's capacity justify the next one. Never choose a pattern for an imagined future scale.

Failure modes

For each component: what fails, the impact, and the mitigation (database down: failover; cache down: fall back to the database, degraded; external API slow: timeout and fallback). Plan for partial failure, retries and duplicates at every boundary.

Architecture decision records

Write an ADR only when all three hold:

Hard to reverse: changing your mind later would cost something meaningful.
Surprising without context: a future reader would wonder why it was done this way.
A real trade-off: there were genuine alternatives and one was chosen for specific reasons. Typical cases: the architectural shape, how contexts integrate, technology with lock-in (database, message bus, auth provider, hosting), ownership and scope boundaries (an explicit "no" counts), deliberate deviations from the obvious path, constraints not visible in code, and rejected alternatives someone will propose again. Format: put it where the project keeps them (otherwise docs/adr/0001-short-slug.md, numbered in sequence); a title and 1–3 sentences on context, decision and why. Add status, alternatives considered or consequences only when they add value.

Rules

Weigh the downsides and operating cost, not only the benefits; record each technology choice with the alternatives considered.
Every piece of data and every business rule has exactly one owner.
Security is part of the design: trust boundaries, authorization, secrets.
Keep proven facts, assumptions and proposals apart, and name what is uncertain.

Output

A requirements summary, the design (components, data, interfaces, diagram), key decisions with trade-offs, risks and mitigations, open questions.

Included files 2

LICENSE.txt
SKILL.md