melhorias na ia

rules/jsdoc-padrao.global.md

@@ -0,0 +1,59 @@
+---
+type: rule
+name: jsdoc-padrao
+description: Padrões de documentação em código (JSDoc, casts temporários e TODOs estruturados)
+scope: global
+trigger: file_match
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.vue"
+updatedAt: "2026-06-01"
+---
+
+# Regra: Documentação em Código
+
+## 1. JSDoc — Princípios
+
+- **Por que, não o Quê**: documente o raciocínio, não o mecanismo que o TypeScript já expressa.
+- **Nomenclatura limpa**: confie em nomes expressivos antes de comentários.
+
+## 2. JSDoc obrigatório em funções compartilhadas
+
+Toda função central ou de uso compartilhado deve ter cabeçalho JSDoc:
+
+```typescript
+/**
+ * Busca detalhes da entidade e calcula privilégios aplicáveis.
+ * Não utilizar em processamento em lote para evitar sobrecarga.
+ *
+ * @param tenantId  - Identificador do tenant no sistema
+ * @param entityId  - ID do registro na base de dados
+ * @returns Objeto consolidado ou `null` se não encontrado
+ */
+export const obterDetalhes = async (tenantId: string, entityId: string) => { ... }
+```
+
+## 3. Casts temporários — justificativa obrigatória
+
+Coerções agressivas requerem comentário explicando o porquê:
+
+```typescript
+// Necessário: biblioteca externa não provê tipagem genérica na versão atual
+const dados = payload.raw as unknown as RespostaFormatada
+```
+
+## 4. TODOs estruturados
+
+Dívida técnica ou dúvida de negócio deve seguir formato padronizado:
+
+- **Tipagem**: `// TODO de tipagem: Criar interface para o retorno da API`
+- **Negócio**: `// TODO de regra: Validar com Produto se taxa se aplica a clientes antigos`
+
+## Impacto
+
+Sem este padrão, funções compartilhadas ficam sem documentação, casts aparecem sem justificativa, e TODOs são inconsistentes e difíceis de buscar.
+
+## Referências
+
+- Rule: `.agent/rules/typescript-sem-any.global.md`