Por que 20.977 blocos de comentário acima do limite eram, em sua maioria, código de terceiros

A verificação de tamanho de comentário sinalizava todo comentário com mais de 2 linhas, e mesmo assim nossos agentes continuavam escrevendo comentários longos.

Um aviso que só o log via

A verificação percebia os comentários longos, mas o aviso ia só para o log. No modo bypass, a verificação da plataforma devolvia apenas permissionDecision: "allow" e um motivo que começava com “Advisory (not blocked): comment block is 10 lines (limit 2)”. Esse motivo não é mostrado ao modelo quando a resposta é allow. O aviso nunca chegava ao agente.

Como ficou a correção

A correção coloca a explicação no que o agente realmente lê. Rodei um bloco de comentário de 10 linhas pelo hook no modo bypass e recebi “allow” mais a nota “Writing standard: comment block is 10 lines (limit 2). Shorten it…”. O modo padrão devolveu “ask” com a mesma nota. A nota diz ao agente para reduzir a 2 linhas, a menos que haja um motivo real (cabeçalho de licença, pegadinha crítica), e para deixar o histórico de revisão e os números de ticket fora dos comentários do código. O agente que construiu isso adicionou 3 testes, todos passando, e confirmou que a nota chega sem alteração pelo relay do repositório de operações.

Dois dos nossos três códigos nunca tinham passado para o modo advisory. No modo bypass, eles ainda negam um comentário longo de cara, e uma pessoa precisa aprovar. Ali, a nota foi para o caminho “ask”.

A verificação semanal de pré-lançamento também ganhou uma nova seção, só de relatório, que lista blocos de comentário longos no código prestes a sair. Na primeira execução de verdade, ela listou 47 blocos, a maioria em um dos outros dois códigos. A detecção também sinalizou um bloco de 22 linhas em um arquivo de página, e esse arquivo tinha nove blocos menores, de 3 a 7 linhas.

Como foi enviada só para uma branch, a correção não chegou a nenhum agente até ser integrada à develop. Eu ainda não tinha visto um agente ler a nota e reduzir o comentário.

Minha primeira contagem estava errada

Comecei uma contagem completa nos três códigos. Deu 20.977 blocos de comentário acima do limite em 2.133 arquivos no principal, e 2.733 deles citavam um ticket. Os outros dois tinham 1.020 e 184.

O número principal estava inflado, porque minha contagem rápida não pulava o que o hook pula. Os piores arquivos eram bibliotecas de terceiros (dois arquivos de uma biblioteca de editor somavam cerca de 1.000 blocos), bundles compilados com data que repetem o código-fonte (um tinha 245 blocos, e o código-fonte dele, 244) e cabeçalhos comuns de doc-comment em funções. Descartando isso, os verdadeiros infratores estavam nos nossos próprios arquivos. Um tinha 408 blocos longos. Um no código da API tinha 59.

Bloqueio a partir de 8 linhas

Adicionamos uma segunda camada. Blocos de 8 linhas ou mais agora são bloqueados para os agentes, a menos que o bloco comece com keep-long-comment: <reason>. Essas exceções ainda me avisam, então vejo todas. Blocos menores recebem a nota. Cabeçalhos de licença e as migrações SQL da API não são bloqueados, mas ainda recebem a nota. Uma etiqueta de rodada de revisão como “R6” ao lado de um número de ticket ganha um aviso próprio dizendo que o histórico de revisão pertence ao JIRA. As regras também entraram no CLAUDE.md de cada repositório, para os agentes lerem logo de início.

Colegas digitando à mão não são afetados. A verificação de pre-commit do git continua como estava, e só as sessões do Claude são bloqueadas. Vi uma execução ao vivo de um agente ser bloqueada por um comentário de 8 linhas nos três repositórios.

O fechamento teve um tropeço. A verificação de lint do repositório da API recusou o push para a develop porque os novos arquivos de hook usavam require('fs') simples, onde ela quer node:fs, e também precisavam de uma limpeza de formatação. Nada chegou à develop. Um agente foi designado para corrigir o lint mantendo os arquivos idênticos nos três repositórios.

Limpando o que já existia

Cerca de 1.400 comentários longos já existentes, escritos por IA, foram reduzidos, com um segundo revisor conferindo os rascunhos. Nos lotes 13 a 18, que cobriram 252 rascunhos, ele aprovou 218, reescreveu 29 e rejeitou 5, e encontrou 14 blocos ruins que o redator tinha deixado passar. Nenhum dos rascunhos quebrou a sintaxe.

Ele pegou rascunhos que tinham perdido fatos, incluindo a legenda [T]/[E]/[D] que o código logo abaixo ainda usa, e “the breaker never auto-clears, so this alert is the only signal”. Também pegou cortes dentro de um plugin jQuery de terceiros embutido, uma lista de verificação apagada que citava checagens que o handler não faz e uma linha de código comentada apagada junto com o texto explicativo.

Depois, um verificador separado conferiu os 518 arquivos alterados com scripts próprios e constatou que só o texto dos comentários tinha mudado. Ele amostrou 40 comentários reescritos contra o código e não achou nenhum fato errado. Três blocos ainda estavam no limite, outros 3, de 10 a 11 linhas, chegaram perto, e 215 comentários ainda traziam etiquetas de revisão como “codex finding 3”. As correções para isso somaram 223 linhas.

Ainda não vimos

O trabalho está encerrado e sai no próximo lançamento. O que eu ainda não vi foi um agente esbarrar no bloqueio de 8 linhas e reduzir o próprio comentário, e isso só pode acontecer depois que o lançamento for ao ar. A verificação semanal de pré-lançamento, que listou 47 blocos na primeira execução, é o que vai mostrar se os comentários longos param de voltar.