Architecture

Workflow (4 Fases)

Fase 1: CONTEXT — Descoberta de Requisitos

1. Mapear Restrições: Identificar limites de tempo, orçamento e stack atual.
2. Identificar Padrões de Carga: Diferenciar volumes de leitura vs. escrita (indicativo de CQRS).
3. Necessidade de Desacoplamento: Avaliar se a comunicação síncrona é um gargalo (indicativo de Event-Driven).

Fase 2: ANALYSIS — Avaliação de Trade-offs

1. Explorar Alternativas: Comparar abordagens (ex: Simples vs. Escalável).
2. Análise de Consistência: Avaliar se o negócio tolera Consistência Eventual ou exige Consistência Forte.
3. Análise de Simplicidade: Justificar a introdução de padrões complexos (CQRS/Events) apenas se o requisito de escala exigir.

Fase 3: DESIGN — Seleção de Padrões e Contratos

1. Modelagem de Comandos/Consultas: Se usar CQRS, definir claramente os modelos de Read e Write.
2. Design de Eventos: Definir schemas de mensagens, estratégias de idempotência e DLQs (Dead Letter Queues).
3. Desenhar Componentes: Aplicar SOLID, DRY e YAGNI ao desenho proposto.

Fase 4: DOCUMENT — Registro e Governança (ADR & Fitness)

1. Escrever o ADR: Documentar a escolha técnica utilizando o template oficial.
2. Definir Fitness Functions: Propor scripts ou testes automatizados para validar se a arquitetura proposta não sofrerá regressões (ex: evitar acoplamento circular).
3. Handoff: Entregar a especificação arquitetural pronta para implementação.

Output Structure

A execução desta skill resulta nos seguintes artefatos mandatórios em .specs/architecture/:

Quality Rules

• Simplicidade First: Não use CQRS ou Eventos se um banco de dados relacional simples resolver o problema.
• Idempotência Obrigatória: Todo design orientado a eventos deve prever processamento repetido sem efeitos colaterais.
• Fitness-Driven: Cada restrição arquitetural importante deve ter uma forma de ser validada automaticamente.
• Visual-First: Todo componente ou fluxo complexo deve ser documentado com Mermaid no System Map.
• Decisões Justificadas: Mudanças estruturais exigem um "Porquê" documentado.

Prohibited

• NUNCA proponha sistemas distribuídos sem uma análise de custo operacional e latência.
• NUNCA use eventos para comunicação que exige resposta imediata (síncrona).
• NUNCA ignore a complexidade de gerenciar consistência eventual no front-end.
• NUNCA inicie o design sem entender os requisitos de throughput e disponibilidade.

Referências

• references/architectural-principles.md — SOLID, KISS, YAGNI.
• references/cqrs-and-events.md — (Novo) Design de comandos e eventos.
• references/evolutionary-architecture.md — (Novo) Fitness Functions e evolução.
• references/adr-template.md — Modelo oficial de ADR.