.agent/rules/typescript-sem-any.md

type	name	trigger	description	scope	updatedAt	globs	alwaysApply
rule	typescript-sem-any	always_on	Proíbe uso de any, casts inseguros e padroniza uso de enums em código TypeScript	global	2026-06-01	**/*.ts, **/*.tsx, **/*.vue	true

Regras obrigatórias para TypeScript neste projeto:

• Nunca usar any.
• Nunca usar as any.
• Nunca contornar erro de tipagem com cast forçado.
• Quando o tipo não for conhecido, usar unknown.
• Antes de acessar valores unknown, fazer narrowing com:
  • typeof
  • in
  • Array.isArray
  • type guards
  • schemas de validação como Zod
• Preferir:
  • generics
  • union types
  • Record<string, unknown>
  • Partial<T>
  • Pick<T, K>
  • PropType<T> em Vue
  • tipos derivados de funções existentes
• Se faltar tipo, o agente deve:
  1. procurar tipos já existentes no projeto;
  2. criar um tipo/interface local explícita;
  3. inferir a partir do contexto sempre que possível;
  4. deixar um TODO de tipagem explícito, mas sem usar any.

Regras Inegociáveis para Uso de Enums e zEnums

🚨 REGRA DE OURO: SE EXISTE ENUM OU zENUM DISPONÍVEL (EM QUALQUER MÓDULO OU APLICAÇÃO), O USO DO ENUM É 100% OBRIGATÓRIO — SEM NENHUMA EXCEÇÃO.

1. Proibição Universal de Strings Literais (Magic Strings):

   • É estritamente proibido utilizar strings literais no lugar de qualquer enum ou zEnum existente no sistema (seja para tabelas, colunas, status, tipos, categorias, eventos, ações, etc.).
   • É proibido utilizar casts para forçar compatibilidade com tipos de domínio (ex: "ativo" as StatusConta ou "pontos" as TipoNomeTabela).

2. Padrão Canônico de Acesso:

   • Enums TypeScript nativos: <NomeEnum>.VALOR (ex: CategoriasSuporte.ADMIN, TipoProcessamento.BATCH).
   • Enums Zod / Objetos derivados: <zSchema>.enum.VALOR ou <enumDerivado>.<membro> (ex: enumTabelas.pontos, enumColunas.codigo, zStatus.enum.ativo, zTipoPessoa.enum.fisica).

3. Operações em Todas as Camadas (Banco, Filas, APIs e Frontend):

   • Banco de dados & Queries: Nomes de tabelas, entidades e colunas DEVEM consumir os enums correspondentes do pacote *-comuns (nunca strings hardcoded em queries de banco).
   • Regras de Negócio & Lógica: Comparações condicionais, transições de estado, status e categorias DEVEM usar os membros do enum.
   • Frontend & Telas: Filtros, selects, badges e renderizações condicionais DEVEM importar e referenciar os enums canônicos.

4. Diretriz de Busca Prévia Obrigatória: Antes de escrever qualquer string que represente conceito de domínio, entidade, tabela, coluna, status ou opção, o agente DEVE:

   1. Inspecionar o pacote *-comuns (src/enums/, src/tabelas/, src/tipos/) da respectiva aplicação;
   2. Se existir qualquer enum correspondente, é obrigatório utilizar o enum existente;
   3. Se não existir, propor/criar o enum ou z.enum no *-comuns em vez de espalhar strings literais.

---

Referências

• Skill: global/skills/diagnosticar-erros-build/SKILL (quando erros de tipagem causam falhas de build em cascata)
• Workflow: global/workflows/codigo-limpo (ou global/workflows/otimizar-codigos)