Claude Code y Node.js lento: mide el cuello de botella antes de corregir

Tu API de Node.js tarda demasiado en generar un informe, el equipo pide una corrección antes del siguiente despliegue y alguien propone “pon un índice”. Puede ser la solución, pero sigue siendo una apuesta si no has medido dónde se consume el tiempo.

Esta guía usa Claude Code como asistente de programación, no como adivino. Un cuello de botella es la parte lenta que limita toda la petición. Perfilar significa medir el tiempo de ejecución para ver ese cuello de botella. El flujo seguro es añadir temporizadores pequeños, ejecutar un comando reproducible con datos sintéticos, corregir solo la sección más lenta y repetir el mismo comando.

El alcance es Node.js del lado servidor: manejadores de API, tareas por lotes, exportaciones CSV y procesos de datos. Si el problema está en la carga visual del navegador, conviene leer la guía de Core Web Vitals. Si el tiempo está dentro de SQL, el siguiente paso es la guía de optimización SQL.

Primer paso

Empieza con el artefacto más pequeño que reproduce el dolor: una ruta, un script, una fixture o una exportación CSV. No pidas a Claude Code “haz el proyecto más rápido” si todavía no existe un comando que muestre la lentitud. Un comando concreto reduce lectura innecesaria y deja una evidencia revisable.

Define los términos desde el inicio. Un problema N+1 aparece cuando se obtiene una lista una vez y luego se consulta información relacionada una vez por elemento. Un await en serie obliga a llamadas independientes a esperar una detrás de otra. La memoización reutiliza el resultado para la misma entrada en lugar de recalcularlo.

Un prompt inicial útil separa medición y permisos:

claude -p "src/api/report.ts is slow. Do not rewrite it yet.
Add timing around database fetch, API fetch, transform, and response formatting.
Use synthetic fixture data only. Return the changed files, command to run, and the slowest measured section.
Do not change production settings, billing limits, credentials, or customer-data handling without human approval."

Código de medición para copiar

El primer cambio debe ser aburrido: imprimir tiempos, no rediseñar el servicio. Node.js incluye performance.now() en la documentación oficial de node:perf_hooks, así que no hace falta instalar paquetes.

Crea measured-report.mjs en una rama de prueba o carpeta desechable y ejecútalo con Node. Los datos son sintéticos: no hay secretos, tokens, URLs de producción ni filas de clientes.

import { performance } from "node:perf_hooks";

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function createTimer() {
  const records = [];
  return {
    async measure(label, fn) {
      const start = performance.now();
      const value = await fn();
      records.push({ label, ms: Number((performance.now() - start).toFixed(1)) });
      return value;
    },
    report() {
      return records.sort((a, b) => b.ms - a.ms);
    },
  };
}

async function fetchUsers() {
  await wait(60);
  return Array.from({ length: 6 }, (_, index) => ({ id: index + 1 }));
}

async function fetchOrdersOneByOne(users) {
  const orders = [];
  for (const user of users) {
    await wait(45);
    orders.push({ userId: user.id, total: user.id * 10 });
  }
  return orders;
}

async function fetchOrdersInBatch(users) {
  await wait(55);
  return users.map((user) => ({ userId: user.id, total: user.id * 10 }));
}

function buildReport(users, orders) {
  const ordersByUser = new Map(orders.map((order) => [order.userId, order]));
  return users.map((user) => ({ ...user, orderTotal: ordersByUser.get(user.id)?.total ?? 0 }));
}

async function run(fetchOrders) {
  const timer = createTimer();
  const users = await timer.measure("users", fetchUsers);
  const orders = await timer.measure("orders", () => fetchOrders(users));
  await timer.measure("report", () => buildReport(users, orders));
  console.table(timer.report());
}

console.log("slow version");
await run(fetchOrdersOneByOne);

console.log("batch version");
await run(fetchOrdersInBatch);

Comandos:

node measured-report.mjs
node --prof measured-report.mjs
node --prof-process isolate-*.log > profile.txt

node --prof es un perfilador integrado y está documentado en la referencia oficial de CLI de Node.js. Úsalo cuando el consumo de CPU no quede claro con temporizadores simples; en muchas APIs y tareas por lotes, la tabla pequeña ya señala el primer objetivo.

Tres casos de uso reales

Caso 1: respuesta lenta de una API

Entrada: el manejador de la API, una prueba de ruta y una petición sintética. Claude Code puede añadir temporizadores alrededor de lectura de base de datos, llamada externa, transformación y serialización. Una persona debe aprobar cambios en credenciales, autenticación, límites de tráfico o conservación de datos de clientes.

Salida: una tabla de tiempos y un parche pequeño sobre la sección más lenta. Si la sección lenta es una consulta, pasa a la lista de SQL antes de añadir índices al azar. Si el tiempo está en formato JSON, la corrección pertenece al código de aplicación.

Caso 2: exportación CSV por lotes

Entrada: una fixture local con filas falsas y el comando que genera el CSV. Claude Code puede medir carga de filas, cruces, formato y escritura de archivo. Una persona debe aprobar el paso de fixtures a exportaciones reales, porque ahí pueden aparecer datos de clientes y coste de cómputo.

Salida: evidencia de si el problema viene de lecturas N+1, llamadas en serie o formateo repetido. La corrección suele ser agrupar, limitar concurrencia o memoizar formateadores, no reescribir toda la tarea.

Caso 3: revisión de pull request antes del release

Entrada: el diff, la prueba de rendimiento existente y el presupuesto esperado, por ejemplo mantener la latencia dentro del objetivo actual del servicio. Claude Code puede revisar el diff y sugerir medición adicional. La decisión de release, rollback y promesas hacia clientes requiere aprobación humana.

Salida: una nota que nombra el riesgo medido, el comando ejecutado y lo que sigue sin medir. Eso vale más que decir “parece más rápido”.

Patrones de corrección después de medir

Síntoma medido	Causa probable	Primera corrección segura
Muchas consultas o llamadas parecidas	N+1	Agrupar identificadores o usar una carga relacionada en bloque
Llamadas independientes suman tiempo	await en serie	Usar Promise.all solo para trabajo independiente
La misma transformación se repite	Recalcular sin necesidad	Memoizar por entrada o mover preparación fuera del bucle
El tiempo crece mucho con las filas	Búsqueda anidada	Crear un Map una vez o revisar el plan antes de indexar

La tabla no sustituye la medición. Sirve para convertir el resultado en el parche más pequeño. Si una corrección toca seguridad, tráfico de producción, facturación o datos de clientes, detente y pide aprobación antes de ejecutarla fuera de la fixture.

Errores y correcciones

Error: pedir a Claude Code “optimiza este endpoint” sin comando. Corrección: exigir comando de reproducción, fixture y tabla de tiempos antes de cualquier reescritura.

Error: tratar números sintéticos como benchmark de producción. Corrección: etiquetar los datos locales como sintéticos y usarlos solo para ubicar el cuello de botella probable. Las conclusiones de producción necesitan observabilidad aprobada del sistema real.

Error: cambiar un bucle en serie por Promise.all sin límite. Corrección: confirmar independencia y usar límite de concurrencia cuando hay base de datos, API de pago o servicio con rate limit.

Error: añadir índices porque la palabra “base de datos” aparece en la ruta lenta. Corrección: mirar el plan de consulta y anotar el coste de escritura y almacenamiento.

Alcance de Claude Code y aprobación humana

Deja que Claude Code haga tareas repetibles: añadir temporizadores temporales, crear fixture sintética, buscar consultas dentro de bucles, proponer agrupación, actualizar una prueba y resumir la evidencia antes y después. Son cambios reversibles y fáciles de revisar.

Reserva la aprobación humana para decisiones de producción: autenticación, registros de clientes, envío de datos a servicios externos, concurrencia de APIs pagadas, límites de facturación, despliegue y cualquier promesa pública de SLA. El agente prepara el diff y la lista; una persona acepta el riesgo.

Una línea útil para el handoff es: “Claude puede modificar medición local y pruebas. Se requiere aprobación humana antes de usar datos de producción, cambiar secretos, tocar controles de facturación o desplegar”.

CTA principal

Los equipos que quieran convertir este flujo en hábito compartido pueden usar la página de formación y consultoría de Claude Code. El resultado buscado no es una promesa mágica de velocidad, sino una revisión repetible con comando, fixture, cuello medido, parche y riesgo restante.

Verificación práctica

Para esta actualización revisé que los enlaces internos usen /es/, que los enlaces externos apunten a documentación oficial de Node.js, que los bloques de código sean JavaScript y comandos ejecutables, que el ejemplo use solo datos sintéticos y que la CTA lleve a la página española de formación.

No ejecuté un benchmark de producción, no inspeccioné incidentes reales ni afirmé una mejora medida en un servicio vivo. La comprobación práctica fue el contenido del artículo, la forma sintáctica de los bloques, la localidad de enlaces y la separación entre lo que Claude Code puede hacer y lo que una persona debe aprobar.