arquitetura-hexagonal

Analise uma base de código existente em qualquer linguagem ou framework e produza um plano de refatoração por fases, com zero quebras, para migrá-la para Arquitetura Hexagonal (Ports and Adapters). Use quando o usuário pedir para refatorar, migrar ou reestruturar um serviço, API ou monólito para arquitetura hexagonal, ports and adapters ou clean architecture, preservando contratos existentes.

O que é arquitetura-hexagonal?

Esta skill analisa profundamente um repositório existente e projeta um plano de refatoração atômico e faseado para migrá-lo para Arquitetura Hexagonal (Ports and Adapters) sem quebrar nenhum contrato externo ou comportamento observável. Ela garante a **Regra de Ouro de Zero Quebras**, preservando cada contrato externo: rotas, métodos HTTP, códigos de status, esquemas de payload de requisição/resposta, cabeçalhos, formatos de erro, flags de CLI ou formatos de mensagem de fila. A skill suporta qualquer linguagem (TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust) e framework, adaptando caminhos de diretório, convenções de nomenclatura, construções de tipagem e executores de teste ao ecossistema detectado. Ela opera estritamente em **Modo Plano**: inspeciona o código primeiro e entrega o plano completo antes de modificar qualquer arquivo, seguindo um fluxo de trabalho de três camadas (domínio, aplicação, infraestrutura) com ênfase em testes de caracterização, injeção de dependência e observabilidade desacoplada. O resultado final é um plano de execução detalhado com cinco fases, desde a criação de testes de contrato até a limpeza do legado, garantindo que o código possa ser refatorado com segurança.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gabrandalisse/skills/tree/HEAD/skills/to-hexagonal-architecture

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Para Arquitetura Hexagonal

Analise um repositório existente em profundidade e projete um plano de refatoração atômico e faseado para migrá-lo para Arquitetura Hexagonal (Ports and Adapters) sem quebrar nenhum contrato externo ou comportamento observável.

Responda no mesmo idioma da solicitação do usuário. Opere estritamente em Modo Plano: inspecione o código primeiro e entregue o plano completo antes de modificar qualquer arquivo.

Quando Usar

  • O usuário pede para migrar ou refatorar um projeto existente para Arquitetura Hexagonal ou Ports and Adapters.
  • O usuário deseja desacoplar a lógica de negócio de frameworks web, ORMs, bancos de dados, brokers de mensagens ou SDKs externos.
  • O usuário pede um plano de refatoração arquitetural seguro e incremental com zero quebras.

Princípios Fundamentais

  1. Zero Quebras (Regra de Ouro): Preserve todos os contratos externos existentes. Rotas, métodos HTTP, códigos de status, esquemas de payload de requisição/resposta, cabeçalhos, formatos de erro, flags de CLI ou formatos de mensagem de fila devem permanecer idênticos.
  2. Caracterização Antes da Refatoração: Nunca mova ou exclua lógica de produção até que testes automatizados de contrato/caracterização cubram endpoints ou pontos de entrada existentes.
  3. Regra de Dependência Estrita: As dependências do código-fonte devem sempre apontar para dentro, em direção ao domain. A camada de domínio não deve ter nenhum import de frameworks web, drivers de banco de dados, ORMs, bibliotecas de serialização ou SDKs externos.
  4. Adaptação Idiomática da Stack: Adapte caminhos de diretório, convenções de nomenclatura, construções de tipagem e executores de teste ao idioma e ecossistema detectados no projeto (por exemplo, TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust).

Fluxo de Trabalho

Passo 1: Descoberta do Código

Escaneie o repositório antes de propor qualquer árvore de pastas ou etapas de migração:

  1. Stack e Ferramentas: Inspecione manifestos de dependência, configurações de compilador/linter e executores de teste para identificar o idioma, framework, biblioteca de validação, ORM/query builder e abordagem de DI.
  2. Pontos de Entrada e Contratos: Inventarie todos os pontos de entrada acionadores (rotas HTTP, resolvers GraphQL, serviços gRPC, consumidores de mensagens, jobs cron), seus esquemas de validação, middlewares/interceptadores e manipuladores globais de erro.
  3. Dependências Externas: Inventarie todos os efeitos colaterais acionados (bancos de dados, caches, clientes HTTP/RPC, filas, armazenamento de arquivos, configuração de ambiente, loggers).
  4. Fluxo de Execução Atual: Rastreie como os dados fluem atualmente do ponto de entrada até a persistência/chamada externa e de volta, observando onde as regras de negócio estão misturadas com detalhes de transporte ou persistência.

Passo 2: Projetar o Layout Hexagonal Alvo

Mapeie as três camadas concêntricas para a raiz de origem idiomática do projeto (por exemplo, src/ em TypeScript/Rust, internal/ em Go, src/main/<lang>/ em JVM, ou o diretório principal do pacote em Python):

  • domain/ (Núcleo de Negócio Puro - zero dependências de framework ou I/O):
    • entities/ e value-objects/: Modelos de domínio encapsulando regras de negócio, invariantes e autovalidação.
    • ports/in/: Interfaces de porta de entrada definindo contratos de caso de uso.
    • ports/out/: Interfaces de porta de saída definindo contratos de repositório, serviço externo, publicador de eventos e LoggerPort.
    • errors/: Exceções semânticas de domínio (por exemplo, ResourceNotFoundError, DomainValidationError, ConflictError).
  • application/ (Orquestração de Casos de Uso):
    • use-cases/: Implementações de ports/in coordenando entidades de domínio e ports/out.
    • dtos/: Estruturas de dados imutáveis de entrada e saída desacopladas de payloads de transporte e entidades de persistência.
  • infrastructure/ (Detalhes Técnicos e Adaptadores):
    • adapters/in/: Adaptadores de entrada (controladores/manipuladores HTTP, manipuladores de consumidores), esquemas de validação de transporte, mapeadores (TransportInput -> InputDTO e OutputDTO -> TransportOutput) e um mapeador global de erro que traduz domain/errors para as respostas de erro exatas do legado.
    • adapters/out/: Implementações concretas de ports/out (repositórios de banco de dados, clientes HTTP, brokers) com mapeadores de persistência/externo para que modelos de ORM ou tipos de SDK nunca vazem para domain/.
    • config/: Carregamento estrito e validação de inicialização de variáveis de ambiente e configurações de runtime.
    • di/ (Raiz de Composição): Conexão explícita de adaptadores acionados, casos de uso e adaptadores acionadores via injeção de construtor, evitando singletons ocultos ou localizadores de serviço.
  • Separação de Bootstrap: Separe a construção da aplicação (buildApp / função de fábrica para teste de integração isolado) da inicialização do servidor/processo (main / listen).

Passo 3: Aplicar Padrões de Engenharia no Plano

Garanta que cada fase do plano aplique:

  • Tipagem Forte e Imutabilidade: Proíba escapes não tipados (como any ou mapas não tipados brutos onde estruturas tipadas se aplicam) e favoreça DTOs imutáveis e Value Objects (readonly, dataclasses congeladas, records, tipos de valor).
  • SOLID e Injeção de Construtor: Mantenha classes e funções pequenas com responsabilidades únicas; injete interfaces via construtores.
  • Observabilidade Sem Acoplamento: Preserve o log estruturado e o contexto de correlação de requisição enquanto mantém domain/ e application/ desacoplados de bibliotecas de log específicas via LoggerPort.
  • Testes Piramidais:
    • Testes unitários para domain/ (invariantes puras) e application/ (mocking ports/out).
    • Testes de integração/contrato verificando adaptadores de entrada reais contra a fiação da aplicação usando o cliente de teste em memória nativo da stack (por exemplo, fastify.inject, Supertest, FastAPI TestClient, Spring MockMvc, ou Go httptest).

Formato de Saída (Modo Plano)

Entregue a resposta estruturada nestas seções exatas:

  1. Diagnóstico da Arquitetura Atual: Inventário conciso da stack detectada, pontos de entrada/endpoints, dependências externas e principais pontos de acoplamento.
  2. Árvore de Diretórios Alvo: Estrutura de pastas proposta completa usando os nomes reais de módulos e funcionalidades encontrados no repositório.
  3. Plano de Execução por Fases: Cinco fases atômicas e verificáveis:
    • Fase 1 - Testes de Caracterização e Scaffolding Base: Crie testes de contrato travando o comportamento atual, crie pastas alvo, carregador de configuração e Raiz de Composição (di/).
    • Fase 2 - Extração do Domínio: Extraia entidades, objetos de valor, erros de domínio e interfaces ports/in + ports/out com testes unitários.
    • Fase 3 - Casos de Uso da Aplicação e Adaptadores Acionados: Implemente casos de uso, DTOs, repositórios/clientes adapters/out e mapeadores de persistência.
    • Fase 4 - Adaptadores de Entrada e Tradução de Erro: Refatore controladores/manipuladores para delegar a casos de uso via mapeadores, conecte a tradução global de erro e ligue di/.
    • Fase 5 - Limpeza do Legado e Verificação Final: Remova arquivos obsoletos, execute a suíte de testes completa, linter e verificador de tipos, e verifique zero desvio de contrato.
  4. Pontos de Verificação de Validação: Comando explícito ou verificação ao final de cada fase provando que nada quebrou antes de avançar para a próxima fase.

Armadilhas

  • Não edite código prematuramente: A menos que o usuário peça explicitamente para começar a executar a Fase 1 imediatamente, produza apenas o plano primeiro para que eles possam revisar os limites dos módulos.
  • Evite abstração excessiva em CRUD trivial: Ainda separe domain, application e infrastructure claramente, mas mantenha casos de uso de passagem concisos em vez de inventar complexidade de domínio artificial.
  • Corresponda a peculiaridades do legado: Se um endpoint existente retornar um código de status não padrão ou nome de campo de erro, documente-o na Fase 1 e preserve-o no mapeador de erro infrastructure para que clientes existentes não quebrem.

Habilidades Relacionadas