Communitygithub.com

xfoundries/software-architecture-skills

Orientação arquitetônica consciente do contexto para sistemas de domínio de negócio usando DDD, Arquitetura em Camadas, Arquitetura Cebola, Arquitetura Hexagonal / Ports and Adapters e CQRS.

O que é software-architecture-skills?

Esta skill capacita o agente a construir aplicações de negócio sobre o framework JFoundry sem se desviar de sua arquitetura planejada. Ela fornece orientação passo a passo para projetar a estrutura do projeto, escolher estilos arquitetônicos (Hexagonal como padrão, Cebola quando solicitado), gerenciar dependências via templates Maven e configurar testes ArchUnit desde o início. A skill suporta projetos Java 21 com Maven e enfatiza a separação rigorosa entre domínio (livre de frameworks), aplicação e infraestrutura, além de oferecer referências especializadas para repositórios, conversores de persistência e padrões Outbox/Inbox. É ideal para desenvolvedores que desejam aplicar DDD e arquiteturas limpas de forma consistente, sem reinventar a roda, aproveitando templates e regras pré-definidas do JFoundry.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add xfoundries/software-architecture-skills

Perguntar na sua IA favorita

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

Documentação

Use JFoundry

Propósito

Use esta skill para construir aplicações de negócio no jfoundry sem se desviar da arquitetura pretendida pelo framework. É para projetos de aplicação, não para alterar os internos do framework jfoundry.

Use como padrão um novo projeto Java 21 Maven usando Arquitetura Hexagonal, a menos que o usuário escolha explicitamente Onion. Não defina o Spring Boot como runtime padrão; escolha Spring apenas quando o usuário selecionar Spring Framework, Spring Boot ou um starter específico do Spring. Prefira copiar os templates empacotados primeiro, depois adaptar nomes e pacotes.

Fluxo de Primeiro Uso

  1. Identifique a forma do projeto: módulo de aplicação único, aplicação Maven multi-módulo ou módulos separados de domínio/aplicação/infraestrutura. Prefira multi-módulo Maven para projetos DDD comuns.
  2. Escolha um estilo primário de arquitetura. Prefira Hexagonal para novos projetos de negócio; escolha Onion apenas quando o usuário solicitar ou o código já o utilizar. Não misture Hexagonal e Onion no mesmo escopo de análise ArchUnit.
  3. Leia references/dependencies.md, escolha o BOM pelo runtime e copie os trechos de template Maven correspondentes de assets/templates/maven/.
  4. Leia references/architecture.md e copie a estrutura de pacotes correspondente de assets/templates/structure/.
  5. Copie um template de teste de arquitetura de assets/templates/java/, substitua PACKAGE_NAME e adicione-o sob o conjunto de fontes de teste do projeto de negócio.
  6. Leia references/repository-and-ports.md antes de criar repositórios de agregados, portas do lado de leitura, portas de consulta, portas de pesquisa, modelos de leitura ou portas de manutenção.
  7. Leia references/persistence-data-converters.md antes de implementar AggregateData, DataConverter, objetos de dados MyBatis-Plus ou conversores MapStruct.
  8. Leia references/outbox-inbox.md apenas quando o projeto precisar de publicação confiável de eventos externos ou consumo idempotente de mensagens.
  9. Execute o menor comando de verificação Maven relevante, geralmente mvn test, ou um de escopo de módulo mvn -pl <modulo> test.

Regras Principais

  • Mantenha o código de domínio livre de Spring, MyBatis, modelos de persistência, clientes de barramento de mensagens e APIs de ciclo de vida do framework.
  • Modele o comportamento de negócio no domínio quando regras e invariantes forem significativos; use CRUD mais simples ou scripts de transação para áreas de baixa complexidade.
  • Para comportamento de domínio não trivial, confirme suposições de agregado, comando, invariante, evento, repositório e porta do lado de leitura antes de codificar; mantenha questões de domínio abertas visíveis.
  • Coloque starters Spring Boot apenas no módulo de montagem boot/runtime, nunca em módulos de domínio ou aplicação.
  • Coloque orquestração de casos de uso e fluxo de trabalho orientado a transações na camada de aplicação.
  • Expresse necessidades de saída como portas secundárias. Coloque MyBatis, JPA, Redis, clientes HTTP, clientes MQ e outros detalhes de tecnologia em adaptadores de infraestrutura.
  • Em projetos jfoundry Hexagonais ou Onion, adaptadores primários como controladores, listeners de mensagens, comandos CLI e agendadores devem chamar portas primárias ou serviços de aplicação, não adaptadores secundários diretamente.
  • Use repositórios de agregados para o ciclo de vida de agregados e carregamento de agregados do lado de comando. Para leituras não agregadas, prefira portas do lado de leitura e divida-as em papéis de pesquisa/modelo de leitura/manutenção apenas quando essa distinção ajudar o projeto.
  • Mantenha conversores de dados de persistência locais à infraestrutura. Prefira interfaces @Mapper do MapStruct com INSTANCE; torne toEntity(...) explícito e chame restore(...) do agregado.
  • Habilite Outbox apenas para publicação confiável para um processo ou barramento externo. Use despacho de eventos de domínio local quando os eventos permanecerem no mesmo processo.
  • Habilite Inbox apenas quando um consumidor precisar lidar com entrega duplicada com segurança.
  • Adicione testes ArchUnit no início. Eles fazem parte do esqueleto do projeto, não de uma limpeza tardia.

