Nomenclatura Cega ao Contexto.

Um revisor identifica Nomenclatura Cega ao Contexto quando os nomes em um diff de autoria da IA são localmente plausíveis, mas desconectados do repositório ao redor. Sinais reveladores:

• Placeholders genéricos em código de domínio: data, result, temp, item, obj, payload, response, value, handleStuff, processData onde o módulo já fala uma linguagem específica (grossPremium, Customer, getCustomerById).
• Deriva de convenções: um símbolo snake_case jogado em um arquivo camelCase, um prefixo booleano is/has ausente, ou um novo verbo CRUD (fetch*) em uma base de código que padronizou em get*. Cada diff segue qualquer que seja o estilo que encontrou por último, introduzindo uma quarta convenção. E então uma quinta.
• Proliferação de sinônimos / conceitos duplicados: a IA inventa fetchUser quando getCustomerById já existe, ou mistura customer/client/user para uma única entidade — reimplementando em vez de reutilizar.
• Nomes que descrevem o mecanismo, não a intenção — ou que mentem sobre o comportamento: processData() que na verdade calcula imposto sobre vendas. Os agentes (e o próximo agente) leem processData() e prosseguem como se aquele nome contasse toda a história, então o significado errado se propaga para cada ponto de chamada.

// O repositório já exporta getCustomerById(id: CustomerId): Promise<Customer>
// A IA adiciona uma quase-duplicata com nomes cegos ao contexto:
async function fetchData(id: string) {          // verbo genérico, tipo frouxo
  const result = await db.query("select * from customers where id = $1", [id]);
  const temp = result.rows[0];                  // 'temp' esconde que é um Customer
  return temp;                                  // nada aqui diz "Customer"
}

Por que os modelos a produzem

• Viés de frequência do próximo token. Em todo o corpus de treinamento, data/result/temp/foo estão entre os identificadores mais frequentes, especialmente no código de tutorial e boilerplate que os LLMs ingerem intensamente. Gerar o nome estatisticamente médio é exatamente o que um preditor de próximo token é otimizado para fazer, o que apaga a intenção do domínio.
• Sem contexto do repositório (ou truncado). O modelo raramente vê o glossário do módulo irmão ou o getCustomerById existente. O resumo da DevClass sobre o relatório de 2025 da GitClear observa que os assistentes têm menos probabilidade de propor a reutilização de uma função similar em outro lugar, em parte por causa do tamanho limitado do contexto (DevClass sobre a GitClear 2025).
• Otimização local / instinto fraco de refatoração. Cada turno otimiza o prompt imediato, não a base de código como um todo. A OX Security encontrou Evitação de Refatorações — uma IA que "se destaca gerando código novo, mas nunca volta para melhorar a arquitetura" — em 80–90% do código de IA analisado (relatório OX).
• Defasagem do corte de treinamento. Convenções e nomes de API de corpora mais antigos ressurgem mesmo depois que um projeto já seguiu em frente.

Por que isso prejudica

• Legibilidade/manutenibilidade: nomes são a principal documentação de uma base de código; os genéricos forçam cada leitor a rederivar a intenção a partir do corpo.
• Duplicação e defeitos: renomear um conceito gera uma implementação paralela. A análise de 2025 da GitClear, com 211 milhões de linhas alteradas (2020–2024), constatou que as linhas associadas à refatoração (linhas "movidas") caíram de 25% das linhas alteradas em 2021 para menos de 10% em 2024, enquanto as linhas copiadas/coladas subiram de 8,3% para 12,3% no mesmo período; 2024 foi o primeiro ano em que as linhas copiadas/coladas superaram as movidas, e os blocos com cinco ou mais linhas duplicadas cresceram cerca de oito vezes ao longo de 2024 (GitClear 2025).
• Loop de feedback de agentes (o dano específico de IA): nomes são a interface que o próximo agente lê ao pé da letra. Como diz a Encyclopedia of Agentic Coding Patterns, "um agente de IA trata os nomes que encontra em uma base de código como seu principal sinal para entender o que as coisas fazem", e "nomes inconsistentes no código existente produzem nomes inconsistentes no código gerado" (AI Pattern Book).
• Carga de revisão & correção: os revisores precisam mapear mentalmente temp/data de volta a conceitos de domínio, o que esconde bugs; nomes enganosos causam uso incorreto nos pontos de chamada.
• Pontos cegos de segurança/auditoria: um segredo ou token estacionado em uma variável chamada data/tmp escapa de greps baseados em nomes e da atenção da revisão.

Observação: ferramentas estáticas capturam bem violações de nomenclatura locais e explícitas (maiúsculas/minúsculas, comprimento, palavras proibidas), mas saber se um nome corresponde ao significado do domínio depende da intenção e escapa em grande parte da detecção automatizada.

Táticas de revisão & prompting

• Alimente as convenções e o glossário no contexto. Mantenha um guia de nomenclatura curto (casing, prefixos booleanos, verbos CRUD, termos de domínio) em CLAUDE.md/docs de estilo e exija que o modelo o siga. Aplique os termos do glossário de domínio de forma consistente para que os sinônimos colapsem em uma única palavra.
• Force a reutilização antes da criação. Prompt: "Procure no repositório por uma função/tipo existente para isto antes de adicionar uma nova; reutilize-a." Isso combate diretamente a falha de conceito duplicado que a GitClear e a OX sinalizam.
• Nomeie as coisas no prompt. "Nomeie o handler como createRefund" é melhor do que "adicione processamento de reembolso". Especifique nomes de domínio (monthlyRevenue, não float1).
• Exija que o linter + a varredura de duplicação rodem no diff (naming-convention + id-denylist + jscpd) e faça o modelo corrigir as violações em vez de você fazê-lo à mão.

A refatoração — aplique Renomear Método (e o mesmo para variáveis) para corrigir nomes enganosos, e elimine o Código Duplicado chamando o símbolo existente em vez do novo.

Antes:

async function fetchData(id: string) {
  const result = await db.query("select * from customers where id = $1", [id]);
  const temp = result.rows[0];
  return temp;
}

Depois (remova a quase duplicata e chame a função de repositório existente com o tipo do domínio):

// Não consulte de novo — reutilize getCustomerById e mantenha o vocabulário do domínio.
const customer = await getCustomerById(id as CustomerId);

Se um nome enganoso já foi entregue, renomeie-o para corresponder ao comportamento (processData → calculateSalesTax) antes de construir em cima dele, para que agentes e humanos a jusante herdem o sinal correto.