Viniciustda/OiTenta / .agents/skills/module-use-case
module-use-case
UnverifiedCria casos de uso padronizados para agregados dos módulos de negócio, com contratos de entrada e saída consistentes, implementação inicial simples, testes unitários completos e estrutura pronta para evolução pelo time.
Module Use Case
Use esta skill quando o pedido for criar ou atualizar um caso de uso dentro de um modulo existente em modules/, preservando o padrao estrutural do projeto, criando os testes unitarios correspondentes e garantindo cobertura de 100% para o arquivo do caso de uso.
Esta skill nao cria controller, Prisma, adaptadores de backend, rotas HTTP ou qualquer integracao de infraestrutura. O foco aqui e somente:
- contrato de entrada e saida;
- orquestracao basica de dominio;
- dependencias explicitas do caso de uso;
- testes reais com fakes concretos;
- exports corretos;
- coverage de 100% para o caso de uso criado ou atualizado.
Entradas obrigatorias
A skill so pode prosseguir quando estas informacoes estiverem claras:
nome do moduloou umpath inequivocodentro demodules/.nome do agregadoou opath do agregado.nome do caso de uso.tipo de cenario:crudcustom
- se o caso de uso
retorna saidaounao retorna saida.
Entradas opcionais
- dependencias esperadas, como repositorios, providers ou outros contratos;
- campos da entrada;
- campos da saida, quando houver retorno;
- regras explicitas de comportamento;
- path explicito do destino final, quando o usuario quiser fugir do modo por convencao.
Se faltar informacao
Se qualquer uma destas informacoes estiver vaga, pare e peca objetivamente apenas o que falta:
- modulo ou path;
- agregado ou path;
- nome do caso de uso;
crudoucustom.- se o caso de uso retorna saida relevante ou usa
void.
Nao invente esses dados. Nao prossiga sem eles.
Leituras obrigatorias
Antes de gerar qualquer codigo, leia obrigatoriamente os arquivos abaixo nesta ordem:
modules/auth/src/user/usecase/register-user.usecase.tsmodules/auth/src/user/usecase/index.tsmodules/auth/test/user/usecase/register-user.usecase.test.tsmodules/auth/test/mock/fake-user.repository.tsmodules/auth/test/mock/fake-crypto.provider.tsmodules/auth/test/mock/index.tspackages/shared/src/usecase/use-case.tspackages/shared/src/usecase/index.ts
Depois disso, leia tambem os materiais internos desta skill:
references/mandatory-readings.mdreferences/few-shots/custom-register-user.usecase.example.tsreferences/few-shots/custom-register-user.usecase.test.example.tsreferences/few-shots/crud-find-user-by-id.usecase.example.tsreferences/few-shots/crud-find-user-by-id.usecase.test.example.tsreferences/few-shots/crud-delete-user.usecase.example.tsreferences/few-shots/crud-delete-user.usecase.test.example.ts
Os few-shots existem para reforcar o padrao de estrutura, nomes, dependencia por construtor e testes com fakes concretos.
Resolucao do destino
Esta skill aceita dois modos de resolucao:
1. Modo por convencao
Quando o usuario informar modulo e agregado por nome, use:
- caso de uso:
modules/<modulo>/src/<aggregate>/usecase/<use-case>.usecase.ts
- teste:
modules/<modulo>/test/<aggregate>/usecase/<use-case>.usecase.test.ts
2. Modo por path explicito
Quando o usuario informar paths, normalize para os destinos reais dentro do modulo:
- se vier um path do modulo, descubra
modules/<modulo>; - se vier um path do agregado, normalize para
modules/<modulo>/src/<aggregate>; - se vier um path da pasta
usecase/, grave o arquivo nela; - se vier o path final do arquivo
<nome>.usecase.ts, use-o diretamente; - o teste continua no padrao do modulo em
modules/<modulo>/test/<aggregate>/usecase/, salvo quando o proprio pedido trouxer um path explicito e valido para o teste.
Se houver ambiguidade real entre dois destinos validos, pare e peca confirmacao objetiva.
Convencoes obrigatorias
- Nome de arquivo sempre em
kebab-case. - Arquivo principal sempre com sufixo
.usecase.ts. - Arquivo de teste sempre com sufixo
.usecase.test.ts. - Nome da classe sempre em
PascalCase. - A classe nunca deve terminar com
UseCase. - Interface de entrada sempre com sufixo
In. - Interface de saida, quando existir, sempre com sufixo
Out.
Exemplo:
- arquivo:
register-user.usecase.ts - classe:
RegisterUser - entrada:
RegisterUserIn - saida:
RegisterUserOut
Fluxo deterministico
- Validar que
modules/<modulo>existe. - Resolver o agregado:
- se o usuario informou apenas o nome, usar
modules/<modulo>/src/<aggregate>; - se informou path, normalizar para a pasta real do agregado;
- se o path apontar para
usecase/ou para um arquivo dentro dela, voltar ate a raiz do agregado.
- se o usuario informou apenas o nome, usar
- Confirmar que o agregado existe antes de seguir.
- Ler o
package.jsondo modulo para descobrir o nome real do workspace de testes. - Ler o
index.tsdeusecase/do agregado, se existir. - Ler tambem o que for relevante para o caso concreto:
provider/index.ts;- contratos de repositorio ou provider usados pelo caso de uso;
model/index.tse entidades usadas;test/mock/index.ts;- fakes do modulo ja existentes.
- Procurar primeiro por fakes concretos reutilizaveis em
modules/<modulo>/test/mock/. - Criar ou atualizar o caso de uso.
- Criar ou atualizar o teste.
- Atualizar exports necessarios sem remover exports existentes.
- Rodar os testes relevantes e verificar cobertura.
- Se a cobertura do caso de uso nao for 100%, complementar os testes antes de encerrar.
Estrutura obrigatoria do caso de uso
O arquivo deve seguir o padrao do projeto:
- importar
UseCasede@poupig/sharedquando o padrao local continuar valido; - declarar
export interface <CaseName>In; - declarar
export interface <CaseName>Outapenas quando houver retorno relevante; - declarar
export class <CaseName> implements UseCase<<CaseName>In, <OutOuVoid>>; - receber dependencias pelo construtor;
- expor
async execute(input: <CaseName>In): Promise<<OutOuVoid>>.
Regras:
- quando nao houver saida relevante, use
voide omita a interfaceOut; - quando houver saida relevante, crie a interface
Outlocal e retorne esse contrato; - mantenha a implementacao simples, legivel e facil de evoluir;
- nao invente regra de negocio nao pedida;
- nao acople o caso de uso a backend, controller, Prisma ou HTTP;
- foque no contrato e na orquestracao basica de dominio.
Regras por tipo de cenario
crud
Para crud, siga uma implementacao minima e previsivel, compativel com casos como:
- criar;
- atualizar;
- excluir;
- buscar por id;
- buscar pagina.
Nesses cenarios:
- prefira dependencias simples, normalmente repositorios;
- reutilize tipos e contratos ja existentes do agregado;
- mantenha fluxo direto, sem condicoes extras desnecessarias;
- so adicione validacao extra quando o pedido trouxer essa necessidade explicitamente ou quando o padrao do modulo ja exigir.
custom
Para custom:
- monte o caso de uso com base no que o usuario descreveu;
- continue com implementacao inicial simples e pouco opinativa;
- quando houver lacunas, prefira contratos minimos e placeholders uteis em vez de inventar comportamento detalhado;
- trate dependencias externas como contratos injetados pelo construtor.
Regras para dependencias
- Procure primeiro contratos e tipos ja existentes no agregado.
- Reutilize repositorios, providers e entidades ja exportados pelo modulo.
- Nao introduza dependencia nova sem necessidade.
- Se o pedido citar dependencias esperadas, respeite isso.
- Se o caso de uso so orquestra uma chamada simples, nao crie camadas extras.
Regras dos testes unitarios
O teste do caso de uso e obrigatorio.
Destino preferencial:
modules/<modulo>/test/<aggregate>/usecase/<use-case>.usecase.test.ts
Cobertura minima obrigatoria do teste:
- caminho feliz;
- falhas de validacao, quando existirem;
- dependencias chamadas ou nao chamadas conforme o fluxo;
- todos os branches e condicionais existentes;
- retorno esperado, quando houver saida;
- comportamento quando erro e propagado ou tratado;
- ausencia de efeitos colaterais quando o fluxo falhar antes do ponto critico.
Regras de qualidade:
- use implementacoes fake reais e concretas, nao mocks de framework como estrategia principal;
- priorize fakes existentes do modulo antes de criar novas;
- se existir fake adequada, reutilize-a e nao duplique;
- se nao existir fake adequada para uma dependencia essencial, crie uma fake simples e reutilizavel em
modules/<modulo>/test/mock/; - ao criar nova fake, exporte-a tambem em
modules/<modulo>/test/mock/index.ts; - use spies apenas como apoio pontual sobre classes concretas ou prototipos, como no exemplo de
User.prototype.validate; - escreva testes reais e uteis, nao superficiais.
Reuso de fakes
Antes de criar uma fake nova, procure por:
modules/<modulo>/test/mock/fake-<aggregate>.repository.ts- outros
fake-*.tsemmodules/<modulo>/test/mock/ - exports existentes em
modules/<modulo>/test/mock/index.ts
Se uma fake cobrir a dependencia:
- reutilize a classe existente;
- adapte o teste ao contrato dela;
- evite duplicacao com outro nome.
Se uma fake nao existir e for essencial:
- crie uma classe concreta simples;
- mantenha armazenamento em memoria ou comportamento previsivel;
- evite
jest.fn()como estrutura principal da fake; - deixe a fake pronta para ser reutilizada por outros testes do modulo.
Exports e integracao
Ao concluir, garanta pelo menos:
- criacao ou atualizacao de
modules/<modulo>/src/<aggregate>/usecase/<use-case>.usecase.ts - criacao ou atualizacao de
modules/<modulo>/src/<aggregate>/usecase/index.ts
Se necessario, atualize tambem o minimo indispensavel para manter a acessibilidade pelo padrao do modulo:
- barrel do agregado;
- barrel do modulo;
modules/<modulo>/test/mock/index.ts, quando houver fake nova.
Preserve todos os exports existentes.
Verificacao obrigatoria
Rode a verificacao a partir da raiz do monorepo:
MODULE_PKG=$(node -p "require('./modules/<modulo>/package.json').name")
npm run test --workspace "$MODULE_PKG" -- --runInBand --runTestsByPath "modules/<modulo>/test/<aggregate>/usecase/<use-case>.usecase.test.ts"
npm run test --workspace "$MODULE_PKG" -- --runInBand --coverage --collectCoverageFrom="src/<aggregate>/usecase/<use-case>.usecase.ts" --runTestsByPath "modules/<modulo>/test/<aggregate>/usecase/<use-case>.usecase.test.ts"
Se uma fake nova foi criada ou alterada e ela tiver logica propria com branch observavel, rode tambem os testes que a exercitam.
Nao encerre a tarefa enquanto:
- o caso de uso nao compilar no contexto do modulo;
- o teste nao existir;
- os exports nao estiverem corretos;
- a cobertura observavel do caso de uso nao atingir 100%.
Entrega minima esperada
Ao aplicar esta skill corretamente, o resultado minimo deve incluir:
- o arquivo do caso de uso;
- o teste unitario correspondente;
- o
index.tsdeusecase/atualizado; - atualizacao de
test/mock/index.ts, se houver fake nova; - validacao real dos testes e da cobertura.
Restricoes
- Nao criar controller.
- Nao criar Prisma.
- Nao criar adapter de backend.
- Nao adicionar complexidade desnecessaria.
- Nao inventar regras de negocio nao pedidas.
- Nao pular a leitura obrigatoria.
- Nao alterar arquivos fora do modulo alvo e da propria skill alem do estritamente necessario para integrar o caso de uso.
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 |