Claude Code para investigaciones de rendimiento: un flujo de trabajo medido

Por qué el trabajo de rendimiento falla sin medición

Los bugs de rendimiento invitan a adivinar. Alguien nota que una página parece lenta o una API hace timeout, y el movimiento más rápido es "limpiar" código, añadir caché o reescribir un bucle. El problema es que "parece lento" no es una métrica, y "más limpio" no es lo mismo que más rápido.

Sin medición, los equipos pierden horas cambiando lo equivocado. La ruta crítica podría estar en la base de datos, en la red o en una única asignación inesperada, mientras el equipo pule código que apenas se ejecuta. Peor aún, un cambio que parece inteligente puede empeorar el rendimiento: logging extra en un bucle apretado, una caché que aumenta la presión de memoria o trabajo paralelo que crea contención por locks.

La adivinanza también arriesga romper el comportamiento. Cuando cambias código para acelerarlo, puedes alterar resultados, manejo de errores, orden o reintentos. Si no vuelves a comprobar la corrección y la velocidad juntas, puedes "ganar" un benchmark mientras envías silenciosamente un bug.

Trata el rendimiento como un experimento, no como un debate. El ciclo es simple y repetible:

• Elige una métrica que represente el problema (latencia, throughput, CPU, memoria, tiempo en BD).
• Captura una línea base bajo las mismas condiciones.
• Cambia una cosa pequeña.
• Mide otra vez y compara.

Muchas victorias son modestas: recortar un 8% del p95, reducir pico de memoria en 50 MB o quitar una consulta a la base de datos. Esas mejoras importan, pero solo si están medidas, verificadas y son repetibles.

El flujo: medir, hipotetizar, cambiar, re-medir

Esto funciona mejor como un bucle, no como una petición puntual de "hacerlo más rápido". El bucle te mantiene honesto porque cada acción se relaciona con evidencia y un número que puedes vigilar.

Una secuencia clara:

• Medir: elige una métrica y registra una línea base.
• Hipotetizar: explica qué crees que está lento y por qué.
• Cambiar: haz el ajuste más pequeño posible que pruebe la hipótesis.
• Re-medir: ejecuta la misma medición y compara.

Cada paso te protege de un tipo distinto de autosugestión. Medir primero evita que "arregles" algo que no era el problema. Una hipótesis escrita evita que cambies cinco cosas a la vez y luego adivines cuál importó. Cambios mínimos reducen el riesgo de romper comportamiento o añadir nuevos cuellos de botella. Re-medir detecta victorias placebo (por ejemplo, una ejecución más rápida por una caché caliente) y revela regresiones.

"Hecho" no es una sensación. Es un resultado: la métrica objetivo se movió en la dirección correcta y el cambio no provocó regresiones evidentes (errores, más memoria, peor p95 o endpoints vecinos más lentos).

Saber cuándo parar forma parte del flujo. Para cuando las ganancias se estabilizan, cuando la métrica ya es suficientemente buena para los usuarios, o cuando la siguiente idea exige grandes refactors por poco beneficio. El trabajo de rendimiento siempre tiene costo de oportunidad; el bucle te ayuda a gastar tiempo donde rinde.

Elige la métrica y fija una línea base

Si mides cinco cosas a la vez, no sabrás qué mejoró. Elige una métrica primaria para esta investigación y trata todo lo demás como señales de apoyo. Para muchos problemas de cara al usuario esa métrica es la latencia. Para trabajo por lotes puede ser throughput, tiempo de CPU, uso de memoria o incluso coste en la nube por ejecución.

Sé específico sobre el escenario. "La API es lenta" es demasiado vago. "POST /checkout con un carrito típico de 3 artículos" es medible. Mantén las entradas estables para que los números signifiquen algo.

Anota la línea base y los detalles del entorno antes de tocar el código: tamaño del dataset, tipo de máquina, modo de compilación, feature flags, concurrencia y calentamiento. Esa línea base es tu ancla. Sin ella, cualquier cambio puede parecer progreso.

Para latencia, apóyate en percentiles, no solo en una media. p50 muestra la experiencia típica, mientras p95 y p99 exponen la cola dolorosa de la que se quejan los usuarios. Un cambio que mejora p50 pero empeora p99 aún puede sentirse más lento.

Decide de antemano qué significa "significativo" para no celebrar ruido:

• Latencia: al menos 10% de mejora en p95 (o un umbral fijo como 50 ms)
• Throughput: al menos 5% más de requests por segundo con la misma tasa de errores
• CPU o memoria: reducción suficiente para evitar escalado o crashes
• Coste: descenso medible por ejecución o por cada 1,000 requests

Con estas reglas puedes probar ideas sin mover la meta.

Reúne evidencia con perfilado y métricas simples

Comienza con la señal más fácil en la que confíes. Un único timing alrededor de una petición puede decirte si tienes un problema real y más o menos de qué tamaño. Reserva el perfilado profundo para cuando necesites explicar por qué es lento.

La buena evidencia suele venir de una mezcla de fuentes:

• Logs de la app (duración de petición, tasa de errores, endpoints más lentos)
• Trazas APM (dónde se pasa el tiempo entre servicios)
• Salida del profiler o flame graphs (funciones calientes y pilas de llamadas)
• Estadísticas de BD (consultas lentas, esperas por locks, tasa de aciertos en caché)
• Métricas de infraestructura (CPU, memoria, red, reinicios de contenedores)

Usa métricas simples cuando la pregunta sea "¿está más lento y cuánto?" Usa perfilado cuando la pregunta sea "¿a dónde se va el tiempo?" Si p95 se duplicó tras un deploy, empieza con timings y logs para confirmar la regresión y acotarla. Si los timings muestran que la mayor parte del retraso está dentro del código de la app (no en la BD), entonces un profiler de CPU o un flame graph puede señalar la función exacta que creció.

Mantén las mediciones seguras. Recoge lo que necesitas para depurar rendimiento, no contenido de usuario. Prefiere agregados (duraciones, contadores, tamaños) frente a payloads crudos, y redacciona identificadores por defecto.

El ruido es real, así que toma múltiples muestras y anota valores atípicos. Ejecuta la misma petición de 10 a 30 veces y registra mediana y p95 en vez de una única ejecución "mejor".

Escribe la receta exacta de la prueba para poder repetirla después de los cambios: entorno, dataset, endpoint, tamaño del body, nivel de concurrencia y cómo capturaste los resultados.

Convierte evidencia en una hipótesis clara

Empieza con un síntoma que puedas nombrar: "p95 sube de 220 ms a 900 ms durante picos de tráfico", "CPU se mantiene al 95% en dos cores" o "la memoria crece 200 MB por hora". Síntomas vagos como "se siente lento" llevan a cambios al azar.

Luego traduce lo medido a un área sospechosa. Un flame graph puede mostrar mucho tiempo en la serialización JSON, una traza puede mostrar una ruta de llamada lenta, o las estadísticas de BD pueden mostrar una consulta que domina el tiempo total. Elige el área más pequeña que explique la mayor parte del coste: una función, una consulta SQL o una llamada externa.

Una buena hipótesis es una frase, comprobable y ligada a una predicción. Pides ayuda para probar una idea, no para que una herramienta haga todo más rápido mágicamente.

Plantilla simple de hipótesis

Usa este formato:

• Debido a (evidencia), (sospecha) está causando (síntoma).
• Si cambiamos (comportamiento específico), entonces (métrica) debería mejorar (cantidad aproximada).
• Sabremos que funcionó si (resultado de la re-medición).

Ejemplo: "Porque el perfil muestra 38% de CPU en SerializeResponse, asignar un buffer nuevo por petición está causando picos de CPU. Si reutilizamos un buffer, la latencia p95 debería bajar un 10–20% y la CPU caer un 15% bajo la misma carga."

Mantente honesto nombrando alternativas antes de tocar código. Quizá la parte lenta es en realidad una dependencia upstream, contención por locks, una caída en la tasa de aciertos de caché o un rollout que aumentó el tamaño del payload.

Escribe 2–3 explicaciones alternativas y luego elige la que mejor soporte tu evidencia. Si tu cambio no mueve la métrica, ya tendrás la siguiente hipótesis lista.

Cómo usar Claude Code sin caer en la conjetura

Claude es más útil en trabajo de rendimiento cuando lo tratas como un analista cuidadoso, no como un oráculo. Mantén cada sugerencia ligada a lo que mediste y asegura que cada paso pueda ser refutado.

Dale entradas reales, no una descripción vaga. Pega evidencia pequeña y enfocada: un resumen de perfilado, unas líneas de log alrededor de la petición lenta, un plan de consulta y la ruta de código específica. Incluye números "antes" (latencia p95, tiempo de CPU, tiempo BD) para que conozca tu línea base.

Pídele que explique lo que los datos sugieren y lo que no apoyan. Luego fuerza explicaciones competidoras. Un prompt útil termina con: "Dame 2–3 hipótesis y, para cada una, dime qué la falsaría." Eso evita engancharse a la primera historia plausible.

Antes de cambiar nada, pide el experimento más pequeño que valide la hipótesis principal. Manténlo rápido y reversible: añade un timer alrededor de una función, activa una bandera del profiler o ejecuta una consulta con EXPLAIN.

Si quieres una estructura cerrada para la salida, pide:

