architecture-patterns_skill

Overview

This skill recommends, evaluates, documents, and helps migrate software architecture patterns for systems of varying complexity. It focuses on matching requirements to established patterns (layered, hexagonal, clean, CQRS, event sourcing) and producing pragmatic outputs like ADRs, architecture evaluations, and migration plans. The skill is atomic, idempotent, and intended for integration into design pipelines or assistant workflows.

How this skill works

Provide an action (recommend, evaluate, document, migrate) and the relevant inputs: system requirements for recommendations, current and target architectures for evaluation or migration, and optional constraints or team size. The skill uses a decision matrix and pattern catalog to score fits, explains tradeoffs, generates concise rationale, and can emit ADR-style documentation or migration steps. Validation ensures required fields are present and errors guide corrective input.

When to use it

• Selecting an architecture for a new project based on functional and non-functional requirements.
• Evaluating an existing architecture against scalability, testability, and maintainability goals.
• Documenting an architecture decision as an ADR for team alignment and audits.
• Planning a migration from a legacy architecture to a modern pattern with minimized risk.
• Choosing patterns for read-heavy, audit-heavy, or complex domain systems.

Best practices

• Supply concrete functional requirements and explicit non-functional targets (scalability, testability, performance).
• Include domain complexity and team size to balance pattern fit versus implementation cost.
• Use generated ADRs as a baseline and iterate with stakeholders before final acceptance.
• Prefer prototypes or pilot modules when adopting high-complexity patterns (CQRS, event sourcing).
• Limit migration scope to bounded contexts and define rollback criteria for each step.

Example use cases

• Recommend Hexagonal or Clean Architecture for a complex enterprise system with high testability needs.
• Advise Layered Architecture for a small team building a simple CRUD application to reduce upfront complexity.
• Generate an ADR documenting the decision to adopt event sourcing for audit and temporal query requirements.
• Evaluate a monolith and produce a phased migration plan toward Microservices using CQRS where read scalability is critical.