Architecture planning
Plans the responsibilities of the game client, match server and persistent services around your actual requirements. Compares practical options, recovery needs and operating costs before implementation.
architecture-planning
Agents using this skill
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 cooperative dungeon game for four players per session. Decide where movement, loot and saved progress are authoritative, and describe what happens when a player disconnects. Compare extending the existing server with adding a separate service, including the evidence needed to choose between them.
Detailed documentation
Read the skill’s original instructions, examples and checks in their authored language.
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.txtSKILL.md