Usa Claude Code en investigaciones de rendimiento con un ciclo repetible: medir, formular una hipótesis, cambiar lo mínimo y volver a medir antes de desplegar.
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:
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.
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:
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.
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:
Con estas reglas puedes probar ideas sin mover la meta.
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:
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.
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.
Usa este formato:
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.
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:
Si no puede nombrar una métrica específica, ubicación y resultado esperado, vuelves a adivinar.
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:
"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.
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:
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.
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:
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.
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:
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.
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:
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:
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:
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.
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:
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.
Empieza con un número que coincida con la queja, normalmente latencia p95 para un endpoint e input específicos. Registra una línea base bajo las mismas condiciones (tamaño de datos, concurrencia, caché frío/caliente), luego cambia una cosa y vuelve a medir.
Si no puedes reproducir la línea base, todavía no estás midiendo: estás adivinando.
Una buena línea base incluye:
Escríbelo antes de tocar el código para no mover el objetivo.
Los percentiles muestran la experiencia de usuario mejor que una media. p50 es lo “típico”, pero los usuarios se quejan de la cola lenta, que es p95/p99.
Si p50 mejora pero p99 empeora, el sistema puede sentirse más lento aunque la media parezca mejor.
Usa tiempos simples cuando preguntas “¿está más lento y cuánto?” Usa perfilado cuando preguntas “¿a dónde se va el tiempo?”
Un flujo práctico: confirma la regresión con tiempos de petición, y solo perfila después de saber que la ralentización es real y está acotada.
Elige una métrica primaria y trata el resto como guardarraíles. Un conjunto común es:
Esto evita “ganar” una gráfica mientras causas timeouts, crecimiento de memoria o peor latencia de cola.
Escribe una hipótesis de una oración ligada a la evidencia y a una predicción:
Si no puedes nombrar la evidencia y el movimiento esperado de la métrica, la hipótesis no es comprobable todavía.
Hazlo pequeño, enfocado y fácil de revertir:
Los diffs pequeños hacen que la siguiente medición tenga sentido y reducen la probabilidad de romper comportamiento mientras persigues velocidad.
Vuelve a ejecutar exactamente la misma receta de prueba (mismas entradas, entorno y forma de carga). Luego comprueba regresiones que no aparecen en el número principal:
Si los resultados son ruidosos, toma más muestras o revierte y ajusta el experimento.
Dale evidencia concreta y obliga a que todo sea testable:
Si la salida no incluye una métrica específica y un plan de re-prueba, estás volviendo a la adivinanza.
Para cuando detenerte:
El trabajo de rendimiento tiene costo de oportunidad. El ciclo (medir → hipotetizar → cambiar → re-medir) ayuda a dedicar tiempo donde los números lo demuestran.
