yonathan-boop/Claude

antislop-code

Anti Slop: Regras para Agentes de Codificação de IA. Skill de Comentários de Código

Parte do sistema antislop. Leia junto com antislop.md (o núcleo). Este skill filtra comentários que soam como IA genérica (decorativos, repetindo o óbvio, formais, exagerados) enquanto preserva os comentários que carregam informações reais. Ele referencia regras do núcleo por número e nunca as duplica ou renumera. Carregue-o quando a tarefa escrever ou editar comentários de código.

Como usar este skill

• Carregue junto com antislop.md sempre que a tarefa tocar em comentários de código. O núcleo contém o mecanismo (o teste de propósito, os três níveis, o Portão de Entrega); este skill contém a profundidade específica de comentários.
• Cada entrada tem a mesma forma: Diga (o padrão), Por que (por que soa como slop), Correção (o que fazer em vez disso), com a regra central governante citada como R-XX.
• Guarda-corpo de escopo: este skill modifica apenas comentários. Nunca modifique código executável, identificadores, imports, formatação, indentação, espaços em branco, fluxo de controle ou lógica. Em caso de dúvida, deixe o código intocado.
• O Portão de Entrega no núcleo permanece o portão. A "Lista de Verificação de Comentários de Código" no final deste arquivo é o suplemento específico de comentários para executar junto.

Comentários Que Não Acrescentam Nada

Separadores Decorativos

• Diga: comentários banner construídos com caracteres repetidos, rótulos EM CAIXA ALTA ou desenhos de caixa ao redor do nome de uma seção: // ======================= em torno de Authentication, // -------- WORKFLOW -------- ou um cabeçalho /* ---- ROUTES ---- */.
• Por que: a decoração é a mensagem. Um rótulo envolto em = ou - sinaliza "IA fez isso" sem adicionar informação, e CAIXA ALTA soa como grito.
• Correção: substitua por uma única linha simples ou remova completamente se o rótulo não acrescentar nada (R-31).

Repetindo o Óbvio

• Diga: um comentário que repete o que a próxima linha ou declaração já mostra, como // Inicializa a variável acima de let count = 0, // Classe Usuário acima de class User {}, // Valida usuário acima de function validateUser(), ou const userAge = 25; // Idade do usuário é 25.
• Por que: dobra a carga de leitura sem acrescentar nada. O código já diz isso; o comentário apenas repete.
• Correção: remova e deixe a linha de código em paz.

Narração de Fluxo de Trabalho

• Diga: comentários que narram o fluxo passo a passo, como // Passo 1: Validar entrada, // Passo 2: Processar requisição, // Passo 3: Retornar resposta, ou // Primeiro..., // Em seguida..., // Finalmente....
• Por que: o fluxo de controle é visível no próprio código. Numerá-lo parece uma lista de verificação, não uma explicação.
• Correção: remova. Se o fluxo for genuinamente difícil de seguir, isso é um problema de estrutura, não um problema de falta de comentário.

Rótulos Vazios

• Diga: rótulos genéricos sem informação por trás: // Lógica principal, // Lógica central, // Lógica de negócio, // Função auxiliar, // Ponto de entrada, // Tratamento de erro, ou // Nota: Isso é importante. / // Importante: Por favor, leia.
• Por que: o rótulo nomeia uma categoria, não um fato. "Lógica principal" não diz ao leitor nada que ele não pudesse inferir do código.
• Correção: remova, a menos que o rótulo carregue informação específica. "Nota: as tentativas ocorrem apenas em 5xx" merece seu lugar; "Nota: isso é importante" não.

Placeholders Vagamente Definidos

• Diga: comentários que prometem trabalho futuro sem dizer o quê: // TODO: Melhorar isso, // Melhorias futuras, // Otimização adicional pode ser adicionada aqui, // Adicionar mais validação.
• Por que: um TODO vago é ruído. Ele nomeia um sentimento (isso poderia ser melhor) em vez de uma tarefa (o quê e por quê).
• Correção: remova. Mantenha um TODO apenas quando ele nomear uma tarefa específica com contexto suficiente para agir.

Eco de Assinatura

• Diga: documentação que apenas repete a assinatura, como um bloco JSDoc que repete @param preco O preço. e @returns Preço total. para uma função cujo nome e parâmetros já dizem tudo.
• Por que: documentação que ecoa a assinatura adiciona comprimento, não compreensão. O leitor não aprende nada novo.
• Correção: simplifique ou remova o eco. Mantenha documentação que explique regras de negócio, casos de borda, suposições, algoritmos, limitações, efeitos colaterais, comportamento da API ou implicações de segurança. Nunca remova documentação real.

Emoji Decorativo

• Diga: emoji usado como decoração em comentários, como // ✅ Validação ou // 🚀 Performance.
• Por que: emoji é ruído visual no código, e o conjunto específico (✅, 🚀, 🔒) é o vocabulário padrão da IA.
• Correção: substitua por português simples, ou remova se o rótulo não acrescentar nada.

