Viniciustda/OiTenta / .agents/skills/shared-validation-rule
shared-validation-rule
UnverifiedCria regras de validação reutilizáveis no pacote compartilhado da aplicação, seguindo o padrão existente de contratos, utilitários, códigos de erro, exports e testes unitários completos.
Shared Validation Rule
Use esta skill quando o pedido for criar ou atualizar uma regra reutilizavel em packages/shared/src/validation/rules.
Objetivo
- Criar novas regras de validacao reutilizaveis dentro de
packages/shared. - Seguir exatamente o padrao estrutural, semantico e de testes ja adotado no projeto.
- Reaproveitar
packages/shared/src/validation/rule.utils.tssempre que fizer sentido. - Criar testes unitarios robustos e curtos, focados no contrato observavel da regra.
- Garantir integracao correta com os exports do pacote shared.
- Entregar uma regra simples, previsivel, reutilizavel e facil de manter.
Entradas obrigatorias
So execute a implementacao quando estas entradas estiverem claras no pedido ou puderem ser inferidas com baixo risco:
- Nome da regra a ser criada.
- Objetivo da validacao.
- Tipo principal do valor validado:
string,number,date,arrayoumixed. - Codigo de erro esperado quando a regra falhar.
Entradas opcionais
- Parametros da regra, quando houver: minimo, maximo, lista de valores, regex, configuracoes de comportamento.
- Exemplos de valores validos e invalidos.
- Se a regra deve ignorar valores vazios ou trata-los como invalidos.
Leitura obrigatoria
Antes de criar a regra, leia obrigatoriamente os arquivos abaixo, nesta ordem:
packages/shared/src/validation/validation-rule.interface.tspackages/shared/src/validation/validation-field.interface.tspackages/shared/src/validation/validator.tspackages/shared/src/validation/rule.utils.tspackages/shared/src/validation/index.tspackages/shared/src/validation/rules/index.ts- Regras de referencia:
packages/shared/src/validation/rules/required.rule.tspackages/shared/src/validation/rules/email.rule.tspackages/shared/src/validation/rules/min-length.rule.tspackages/shared/src/validation/rules/range-length.rule.tspackages/shared/src/validation/rules/strong-password.rule.tspackages/shared/src/validation/rules/person-name.rule.ts
- Testes de referencia:
packages/shared/test/validation/rules/required.rule.test.tspackages/shared/test/validation/rules/email.rule.test.tspackages/shared/test/validation/rules/min-length.rule.test.tspackages/shared/test/validation/rules/range-length.rule.test.tspackages/shared/test/validation/rules/security-rules.test.tspackages/shared/test/validation/rules/string-rules.test.ts
Se a nova regra exigir utilitario novo ou alterar comportamento utilitario, leia e atualize tambem:
packages/shared/test/validation/rule.utils.test.tspackages/shared/test/validation/validator.test.tsquando a integracao comValidator.validate(...)precisar de cobertura adicionalpackages/shared/src/index.tsquando houver duvida sobre a cadeia final de exports do pacote
Consulte tambem references/mandatory-readings.md e os few-shots locais desta skill antes de escrever codigo novo.
Few-shots internos
Os few-shots desta skill ficam em references/few-shots/ e devem ser usados como referencia pratica imediata:
required.rule.example.tsrequired.rule.test.example.tsemail.rule.example.tsemail.rule.test.example.tsmin-length.rule.example.tsmin-length.rule.test.example.tsrange-length.rule.example.tsrange-length.rule.test.example.tsstrong-password.rule.example.tsstrong-password.rule.test.example.ts
Eles existem para mostrar o padrao real de implementacao e teste sem depender de arquivos externos para o papel didatico.
Fluxo deterministico
- Normalizar o nome da regra em
kebab-casepara o arquivo e em PascalCase com sufixoRulepara a classe. - Ler todas as referencias obrigatorias do projeto.
- Ler os few-shots internos mais proximos do caso.
- Definir o contrato da regra:
- implementar
ValidationRule; - expor
validate(value: unknown): string | null; - retornar
nullquando valido; - retornar apenas o sufixo do erro quando invalido;
- nunca montar
<field.code>.<errorCode>dentro da regra; - nunca lancar excecao diretamente;
- nunca criar efeitos colaterais.
- implementar
- Decidir o comportamento para valores vazios:
- por padrao, regras opcionais ignoram vazio e retornam
null; - deixe obrigatoriedade para
RequiredRule; - so trate vazio como invalido quando isso vier explicitamente do pedido e for coerente com o padrao existente.
- por padrao, regras opcionais ignoram vazio e retornam
- Reaproveitar utilitarios existentes antes de criar logica propria:
validateStringValuesvalidateNumberValuesvalidateDateValuesvalidateEachValueisEmptyValuegetValueLengthtoValidDatetestPattern
- So criar nova funcao em
rule.utils.tsquando ela for claramente generica e reutilizavel por outras regras. - Implementar a regra em
packages/shared/src/validation/rules/<rule-name>.rule.ts. - Atualizar
packages/shared/src/validation/rules/index.ts. - Verificar se os exports agregados continuam acessiveis por:
packages/shared/src/validation/index.tspackages/shared/src/index.ts- preservar exports existentes e adicionar apenas o necessario
- Criar ou atualizar
packages/shared/test/validation/rules/<rule-name>.rule.test.ts. - Se houver utilitario novo, criar ou atualizar os testes dele em
packages/shared/test/validation/rule.utils.test.ts. - Rodar os testes relevantes do pacote shared e complementar cobertura ate a nova regra atingir 100%.
Regras de implementacao
- O arquivo da regra deve ser sempre
packages/shared/src/validation/rules/<rule-name>.rule.ts. - O nome do arquivo deve ser sempre em
kebab-case. - O nome da classe deve ser em PascalCase com sufixo
Rule. - Toda regra deve implementar
ValidationRule. - O metodo deve seguir exatamente
validate(value: unknown): string | null. - A regra deve retornar apenas o sufixo do erro, por exemplo:
requiredinvalid.emailmin.lengthrange.lengthstrong.passwordperson.name
- O
Validatore quem monta o erro completo no formato<field.code>.<errorCode>. - Nao duplicar logica ja existente em
rule.utils.ts. - Manter a implementacao curta, previsivel e legivel.
- Quando a regra aceitar parametros, recebe-los por construtor, no mesmo estilo das regras existentes.
- Quando a regra validar colecoes ou multiplos valores, seguir o estilo das regras atuais baseadas em
validateEachValuee derivados.
Regras para os testes
- O teste da regra deve viver em
packages/shared/test/validation/rules/<rule-name>.rule.test.ts. - Seguir o estilo do projeto:
- imports a partir de
../../../src/index; describe("<ClassName>Rule", ...);- testes curtos, claros e orientados ao contrato;
- evitar indirecao desnecessaria.
- imports a partir de
- Cobrir, no minimo:
- cenario valido;
- cenario invalido;
- comportamento com valores vazios, quando aplicavel;
- comportamento com tipos invalidos, quando aplicavel;
- comportamento dos parametros, quando existirem;
- cenarios limite relevantes.
- Se a regra reutilizar utilitario com branches relevantes, testar o comportamento observavel da regra sem duplicar teste do utilitario alem do necessario.
- Se houver nova funcao utilitaria, criar testes diretos para ela em
packages/shared/test/validation/rule.utils.test.ts. - Se o usuario fornecer exemplos de valores validos e invalidos, reproduzir esses exemplos nos testes sempre que fizer sentido.
- A cobertura esperada para a nova regra e 100%.
Verificacao
Rodar a verificacao a partir da raiz do monorepo:
SHARED_PKG=$(node -p "require('./packages/shared/package.json').name")
npm run test --workspace "$SHARED_PKG" -- --runInBand --runTestsByPath "packages/shared/test/validation/rules/<rule-name>.rule.test.ts"
npm run test --workspace "$SHARED_PKG" -- --runInBand
Se houve alteracao em rule.utils.ts, validar tambem:
SHARED_PKG=$(node -p "require('./packages/shared/package.json').name")
npm run test --workspace "$SHARED_PKG" -- --runInBand --runTestsByPath "packages/shared/test/validation/rule.utils.test.ts"
Nao encerrar a tarefa enquanto:
- a regra nao estiver exportada corretamente;
- o teste da regra nao existir;
- a cobertura observavel da nova regra nao estiver completa;
- o comportamento nao estiver coerente com
Validator.validate(...).
Saida esperada
Ao concluir uma implementacao baseada nesta skill, o resultado minimo deve incluir:
packages/shared/src/validation/rules/<rule-name>.rule.ts- atualizacao de
packages/shared/src/validation/rules/index.ts - teste em
packages/shared/test/validation/rules/<rule-name>.rule.test.ts - atualizacoes adicionais em exports agregados apenas se realmente necessarias
- atualizacao de
rule.utils.tserule.utils.test.tssomente quando surgir um helper novo e claramente reutilizavel
Restricoes
- Esta skill nao cria entidades, casos de uso ou controllers.
- Esta skill existe apenas para criar regras reutilizaveis no pacote shared.
- Nao inventar um padrao novo se o projeto ja possui um.
- Nao criar documentacao extra fora desta pasta de skill.
- Nao pular a leitura das referencias obrigatorias.
- Nao alterar regras, exports ou testes nao relacionados alem do necessario para integrar a nova regra.
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 |