• Qué indica la evidencia (y con qué confianza)
• 2–3 hipótesis con una prueba de falsación
• El cambio de código o config más pequeño para probar la principal
• Exactamente qué métrica re-medir y la dirección esperada

Si no puede nombrar una métrica específica, ubicación y resultado esperado, vuelves a adivinar.

Haz cambios mínimos y reversibles

Tras tener evidencia e hipótesis, resiste la tentación de "limpiar todo". El trabajo de rendimiento es más fácil de confiar cuando el cambio es pequeño y fácil de deshacer.

Cambia una cosa a la vez. Si tocas una consulta, añades caché y refactorizas un bucle en el mismo commit, no sabrás qué ayudó (o qué perjudicó). Cambios de variable única hacen que la siguiente medición tenga sentido.

Antes de tocar código, escribe lo que esperas en números. Ejemplo: "p95 debe bajar de 420 ms a menos de 300 ms, y el tiempo BD debe reducirse ~100 ms." Si el resultado no alcanza ese objetivo, aprendes rápido que la hipótesis era débil o incompleta.

Mantén los cambios reversibles:

• Prefiere un diff pequeño que se pueda revertir limpio.
• Pon el cambio detrás de una flag para poder apagarlo rápido.
• Evita refactors que cambien nombres, formato y lógica juntos.
• Mantén el alcance: un endpoint, un hot path, una llamada cara.
• Añade una nota corta en el commit con las métricas esperadas antes/después.

"Mínimo" no significa "trivial". Significa enfocado: cachear el resultado de una función cara, eliminar una asignación repetida en un bucle apretado o dejar de hacer trabajo para peticiones que no lo necesitan.

Añade una medición ligera alrededor del cuello de botella sospechado para ver qué se movió. Un timestamp antes y después de una llamada (loggeado o capturado como métrica) puede confirmar si tu cambio golpeó la parte lenta o solo desplazó el tiempo a otro sitio.

Re-medir y decidir el siguiente paso

Tras un cambio, vuelve a ejecutar el mismo escenario que usaste para la línea base: mismas entradas, entorno y forma de carga. Si tu prueba depende de cachés o calentamiento, hazlo explícito (por ejemplo: "primera ejecución fría, siguientes 5 en caliente"). Si no, vas a "encontrar" mejoras que fueron suerte.

Compara resultados usando la misma métrica y los mismos percentiles. Las medias pueden ocultar dolor, así que vigila p95 y p99, además de throughput y tiempo de CPU. Ejecuta suficientes repeticiones para ver si los números se estabilizan.

Antes de celebrar, comprueba regresiones que no aparezcan en un número principal:

• Correctitud: las respuestas siguen coincidiendo con lo esperado.
• Tasa de errores: timeouts, 5xx, reintentos.
• Memoria: pico mayor o crecimiento sostenido entre ejecuciones.
• Latencia de cola: p99 empeoró aunque p50 mejoró.
• Coste en recursos: CPU o carga en BD se disparó.

Luego decide según la evidencia, no por esperanza. Si la mejora es real y no introdujiste regresiones, mantenla. Si los resultados son mixtos o ruidosos, revierte y formula una nueva hipótesis, o aísla más el cambio.

Si trabajas en una plataforma como Koder.ai, tomar un snapshot antes de experimentar puede convertir la reversión en un solo paso, lo que facilita probar ideas arriesgadas con seguridad.

Finalmente, escribe lo aprendido: la línea base, el cambio, los nuevos números y la conclusión. Este registro corto evita que la siguiente ronda repita los mismos callejones sin salida.

Errores comunes que hacen perder tiempo

El trabajo de rendimiento suele desviarse cuando pierdes el hilo entre lo que mediste y lo que cambiaste. Mantén una cadena de evidencia limpia para poder decir, con confianza, qué mejoró o empeoró.

Los reincidentes:

• Arreglar el objetivo equivocado: celebras una mediana (p50) más rápida, pero la latencia de cola (p95 o p99) sigue mal.
• Cambiar varias cosas a la vez: refactors, caché y ajustes de consultas en un solo commit impiden saber qué ayudó.
• Creer en una única ejecución ruidosa: un benchmark local que varía 20% entre corridas no es prueba.
• Tratar un único perfil como la verdad absoluta: un flame graph apunta a parsing JSON, pero las peticiones se acumulan por ralentizaciones en BD.
• Comparar peras con manzanas: distintos datasets, feature flags, hardware o niveles de concurrencia y sacar conclusiones.

Un ejemplo pequeño: un endpoint parece lento, afinaste el serializador porque está caliente en un profile. Luego vuelves a probar con un dataset más pequeño y parece más rápido. En producción p99 empeora porque la BD sigue siendo el cuello de botella y tu cambio aumentó el tamaño del payload.