Marcadores de Fim

• Diga: comentários que apenas marcam o fim de um bloco, como } // fim if, # Fim da função ou // Fim processOrder.
• Por que: a chave de fechamento já encerra o bloco. O marcador existe por hábito, não por necessidade.
• Correção: remova. No raro caso em que um marcador de fim genuinamente ajuda um arquivo longo, mantenha-o apenas onde evitar confusão, não como hábito.

Como Deve Ler

O Comentário Superexplicado

• Diga: um comentário que se estende por várias linhas, empilhando razões, contexto e história em torno de um fato que cabe em uma linha: um bloco de quatro linhas explicando que um stub está no PATH, qual versão introduziu a solução alternativa e o que quebrou antes dela. Cada frase é verdadeira. O comprimento é o indicador.
• Por que: uma pessoa deixa uma nota, um gerador escreve um caso. Preencher um fato de uma linha em um parágrafo, construir uma cadeia "porque X, então Y e portanto Z" ou citar o número do problema e a versão que o corrigiu são o mesmo floreio que qualquer outro padrão de IA, e eles enterram a linha que importa sob aquelas que não importam.
• Correção: corte para a restrição apenas: uma linha, duas no máximo, nunca três. Mantenha a armadilha da plataforma, a falha silenciosa, a regra do protocolo, o custo de desempenho. Descarte o número do problema, o histórico de versões e a cadeia de raciocínio.

Narração Linha por Linha

• Diga: um comentário em cada declaração trivial, narrando cada linha conforme é escrita: // Inicializa contador, depois // Percorre itens, depois // Obtém item, depois // Incrementa, depois // Retorna resultado.
• Por que: quando cada linha é comentada, nenhum dos comentários importa. O leitor tem que verificar cada um para encontrar aquele que carrega significado.
• Correção: escreva um comentário conciso por bloco lógico em vez de um por linha. Se o bloco não precisar de comentário, não escreva nenhum.

Linguagem Formal ou Exagerada

• Diga: comentários que soam formais, longos ou gritados: "Esta função é responsável por validar se as credenciais fornecidas são válidas antes de prosseguir com o processo de autenticação", ou // LÓGICA PRINCIPAL em maiúsculas.
• Por que: linguagem formal e exagerada soa como gerada, não como um engenheiro deixando uma nota para o próximo.
• Correção: escreva linhas curtas, em letras minúsculas (exceto quando necessário) e com uma voz natural de desenvolvedor: // Valida credenciais antes de emitir um token. Bons comentários explicam o porquê, não o quê, e permanecem curtos.

Não é uma Proibição (preserve estes)

Nunca remova comentários que expliquem:

• lógica de negócio e intenção
• decisões arquiteturais
• considerações de segurança
• trade-offs de desempenho
• comportamento de concorrência
• detalhes de protocolo
• contratos de API
• soluções alternativas
• casos de borda e suposições
• licenciamento e avisos legais

Exemplo que deve permanecer:

// Stripe pode tentar novamente entregas de webhook por até três dias.
// Ignore eventos duplicados usando o ID do evento.

Um comentário merece seu lugar quando explica algo que o código já não mostra: a razão, a restrição, o comportamento não óbvio.

Merecer um lugar diz o que pode ficar, nunca por quanto tempo pode se estender. Uma nota de solução alternativa é uma linha sobre a solução alternativa, não um parágrafo sobre ela. O exemplo acima tem duas linhas porque dois fatos são reais, não porque duas linhas é uma meta. Esta lista é a razão mais comum pela qual um comentário sobrevive a uma revisão que não deveria: o conteúdo é legitimamente valioso, então o comprimento não é examinado. Valor não é comprimento.

Lista de Verificação de Comentários de Código

Execute estes junto com o Portão de Entrega central quando a tarefa tocar em comentários. Todas as respostas devem ser sim:

• Cada comentário adiciona informação que o código já não mostra? (R-31)
• Os comentários evitam separadores decorativos, banners EM CAIXA ALTA e cabeçalhos desenhados com caixa?
• Os comentários evitam repetir a linha, declaração ou assinatura óbvia?
• Os comentários evitam narração de fluxo de trabalho passo a passo?
• Os comentários evitam rótulos vazios e TODOs vagos que não nomeiam nenhuma tarefa?
• Os comentários evitam emoji decorativo e marcadores de fim?
• A densidade de comentários é um por bloco lógico, não um por linha?
• Cada comentário tem uma linha, ou duas apenas quando a segunda carrega um novo fato?
• Os comentários restantes são curtos, naturais e em letras minúsculas (exceto quando necessário)?
• O guarda-corpo de escopo é mantido: apenas comentários alterados, o código intocado?