aprimoração de ia

rules/typescript-sem-any.md

@@ -0,0 +1,77 @@
+---
+type: rule
+name: typescript-sem-any
+trigger: always_on
+description: Proíbe uso de any, casts inseguros e padroniza uso de enums em código TypeScript
+scope: global
+updatedAt: "2026-06-01"
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.vue"
+alwaysApply: 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 obrigatórias para uso de enums:
+
+- Quando um valor estiver associado a um `enum`, é obrigatório utilizar o enum, nunca strings literais.
+- O acesso deve seguir o padrão: `<NomeEnum>.VALOR`.
+
+Também é proibido, quando existir `enum` correspondente:
+
+- utilizar strings literais no lugar do enum (ex: `"ativo"`, `"inativo"`, `"automatica"`, `"criar"`);
+- utilizar cast para forçar compatibilidade com enum (ex: `"ativo" as StatusConta`).
+
+Proibido gerar código que apenas "faça compilar" usando:
+
+- `as any`
+- `: any`
+- `[] as any`
+- `{ } as any`
+- dupla coerção como `as unknown as any`
+
+Em casos excepcionais, preferir:
+
+- `as unknown as TipoEspecifico` somente se houver justificativa clara e comentário técnico.
+
+Diretriz para o agente:
+
+Se encontrar uma string que represente um valor de domínio do sistema, o agente deve:
+
+1. procurar se já existe um `enum` correspondente no projeto;
+2. usar o `enum` existente;
+3. se não existir, propor a criação de um `enum` explícito, em vez de manter strings soltas.
+
+---
+
+## Referências
+
+- Skill: `global/skills/diagnosticar-erros-build/SKILL` (quando erros de tipagem causam falhas de build em cascata)
+- Workflow: `global/workflows/otimizar-codigos` (padrão de documentação para casts temporários)
+