Si usas Claude Code para proponer arreglos, mantenlo con correa corta. Pide 1–2 cambios mínimos que coincidan con la evidencia que ya recopilaste e insiste en un plan de re-medición antes de aceptar un parche.

Una lista rápida antes de declarar “más rápido”

Las afirmaciones de velocidad se desmoronan cuando la prueba es confusa. Antes de celebrar, asegúrate de poder explicar qué mediste, cómo lo mediste y qué cambiaste.

Comienza nombrando una métrica y anotando la línea base. Incluye detalles que cambian números: tipo de máquina, carga de CPU, tamaño del dataset, modo de compilación (debug vs release), feature flags, estado de caché y concurrencia. Si no puedes reproducir la configuración mañana, no tienes línea base.

Checklist:

• La métrica y la línea base están registradas con notas del entorno (hardware, config, datos, caché fría o caliente).
• Los pasos de la prueba están escritos y son repetibles.
• Tienes una hipótesis con una predicción (por ejemplo, "Si eliminamos consultas N+1, p95 debería bajar ~30%").
• Hiciste un cambio pequeño y reversible y documentaste exactamente qué se tocó (archivo, función, query, ajuste).
• Re-mediste con múltiples muestras y comparaste comparables (mismas entradas, misma carga).

Después de que los números mejoren, haz una pasada rápida de regresión. Comprueba correctitud (misma salida), tasa de errores y timeouts. Vigila efectos secundarios como más memoria, picos de CPU, peor arranque o más carga en BD. Un cambio que mejora p95 pero duplica la memoria puede ser un mal trade-off.

Ejemplo: investigar paso a paso un endpoint API lento

Un equipo informa que GET /orders va bien en dev, pero se ralentiza en staging cuando llega a carga moderada. Usuarios se quejan de timeouts, pero la latencia media aún parece "aceptable", que es una trampa clásica.

Primero, fija una línea base. Bajo una prueba de carga estable (mismo dataset, misma concurrencia, misma duración), registras:

• p95: 1.8s (objetivo < 600ms)
• CPU de la API: ~70% con picos ocasionales
• BD: una consulta tarda 900–1100ms y el tiempo total de consulta por petición es ~1.3s

Ahora reúne evidencia. Una traza rápida muestra que el endpoint ejecuta una consulta principal de orders y luego recorre y busca items relacionados por cada order. También notas que la respuesta JSON es grande, pero el tiempo de BD domina.

Convierte eso en una lista de hipótesis a probar:

• Una consulta lenta necesita un índice.
• Consultas N+1 multiplican el tiempo en BD.
• La serialización es lenta por un payload enorme.
• Contención de locks frena lecturas durante escrituras.

Pide un cambio mínimo que encaje con la evidencia más fuerte: elimina una llamada N+1 obvia trayendo items en una sola consulta por IDs de order (o añade el índice faltante si el plan muestra un full scan). Manténlo reversible y en un commit focalizado.

Re-mide con la misma prueba de carga. Resultados:

• p95: 1.8s → 720ms
• Tiempo total BD: ~1.3s → 420ms
• CPU: algo menor, pero aún con picos

Decisión: deployar el fix (victoria clara) y empezar un segundo ciclo enfocado en la brecha restante y los picos de CPU, ya que la BD dejó de ser el limitante principal.

Siguientes pasos: convierte este flujo en rutina

La forma más rápida de mejorar en investigaciones de rendimiento es tratar cada ejecución como un pequeño experimento repetible. Cuando el proceso es consistente, los resultados son más fáciles de confiar, comparar y compartir.

Una plantilla simple de una página ayuda:

• Métrica + cómo se mide (herramienta, comando, dataset)
• Línea base (números, entorno y cuándo se capturó)
• Hipótesis (una frase, comprobable)
• Cambio (diff pequeño, qué tocaste)
• Resultado (antes/después y la decisión)

Decide dónde viven estas notas para que no desaparezcan. Un lugar compartido importa más que la herramienta perfecta: una carpeta en el repo junto al servicio, un doc del equipo o notas en el ticket. La clave es la descubribilidad. Alguien debería poder encontrar "p95 se disparó tras cambio de caché" meses después.

Haz experimentos seguros una costumbre. Usa snapshots y rollback fácil para probar una idea sin miedo. Si construyes con Koder.ai, Planning Mode puede ser un lugar conveniente para esbozar el plan de medición, definir la hipótesis y mantener el cambio acotado antes de generar un diff preciso y re-medir.

Establece una cadencia. No esperes a incidentes. Añade pequeñas comprobaciones de rendimiento tras cambios como nuevas consultas, endpoints, payloads más grandes o actualizaciones de dependencias. Un chequeo de 10 minutos ahora puede ahorrarte un día de adivinanzas después.