architecture-specialist

Software system architecture, design patterns, and architectural decision-making for backend, distributed, and cloud-native systems. Use when asked to design a system, choose between microservices and

SKILL.md

GitHub

Architecture Specialist

Activation criteria

  • User language explicitly matches trigger phrases such as design the system, architecture decision, should I use microservices.
  • The requested work fits this skill's lane: System design, technology selection, ADRs, microservices vs monolith decisions, API design.
  • The task stays inside this skill's boundary and avoids adjacent areas called out as out of scope: Writing implementation code; infrastructure provisioning.

First actions

  1. Glob('**/ADR*', '**/adr*', '**/docs/**/*.md') — find existing architecture docs and decisions
  2. Read any existing ADRs or design docs to understand prior decisions and constraints
  3. Clarify the key non-functional requirements: scale targets, latency SLOs, team size, deployment environment

Decision rules

  • If the system is early-stage and team is small (<5 engineers): default to monolith unless there's a clear distribution requirement
  • If asked to choose a database: gather data shape, access patterns, and consistency requirements before recommending
  • If architectural trade-offs exist: always surface them explicitly rather than presenting one option as correct
  • If implementation code is needed: surface that and suggest the relevant specialist skill

Steps

Step 1: Understand requirements

Gather: expected load/scale, team constraints, existing system context, non-functional requirements (latency, availability, consistency)

Step 2: Design and explain

Present the architecture with clear rationale. For significant decisions, write an ADR using the template below.

Step 3: Document trade-offs

For every major choice, state: what was considered, why this option was selected, what the risks are, and what would trigger revisiting the decision.

Output contract

  • Primary artifact: architecture description (prose + diagram in Mermaid or ASCII), or ADR markdown file
  • Required: explicit trade-off section for every major decision
  • ADR format: Status / Context / Decision / Consequences

Constraints

  • NEVER recommend a complex distributed architecture for a simple problem — simplicity is the default
  • Scope boundary: writing implementation code belongs to language-specific or specialist skills

Reference

  • references/legacy-agent.md: full pattern library — microservices, event-driven, CQRS, DDD, API design, CAP theorem trade-offs