Viniciustda/OiTenta / .agents/skills/module-entity
module-entity
UnverifiedCria entidades de domínio padronizadas para os módulos da aplicação, com estado tipado, herança da entidade base, validação explícita orientada por regras reutilizáveis do projeto e testes unitários completos para garantir segurança de evolução.
Module Entity
Use esta skill quando o pedido for criar ou completar uma entidade de dominio dentro de um modulo existente em modules/, junto com o teste unitario da entidade e a verificacao de coverage.
Esta skill nao cria controller, repositorio Prisma, migration, seed ou adaptacoes do backend. O foco aqui e somente:
- entidade de dominio
- validacao explicita e lazy
- reaproveitamento de regras compartilhadas
- testes unitarios fortes
- coverage de 100% para a entidade criada ou alterada
Entradas obrigatorias
nome do modulonome do agregadooupath do agregadonome da entidadelista de atributos com tipos
Entrada opcional:
regras explicitas por campo, quando o usuario quiser forcar alguma validacao
Referencias obrigatorias
Antes de gerar qualquer codigo, ler obrigatoriamente:
modules/auth/src/user/model/user.entity.tsmodules/auth/test/user/model/user.entity.test.tspackages/shared/src/validation/rules/packages/shared/src/validation/index.tspackages/shared/src/validation/validator.tspackages/shared/src/model/entity.ts
Tambem leia as referencias internas desta skill para acelerar a reproducao estrutural:
references/user-entity-pattern.mdreferences/validation-inference-guide.md
Validacoes iniciais
- Validar que
modules/<modulo>existe. - Resolver o agregado:
- Se o usuario informar apenas o nome, usar
modules/<modulo>/src/<aggregate>. - Se o usuario informar um path, ele deve apontar para um agregado real dentro de
modules/<modulo>/src/.
- Se o usuario informar apenas o nome, usar
- Se o path informado apontar para
model/ou para um arquivo dentro do agregado, normalizar para a pasta do agregado. - Se o agregado nao existir, parar e pedir o agregado correto.
- Nao inferir multiplos destinos. Se houver ambiguidade real entre dois caminhos validos, parar e pedir confirmacao.
- Ler
modules/<modulo>/package.jsonpara descobrir o nome real do workspace antes de rodar os testes.
Destinos obrigatorios
- Entidade:
modules/<modulo>/src/<aggregate>/model/<entity>.entity.ts
- Teste:
modules/<modulo>/test/<aggregate>/model/<entity>.entity.test.ts
Convencoes obrigatorias:
- Nome do arquivo em
kebab-case - Interface de estado em
PascalCasecom sufixoState - Classe em
PascalCase
Exemplo:
- arquivo:
customer.entity.ts - interface:
CustomerState - classe:
Customer
Estrutura obrigatoria da entidade
Seguir exatamente o padrao do projeto:
export interface <EntityName>State extends EntityStateexport class <EntityName> extends Entity<<EntityName>State>- Construtor apenas repassa
propsparasuper(props) - Getters explicitos para todos os campos informados
validate()comValidator.validate([...])
Formato esperado:
export interface ExampleEntityState extends EntityState {
field: string;
}
export class ExampleEntity extends Entity<ExampleEntityState> {
constructor(props: ExampleEntityState) {
super(props);
}
get field(): string {
return this.props.field;
}
public validate(): void {
Validator.validate([
{
code: "exampleEntity.field",
value: this.field,
rules: [new RequiredRule()],
},
]);
}
}
Regra central de validacao
- Nao fazer validacao eager no construtor.
- Nao chamar
validate()dentro do construtor. - A entidade pode existir temporariamente invalida.
- Isso e intencional e obrigatorio.
- A unica validacao automatica aceita e a da classe base
Entity, que validaide timestamps. - Toda regra de negocio da propria entidade deve ficar dentro de
validate().
Heuristica de inferencia de validacao
A skill deve inferir o melhor conjunto possivel de regras com base em:
- nome do campo
- tipo do campo
- padrao observado nas regras existentes
- exemplo real em
User - regras explicitas fornecidas pelo usuario
Prioridades:
- Regra explicita do usuario
- Regra compartilhada ja existente em
packages/shared/src/validation/rules - Nova regra compartilhada, somente se ela for claramente generica e reutilizavel
Nunca:
- deixar campo relevante sem protecao por omissao
- criar regra local dentro da entidade quando ja existir regra compartilhada adequada
- criar regra compartilhada para comportamento hiper especifico de uma unica entidade
Regras sugeridas por tipo e semantica
Use as regras compartilhadas existentes sempre que fizer sentido:
stringobrigatoria:RequiredRule
- nomes pessoais:
RequiredRuleMinLengthRuleMaxLengthRulePersonNameRule
- email:
RequiredRuleEmailRule
- slug:
RequiredRuleSlugRule
- url:
RequiredRuleUrlRule
- dominio:
RequiredRuleDomainRule
- senha em hash:
BcryptHashRule
- senha em texto puro:
RequiredRuleStrongPasswordRuleNoCommonPasswordRule
- UUID em campo de referencia:
RequiredRuleUuidRule
- numero inteiro:
RequiredRuleIntegerRule
- numero positivo:
PositiveRule
- numero negativo:
NegativeRule
- limite numerico:
MinValueRuleMaxValueRuleRangeValueRule
Date:RequiredRuleDateRule
- data passada ou futura:
PastDateRuleFutureDateRule
- arrays:
RequiredRulequando o campo nao puder faltarMinItemsRuleMaxItemsRuleUniqueItemsRule
- strings sem espacos ou com formato especial:
NoWhitespaceRuleRegexRuleAlphaRuleAlphaNumericRuleStartsWithRuleEndsWithRuleContainsRule
Convencao de codigos de erro
- Usar prefixo semanticamente estavel em minusculo.
- Seguir o padrao observado em
user.entity.ts. - Preferir
<aggregate>.<campo>quando a entidade representar o agregado principal. - Para entidades filhas, usar um prefixo claro e consistente, por exemplo
<entity>.<campo>. - Manter o mesmo prefixo em todos os campos da entidade.
Criacao de nova regra compartilhada
Se nao existir regra compartilhada suficiente para um caso recorrente e generico:
- Criar a nova regra em
packages/shared/src/validation/rules/<rule>.rule.ts - Exportar em
packages/shared/src/validation/rules/index.ts - Confirmar que
packages/shared/src/validation/index.tsja a expoe viaexport * from "./rules" - Criar ou atualizar o teste da nova regra em
packages/shared/test/validation/rules/ - Usar a regra nova na entidade
Essa regra nova so deve existir quando o comportamento for claramente reaproveitavel por outros modulos.
Atualizacao de barrels
Para reduzir ajuste manual posterior, manter os exports coerentes com o padrao local:
- Se existir
modules/<modulo>/src/<aggregate>/model/index.ts, exportar a nova entidade nele. - Se nao existir esse arquivo e o agregado ja possuir outras entidades ou model, criar
model/index.ts. - Se
modules/<modulo>/src/index.tsja exportar./<aggregate>/model, preservar o padrao. - Se o modulo usar um barrel mais amplo por agregado, atualizar somente o minimo necessario para a entidade ficar acessivel pelo padrao ja adotado no proprio modulo.
Nao inventar reorganizacao estrutural.
Regras dos testes unitarios
O teste da entidade deve buscar cobertura de 100% para o arquivo da entidade.
Cobertura minima obrigatoria:
- criacao de entidade valida
- leitura correta de todos os getters
- comportamento lazy, garantindo que a entidade possa existir invalida antes do
validate() - sucesso de
validate()para dados validos - falha de
validate()para dados invalidos - mensagens ou codigos de erro esperados quando fizer sentido
- cenarios limite das regras aplicadas
- comportamento herdado relevante da classe base, quando fizer parte da superficie observavel
- branches internos de
validate() - fluxos de
clone,deletedAt,createdAteupdatedAt, quando a entidade os expuser de forma observavel
Regras de qualidade do teste:
- seguir o estilo de
modules/auth/test/user/model/user.entity.test.ts - criar helper para extrair mensagens de
ValidationExceptionquando isso simplificar assercoes - evitar teste superficial que apenas instancia a classe sem verificar comportamento
- testar especialmente as combinacoes que podem deixar branch sem cobertura
- se a entidade tiver apenas getters e um
validate()linear, ainda assim cobrir sucesso, falha e limites de cada regra importante
Workflow recomendado
- Validar modulo, agregado e destino.
- Ler as referencias obrigatorias.
- Identificar regras compartilhadas ja existentes para cada campo.
- Decidir o prefixo dos codigos de validacao.
- Criar ou atualizar a entidade.
- Criar ou atualizar o teste da entidade.
- Atualizar barrels minimos do agregado, se necessario.
- Se houver nova regra compartilhada, criar a regra e o teste dela antes de validar a entidade.
- Rodar testes com coverage mirando a entidade.
- Se coverage da entidade ficar abaixo de 100%, ajustar os testes e rodar novamente.
Comandos de verificacao
Preferir executar a partir da raiz do projeto.
Para o modulo afetado:
npm run test --workspace <workspace-name-lido-do-package-json> -- --runTestsByPath test/<aggregate>/model/<entity>.entity.test.ts --collectCoverageFrom=src/<aggregate>/model/<entity>.entity.ts
Se a implementacao criar nova regra compartilhada:
npm run test --workspace <workspace-name-do-shared> -- --runTestsByPath test/validation/rules/<rule>.test.ts --collectCoverageFrom=src/validation/rules/<rule>.rule.ts
Quando fizer sentido, rodar tambem a suite completa do modulo:
npm run test --workspace @poupig/<modulo>
Objetivo obrigatorio:
- cobertura de 100% para a entidade criada ou alterada
- quando houver nova regra compartilhada, cobertura de 100% tambem para essa regra
Guardrails
- Nao criar controller, repository, migration, seed ou adaptacoes de backend.
- Nao mudar o padrao da entidade base do projeto.
- Nao colocar logica de negocio fora de
validate()sem necessidade estrutural real. - Nao disparar
validate()no construtor. - Nao ignorar
clone, timestamps oudeletedAtquando eles forem relevantes para a superficie observavel. - Nao usar regra ad hoc local se existe regra compartilhada equivalente.
- Nao parar cedo com coverage parcial; ajustar os testes ate cobrir completamente a entidade.
Saida esperada
- entidade criada ou atualizada em
modules/<modulo>/src/<aggregate>/model/<entity>.entity.ts - teste criado ou atualizado em
modules/<modulo>/test/<aggregate>/model/<entity>.entity.test.ts - barrels minimos ajustados quando necessario
- nova regra compartilhada criada apenas se realmente generica
- validacao final executada com coverage
Few-shot
Para reproduzir o padrao estrutural rapidamente:
- ver
references/user-entity-pattern.md - ver
references/validation-inference-guide.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |