---
title: "Nomenclatura ciega al contexto"
type: "ai-smell"
slug: "context-blind-naming"
url: "http://localhost:3000/es/ai-smells/context-blind-naming.md"
category: "Claridad"
description: "Un asistente de IA nombra el código nuevo con marcadores genéricos o una convención recién inventada que ignora los identificadores existentes del repositorio y el vocabulario del dominio, erosionando la legibilidad y generando conceptos duplicados y mal descritos."
---
# Nomenclatura ciega al contexto

> Un asistente de IA nombra el código nuevo con marcadores genéricos o una convención recién inventada que ignora los identificadores existentes del repositorio y el vocabulario del dominio, erosionando la legibilidad y generando conceptos duplicados y mal descritos.

## Signs and Symptoms

Un revisor detecta la nomenclatura ciega al contexto cuando los nombres en un diff escrito por IA son localmente plausibles pero están desconectados del repositorio circundante. Señales reveladoras:

* **Marcadores genéricos en código de dominio:** `data`, `result`, `temp`, `item`, `obj`, `payload`, `response`, `value`, `handleStuff`, `processData` donde el módulo ya habla un lenguaje específico (`grossPremium`, `Customer`, `getCustomerById`).
* **Deriva de convenciones:** un símbolo en `snake_case` colocado en un archivo `camelCase`, un prefijo booleano `is`/`has` ausente, o un nuevo verbo CRUD (`fetch*`) en una base de código que estandarizó `get*`. Cada diff "sigue el estilo que encontró por última vez, introduciendo una cuarta convención. Luego una quinta."
* **Proliferación de sinónimos / conceptos duplicados:** la IA inventa `fetchUser` cuando `getCustomerById` ya existe, o mezcla `customer`/`client`/`user` para una sola entidad, reimplementando en lugar de reutilizar.
* **Nombres que describen el mecanismo, no la intención, o que mienten sobre el comportamiento:** `processData()` que en realidad calcula el impuesto sobre las ventas. Los agentes (y el siguiente agente) "leen `processData()` y proceden como si ese nombre contara toda la historia", así que el significado erróneo se propaga a cada punto de llamada.

```ts
// El repositorio ya exporta getCustomerById(id: CustomerId): Promise<Customer>
// La IA añade un casi-duplicado con nombres ciegos al contexto:
async function fetchData(id: string) {          // verbo genérico, tipo laxo
  const result = await db.query("select * from customers where id = $1", [id]);
  const temp = result.rows[0];                  // 'temp' oculta que es un Customer
  return temp;                                  // nada aquí dice "Customer"
}

```

## Reasons for the Problem

**Por qué los modelos lo producen**

* **Sesgo de frecuencia del siguiente token.** En todo el corpus de entrenamiento, `data`/`result`/`temp`/`foo` son los identificadores de mayor probabilidad, especialmente en el código de tutoriales y plantillas que los LLM ingieren en abundancia. Generar el nombre _estadísticamente promedio_ es exactamente lo que un predictor del siguiente token está optimizado para hacer, lo que diluye la intención del dominio ([Towards Data Science](https://towardsdatascience.com/the-missing-curriculum-essential-concepts-for-data-scientists-in-the-age-of-ai-coding-agents/)).
* **Sin contexto del repositorio (o truncado).** El modelo rara vez ve el glosario del módulo hermano ni el `getCustomerById` existente. GitClear vincula directamente el aumento de la duplicación con esto: el asistente "es menos propenso a proponer reutilizar una función similar de otro lugar... en parte por el tamaño limitado del contexto" ([GitClear 2025](https://www.gitclear.com/ai%5Fassistant%5Fcode%5Fquality%5F2025%5Fresearch)).
* **Optimización local / instinto débil de refactorización.** Cada turno optimiza el prompt inmediato, "sin considerar el impacto arquitectónico acumulado". OX Security halló _evitación de refactorizaciones_ en el 80–90 % del código de IA, así que el modelo añade un símbolo recién nombrado en lugar de renombrar o reutilizar uno existente ([informe de OX](https://www.prnewswire.com/news-releases/ox-report-ai-generated-code-violates-engineering-best-practices-undermining-software-security-at-scale-302592642.html)).
* **Desactualización por la fecha de corte del entrenamiento.** Las convenciones y los nombres de API de corpus más antiguos resurgen incluso después de que un proyecto haya avanzado.

**Por qué resulta perjudicial**

* **Legibilidad/mantenibilidad:** los nombres son la documentación principal de una base de código; los genéricos obligan a cada lector a volver a deducir la intención a partir del cuerpo.
* **Duplicación y defectos:** renombrar un concepto genera una implementación paralela. GitClear midió un aumento de \~8× en bloques duplicados y, por primera vez en 2024, el copiar/pegar superó a las líneas movidas (refactorizadas); los clones acarrean un estimado 15–50 % más de defectos.
* **Bucle de retroalimentación de agentes (el daño específico de la IA):** los nombres son la interfaz que el _siguiente_ agente lee al pie de la letra. Un nombre engañoso o genérico "propaga errores a todo el código generado por agentes que se construye sobre él" ([AI Pattern Book](https://aipatternbook.com/naming)).
* **Carga de revisión y corrección:** los revisores deben mapear mentalmente `temp`/`data` de vuelta a conceptos del dominio, lo que oculta errores; los nombres engañosos provocan un uso incorrecto en los puntos de llamada.
* **Puntos ciegos de seguridad/auditoría:** un secreto o token aparcado en una variable llamada `data`/`tmp` se cuela ante los greps basados en nombres y la atención de la revisión.

Nota: investigaciones como arXiv [2509.20491](https://arxiv.org/abs/2509.20491) muestran que las herramientas estáticas detectan bien los olores _locales y explícitos_, pero la faceta de significado del dominio aquí depende del valor/la intención y escapa en gran medida a la detección automatizada.

## Treatment

**Tácticas de revisión y de prompting**

* **Incorpora las convenciones y el glosario al contexto.** Mantén una guía breve de nomenclatura (mayúsculas, prefijos booleanos, verbos CRUD, términos del dominio) en `CLAUDE.md`/los documentos de estilo y exige que el modelo la siga. Aplica los términos del glosario del dominio de forma consistente para que los sinónimos colapsen en una sola palabra.
* **Fuerza la reutilización antes de la creación.** Prompt: "Busca en el repositorio una función/tipo existente para esto antes de añadir uno; reutilízalo." Esto contrarresta directamente el fallo de conceptos duplicados que señalan GitClear y OX.
* **Nombra las cosas en el prompt.** "Nombra el manejador `createRefund`" es mejor que "añade el procesamiento de reembolsos". Especifica nombres del dominio (`monthlyRevenue`, no `float1`).
* **Exige que se ejecuten el linter + el escaneo de duplicación** sobre el diff (naming-convention + `id-denylist` \+ jscpd) y haz que el modelo corrija las infracciones en lugar de hacerlo tú a mano.

**La refactorización**: aplica _Renombrar variable/función_ (el "Cambiar declaración de función" de Fowler), corrigiendo el olor de **Nombre misterioso**, y _Consolidar código duplicado_ reutilizando el símbolo existente en lugar del nuevo.

Antes:

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

```

Después (reutiliza la función existente del repositorio; nombres y tipos que revelan la intención y respetan la convención):

```ts
// No vuelvas a consultar — reutiliza getCustomerById y conserva el vocabulario del dominio.
async function getCustomerById(id: CustomerId): Promise<Customer | null> {
  const { rows } = await db.query<Customer>(
    "select * from customers where id = $1",
    [id],
  );
  return rows[0] ?? null;
}

```

Si un nombre engañoso ya se entregó, renómbralo para que coincida con el comportamiento (`processData` → `calculateSalesTax`) antes de construir sobre él, para que los agentes y las personas posteriores hereden la señal correcta.

## Detected by

- **ESLint (core)** `id-denylist` — Prohíbe identificadores especificados (https://eslint.org/docs/latest/rules/id-denylist)
- **ESLint (core)** `id-length` — Impone una longitud mínima/máxima de identificador (https://eslint.org/docs/latest/rules/id-length)
- **typescript-eslint** `@typescript-eslint/naming-convention` — Impone convenciones de nomenclatura (mayúsculas/prefijos) (https://typescript-eslint.io/rules/naming-convention/)
- **eslint-plugin-unicorn** `unicorn/prevent-abbreviations` — Evita abreviaturas / nombres demasiado genéricos (https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/prevent-abbreviations.md)
- **SonarQube / SonarSource** `typescript:S117` — Los nombres de variables locales y parámetros deben cumplir una convención de nomenclatura (https://rules.sonarsource.com/typescript/RSPEC-117/)
- **jscpd** `copy-paste-detection` — Detecta bloques duplicados creados cuando un concepto renombrado duplica uno existente (https://github.com/kucherenko/jscpd)