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.claude/skills/architecture-specialist/SKILL.md
GitHubArchitecture 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
Glob('**/ADR*', '**/adr*', '**/docs/**/*.md')— find existing architecture docs and decisions- Read any existing ADRs or design docs to understand prior decisions and constraints
- 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