senior-architect_skill

Overview

This skill provides senior-level software architecture workflows and tooling to design, document, and defend scalable, reliable systems. It focuses on translating requirements and constraints into clear system boundaries, runtime containers, APIs, risk analyses, and actionable architectural decisions. The outputs are shippable artifacts: an architecture doc, ADRs, and a diagram.

How this skill works

The skill inspects project code and dependency signals to infer components, frameworks, and service boundaries, then generates a documentation skeleton and starter diagrams. It guides you through clarifying constraints, producing context/containers/interfaces/risks, and formalizing trade-offs as ADRs. Optional scripts can bootstrap docs, analyze dependencies, and produce a Mermaid diagram from detected components.

When to use it

• Defining or revising architecture for a new feature or system
• Choosing databases, APIs, queues, caching, or observability stacks
• Preparing ADRs for high-impact technical decisions
• Reviewing an existing codebase to extract architecture and risks
• Planning scalability, availability, and operational runbooks

Best practices

• Start by capturing the primary user journey and measurable success metrics
• List non-functional requirements (latency, throughput, availability, cost, compliance) up front
• Document system boundary and external dependencies before diving into components
• Model containers and interfaces with explicit data ownership and contracts
• Write ADRs that state options, trade-offs, chosen approach, and migration plan
• Include failure modes, mitigations, and open questions as part of the architecture deliverable

Example use cases

• Bootstrap an architecture doc and ADRs for a new microservice handling payments
• Analyze a monorepo to surface backend/frontend runtimes and produce a starting Mermaid diagram
• Compare DB/queue/cache options with a tech decision matrix and capture the result in an ADR
• Produce a scalability plan: assumptions, bottlenecks, and mitigation path for a high-throughput API
• Review an acquired codebase to produce a concise architecture summary and risk register