Habilidade de Desenvolvimento de Arquitetura de Software

Esta habilidade fornece orientação para o desenvolvimento e arquitetura de software focados em qualidade. Ela é baseada nos princípios de Arquitetura Limpa (Clean Architecture) e Design Orientado a Domínio (Domain Driven Design).

Regras de Estilo de Código

Princípios Gerais

• Padrão de retorno antecipado (early return): Sempre use retornos antecipados quando possível, em vez de condições aninhadas, para melhor legibilidade.
• Evite duplicação de código através da criação de funções e módulos reutilizáveis.
• Decomponha componentes e funções longos (mais de 80 linhas de código) em múltiplos componentes e funções menores. Se eles não puderem ser usados em outro lugar, mantenha-os no mesmo arquivo. Mas se o arquivo tiver mais de 200 linhas de código, ele deve ser dividido em vários arquivos.
• Use funções de seta (arrow functions) em vez de declarações de função quando possível.

Melhores Práticas

Abordagem "Biblioteca Primeiro" (Library-First Approach)

• SEMPRE procure por soluções existentes antes de escrever código personalizado.
  • Verifique o npm em busca de bibliotecas existentes que resolvam o problema.
  • Avalie serviços/soluções SaaS existentes.
  • Considere APIs de terceiros para funcionalidades comuns.
• Use bibliotecas em vez de escrever suas próprias utilidades ou helpers. Por exemplo, use cockatiel em vez de escrever sua própria lógica de retentativa.
• Quando código personalizado É justificado:
  • Lógica de negócios específica e única do domínio.
  • Caminhos críticos de desempenho com requisitos especiais.
  • Quando dependências externas seriam excessivas.
  • Código sensível à segurança que requer controle total.
  • Quando soluções existentes não atendem aos requisitos após avaliação completa.

Arquitetura e Design

• Princípios de Arquitetura Limpa e DDD:
  • Siga o design orientado a domínio e a linguagem ubíqua.
  • Separe entidades de domínio de preocupações de infraestrutura.
  • Mantenha a lógica de negócios independente de frameworks.
  • Defina casos de uso claramente e mantenha-os isolados.
• Convenções de Nomenclatura:
  • EVITE nomes genéricos: utils, helpers, common, shared.
  • USE nomes específicos do domínio: OrderCalculator, UserAuthenticator, InvoiceGenerator.
  • Siga os padrões de nomenclatura de contexto delimitado (bounded context).
  • Cada módulo deve ter um único propósito claro.
• Separação de Preocupações (Separation of Concerns):
  • NÃO misture lógica de negócios com componentes de UI.
  • Mantenha consultas ao banco de dados fora dos controllers.
  • Mantenha limites claros entre os contextos.
  • Garanta a separação adequada de responsabilidades.

Anti-Padrões a Evitar

• Síndrome NIH (Not Invented Here - Não Inventado Aqui):
  • Não crie autenticação personalizada quando Auth0/Supabase existem.
  • Não escreva gerenciamento de estado personalizado em vez de usar Redux/Zustand.
  • Não crie validação de formulário personalizada em vez de usar bibliotecas estabelecidas.
• Escolhas Arquiteturais Ruins:
  • Misturar lógica de negócios com componentes de UI.
  • Consultas ao banco de dados diretamente em controllers.
  • Falta de separação clara de preocupações.
• Anti-Padrões de Nomenclatura Genérica:
  • utils.js com 50 funções não relacionadas.
  • helpers/misc.js como um "depósito" genérico.
  • common/shared.js com propósito pouco claro.
• Lembre-se: Cada linha de código personalizado é um passivo que requer manutenção, testes e documentação.

Qualidade do Código

• Tratamento adequado de erros com blocos catch tipados.
• Divida a lógica complexa em funções menores e reutilizáveis.
• Evite aninhamento profundo (máximo de 3 níveis).
• Mantenha funções focadas e com menos de 50 linhas, quando possível.
• Mantenha arquivos focados e com menos de 200 linhas de código, quando possível.

Quando Usar

Esta habilidade é aplicável para executar o fluxo de trabalho ou as ações descritas na visão geral.

Exemplo

Solicitação do usuário:

Use @software-architecture para esta tarefa: Guia para arquitetura de software focada em qualidade.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.