Templates Empacotados

Copie templates em vez de reescrevê-los de memória:

  • assets/templates/java/HexagonalArchitectureTest.java
  • assets/templates/java/OnionSimpleArchitectureTest.java
  • assets/templates/maven/dependency-management-core.xml
  • assets/templates/maven/dependency-management-spring.xml
  • assets/templates/maven/domain-module-dependencies.xml
  • assets/templates/maven/application-module-dependencies.xml
  • assets/templates/maven/infrastructure-mybatis-plus-dependencies.xml
  • assets/templates/maven/architecture-test-dependencies.xml
  • assets/templates/maven/spring-boot-app-dependencies.xml
  • assets/templates/maven/spring-boot-mybatis-plus-dependencies.xml
  • assets/templates/maven/outbox-dependencies.xml
  • assets/templates/maven/outbox-mybatis-plus-dependencies.xml
  • assets/templates/maven/inbox-dependencies.xml
  • assets/templates/maven/inbox-mybatis-plus-dependencies.xml
  • assets/templates/maven/broker-dependencies.xml
  • assets/templates/structure/hexagonal-package-structure.txt
  • assets/templates/structure/onion-simple-package-structure.txt

Substitua placeholders como PACKAGE_NAME e JFOUNDRY_VERSION. Mantenha trechos opcionais opcionais; não adicione Outbox, Inbox, MyBatis-Plus ou starters de barramento a menos que o caso de uso os exija.

Roteamento de Referências

  • Leia references/first-use.md quando o usuário estiver iniciando um novo projeto ou perguntar como invocar esta skill.
  • Leia references/architecture.md para papéis de pacotes, anotações, direção de dependência e seleção de estilo arquitetônico.
  • Leia references/dependencies.md para seleção de starters e trechos Maven.
  • Leia references/repository-and-ports.md antes de modelar persistência, repositórios de agregados, modelos de leitura ou portas de consulta.
  • Leia references/persistence-data-converters.md antes de escrever implementações de DataConverter, objetos de dados de persistência ou regras de mapeamento MapStruct.
  • Leia references/outbox-inbox.md antes de adicionar externalização de eventos, adaptadores de barramento, tabelas Outbox, despachantes ou idempotência de consumidores.
  • Leia references/testing.md antes de adicionar ou alterar testes de arquitetura.

Primeiro Prompt Comum

Ao orientar um novo projeto, comece perguntando pelo pacote base, forma do projeto/módulo, stack de runtime, escolha de persistência e se mensagens externas são necessárias. Se o usuário não tiver preferência, prossiga com:

  • Java 21
  • Maven
  • nenhum vínculo de runtime ainda
  • Arquitetura Hexagonal
  • BOM jfoundry-dependencies
  • jfoundry-domain-starter
  • jfoundry-application-starter
  • JFoundryRules.hexagonalStrict() e JFoundryRules.jmoleculesDdd()

Prompt sugerido para o usuário para um novo projeto de negócio:

Use $use-jfoundry para criar a arquitetura inicial de um novo projeto de negócio Java 21.
Pacote base: com.example.order
Forma do projeto: multi-módulo Maven
Runtime: não decidido
Persistência: MyBatis-Plus
Mensageria: Kafka depois, não no esqueleto inicial
Arquitetura: padrão, a menos que precise escolher

Se detalhes estiverem faltando, faça uma pergunta concisa ou prossiga com os padrões acima quando a escolha for de baixo risco.

Habilidades Relacionadas