software-architecture

Design scalable architectures by applying structured frameworks—layered, hexagonal, or microservices patterns—paired with trade-off analysis and Architecture Decision Records (ADRs). The skill enforces a phased workflow: discovery, constraint evaluation, design, and standardized documentation with observability practices to ensure maintainability as systems grow.

Evaluate architectural trade-offs by establishing clear criteria, comparing options systematically, and documenting decisions through ADRs. This approach captures reasoning for technology stack choices, scaling strategies, and performance decisions, creating a reference for future maintainers and preventing recurring design debates.

Use ADRs when designing new systems, planning major features, evaluating architectural approaches, or making technology stack decisions. ADRs document the context, options considered, trade-offs, and final decision, creating maintainable reference records that guide long-term system evolution.

Yes. The skill applies to designing new systems and refactoring existing ones. Use architectural frameworks and decision records to evaluate current approaches, plan feature additions, or migrate to patterns like microservices, ensuring decisions are documented and constraints are explicitly evaluated.

Plan for scale by identifying performance constraints during discovery and analysis phases, selecting patterns that handle your load profile, and documenting observability practices. The ADR-driven workflow ensures scaling decisions are explicit, justified, and communicated to the team.

Create standardized Architecture Decision Records capturing problem context, architectural options evaluated, constraints, trade-offs, and the chosen approach. Include observability practices and TodoWrite steps to ensure decisions are traceable, decisions remain discoverable, and implementation guidance is clear.