.agent/global/rules/jsdoc-padrao.md

type	name	description	scope	trigger	globs	updatedAt
rule	jsdoc-padrao	Padrões de documentação em código (JSDoc, casts temporários e TODOs estruturados)	global	file_match	**/*.ts **/*.tsx **/*.vue	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:

/**
 * 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ê:

// 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: global/rules/typescript-sem-any.md