Zoha/agent-skills

Estrutura NestJS GraphQL

Onde cada arquivo pertence em uma aplicação NestJS GraphQL (code-first) e como cada arquivo funciona. Esta skill é um guia de posicionamento e anatomia: ela responde "em qual pasta este arquivo vai?", "do que este arquivo é responsável?" e "como os módulos se conectam para resolver campos e relações?". Abrange o mapa da estrutura base, além de regras por arquivo para módulos, serviços, resolvedores (query, mutation, subscription e field), inputs e args, paginação, entidades (boas práticas de schema Mongoose para tipos compartilhados), injeção de modelo restrita a repositórios, models/mappers, repositórios, discriminadores Mongoose, campos derivados, providers, loaders, eventos, jobs em background, autenticação, exceções, escalares customizados, configuração, blocos comuns de construção, configuração de infraestrutura e convenções de nomenclatura/testes/lint.

Ela é deliberadamente separada da skill nestjs-best-practices. Essa skill cobre comportamento do framework (profundidade de injeção de dependência, segurança, desempenho, tratamento de erros, microsserviços, DevOps); esta cobre estrutura e composição de módulos. Onde elas se sobrepõem (módulos de recurso, dependências circulares), esta skill examina através de uma lente de posicionamento e faz referência cruzada à outra skill para profundidade comportamental.

Esta skill cobre ambas as regras de estrutura (onde um arquivo vive) e regras de resolução de módulos (como os módulos se conectam em tempo de execução — por exemplo, resolução de dependência circular). As regras de resolução de módulos estão nas Seções 2 e 3.

Quando Aplicar

Consulte estas diretrizes quando:

• Decidir onde um novo arquivo pertence em uma base de código NestJS GraphQL
• Projetar ou revisar um layout de diretório orientado a recursos
• Criar um novo módulo de recurso e seus arquivos
• Decidir como modelar documentos polimórficos (discriminadores Mongoose) e publicar seu tipo GraphQL automaticamente
• Decidir onde um modelo Mongoose pode ser injetado — e manter o acesso ao banco de dados atrás de um repositório
• Decidir se um valor pertence ao banco de dados ou deve ser derivado quando lido
• Descobrir como um módulo resolve um campo ou relação que vive em outro módulo
• Resolver problemas de conexão entre módulos (dependências circulares, exportações ausentes)

Categorias de Regras por Prioridade

Prioridade	Categoria	Impacto	Prefixo
1	Estrutura da Aplicação	CRÍTICO	struct-
2	Módulos & Bootstrap	CRÍTICO	module-
3	Relações & Entre Módulos	CRÍTICO	relations-
4	Serviços	ALTO	service-
5	Resolvedores GraphQL	ALTO	resolver-
6	Tipos & Inputs GraphQL	ALTO	type-
7	Acesso a Dados	MÉDIO-ALTO	data-
8	Config, Comum & Infra	MÉDIO	infra-
9	Convenções & Testes	MÉDIO	conventions-

Referência Rápida

1. Estrutura da Aplicação (CRÍTICO)

• struct-auth-feature - Manter Autenticação em Seu Próprio Módulo de Recurso
• struct-canonical-layout - Estrutura Canônica da Aplicação
• struct-feature-decomposition - Dividir um Recurso em Submódulos Quando Crescer
• struct-file-placement-table - Tabela de Posicionamento de Arquivos
• struct-module-kinds - Distinguir Recursos de Domínio de Módulos de Nível de Aplicação
• struct-schema-artifact - Localizar e Política do Artefato de Schema Gerado

2. Módulos & Bootstrap (CRÍTICO)

• module-bootstrap - Manter main.ts e app.module.ts Enxutos
• module-export-policy - Exportar Apenas a API Pública do Recurso (Seus Serviços)
• module-feature-module - O Arquivo do Módulo de Recurso

3. Relações & Entre Módulos (CRÍTICO)

• relations-avoid-circular - Resolver Dependências Circulares de Módulos
• relations-dataloader - Agrupar Relações com um DataLoader por Requisição
• relations-events - Desacoplar Módulos com Eventos
• relations-field-resolvers - Resolver Relações com @ResolveField
• relations-owning-module - Colocar um Campo de Relação no Módulo Que Possui Seus Dados

4. Serviços (ALTO)

• service-background-jobs - Manter Processadores de Fila e Jobs Agendados com o Recurso
• service-external-providers - Manter Clientes de Terceiros em providers/
• service-interfaces-tokens - Declarar Contratos de Serviço e Tokens de Injeção em interfaces/
• service-single-responsibility - Vários Serviços Focados por Módulo
• service-small-focused-methods - Manter Métodos de Serviço Pequenos e Focados

5. Resolvedores GraphQL (ALTO)

• resolver-computed-fields - Declarar Campos no Tipo; Resolver os Computados no Resolvedor
• resolver-organization - Dividir Resolvedores por Papel em resolvers/
• resolver-per-type - Um Arquivo de Resolvedor por Tipo Que Tenha Resolvedores de Campo
• resolver-subscriptions - Colocar Resolvedores de Subscription em resolvers/ com PubSub em infra/

6. Tipos & Inputs GraphQL (ALTO)

• type-args - Definir Classes @Args em dto/
• type-inputs - Definir Inputs GraphQL em dto/
• type-pagination - Paginar Consultas de Lista com um Tipo de Página Compartilhado
• type-polymorphic-discriminators - Publicar Documentos Discriminados como uma Interface ou Union
• type-unions-interfaces - Colocar Tipos Union e Interface com os Tipos do Módulo

7. Acesso a Dados (MÉDIO-ALTO)

• data-derived-fields - Calcular Campos Derivados; Não Armazená-los
• data-discriminators - Modelar Subtipos Polimórficos com Discriminadores
• data-entity-mongodb - Colocar Entidades MongoDB em entities/
• data-model-injection - Injetar um Modelo Apenas no Repositório
• data-models-mappers - Separar models/ e mappers/ Quando a API Diferir do Armazenamento
• data-mongoose-schema - Boas Práticas de Schema Mongoose para Tipos Compartilhados
• data-repository - Manter Acesso a Dados em repositories/

8. Config, Comum & Infra (MÉDIO)

• infra-common-types - Colocar Tipos Compartilhados em common/types/
• infra-common - Colocar Blocos Comuns de Construção em common/
• infra-config - Colocar Configuração Tipada em config/
• infra-custom-scalars - Implementar Escalares Customizados em common/scalars/
• infra-database - Colocar Configuração do Banco de Dados e Migrações em infra/database/
• infra-directives - Colocar Diretivas de Schema em common/directives/
• infra-exceptions - Colocar Exceções em exceptions/
• infra-graphql - Colocar Configuração GraphQL em infra/graphql/
• infra-seeds - Colocar Scripts de Seed em infra/database/seeds/
• infra-shared-module - Usar um SharedModule para Serviços Transversais

9. Convenções & Testes (MÉDIO)

• conventions-barrels-aliases - Usar Barrels e Apelidos de Caminho Deliberadamente
• conventions-cli-generator - Usar o Gerador CLI do Nest, Depois Ajustar
• conventions-constants-enums - Manter Constantes e Enums Fora de Arquivos de Classe
• conventions-module-boundaries - Impor Limites de Módulos com Lint
• conventions-naming - Convenções de Nomenclatura de Arquivos e Classes
• conventions-test-fixtures - Colocar Fixtures de Teste, Fábricas e Helpers em test/
• conventions-testing - Posicionamento de Arquivos de Teste

Como Usar

Comece com a regra de estrutura base, depois leia a regra para o tipo específico de arquivo que você está criando. Os arquivos de regra ficam em rules/:

rules/struct-canonical-layout.md
rules/_sections.md

Cada arquivo de regra contém:

• Propósito e posicionamento (onde o arquivo vive e como é nomeado)
• Responsabilidades e anti-responsabilidades
• Um exemplo incorreto com explicação
• Um exemplo correto com explicação

Documento Compilado Completo

Para o guia completo com todas as regras expandidas em um único documento, veja AGENTS.md.