Recursos
- autoresearch-cli en GitHub - la herramienta en sí. 35 estrellas, licencia MIT, publicada por primera vez el 10 jun 2026 y todavía en actualización (último commit el 20 jun 2026).
- Instala la skill del agente - el SKILL.md que enseña a tu agente a ejecutar el bucle.
- Plantilla de ajustes - el bloque de hooks que pegas en tu proyecto para que el bucle siga activo.
- pi-autoresearch (el proyecto original) - el original con 7.1K estrellas del que se extrajo esto. La misma idea, vinculada a otro entorno de ejecución.
- Caso práctico: reducir un prompt de producción un 28% - un recorrido real por una ejecución de optimización autónoma.
Cómo funciona
Piensa en esto como un pequeño árbitro que se sitúa entre tu agente de IA y tu código.
Le das al agente una tarea: mejorar una cifra.
Esa cifra puede ser lo rápido que se ejecuta un script, los pocos tokens que usa un prompt o cuántas pruebas se superan.
Después el agente sigue un bucle: probar un cambio, medirlo de verdad, conservarlo si la cifra mejoró, descartarlo si no y repetir.
La razón de existir de la herramienta es que no se puede confiar en que un agente evalúe su propio trabajo.
Por eso el agente nunca toca las cifras ni ejecuta git a mano.
Solo le pide a la herramienta: «ejecuta mi prueba de rendimiento» y «registra este resultado».
La herramienta se encarga de medir con honestidad, conservar, revertir y llevar el registro, para que el agente pueda funcionar sin supervisión durante horas y te despiertes con un resultado en el que realmente puedes confiar, en lugar de un registro de chat lleno de afirmaciones seguras.
Esa separación es el objetivo. Un agente al que dejas evaluarse siempre informará de avances, porque informar de avances es el camino fácil. Quítale el control de las cifras y el bucle dejará de ser una impresión para convertirse en un experimento.
Una cosa que esto NO es: no es un asistente de investigación web que lee artículos y te escribe un informe. Aquí «investigación» significa un bucle de experimentos científicos sobre tu propio código. Si quieres investigación web, mira gpt-researcher o local-deep-research.
Paso 1: identifica cuándo es la herramienta adecuada
Esto sirve para un tipo concreto de problema: tienes algo medible que quieres mejorar y estás dispuesto a dejar que un agente trabaje insistentemente en ello.
Buenos casos: acelerar una función lenta, reducir el número de tokens de un prompt, aumentar la tasa de éxito de un conjunto de pruebas, reducir un paquete o pulir un CLAUDE.md para que el agente lo siga mejor.
Un mal caso es cualquier cosa vaga sin una cifra, como «mejora el código». El bucle no tiene una medida que optimizar, así que no puede funcionar.
Si puedes escribir una cifra y una forma de calcularla, puedes empezar.
Paso 2: instala la herramienta
La herramienta es un programa de línea de comandos (un programa que ejecutas escribiendo su nombre en la terminal, la ventana de texto donde escribes comandos).
La instalas una vez, de forma global, con npm (el gestor de paquetes que viene con Node).
npm install -g autoresearch-cliNecesitas Node en su versión 18 o posterior.
El resultado correcto es que el comando termine sin errores y autoresearch --help muestre una lista de comandos.
Paso 3: instala la skill del agente
La herramienta es solo la mitad. La otra mitad es una skill: un archivo breve de instrucciones que enseña al agente a dirigir el bucle.
Aquí una skill es simplemente un archivo Markdown que el agente lee para aprender una capacidad nueva.
npx skills add https://github.com/trotsky1997/autoresearch-cli/tree/main/skill --skill autoresearchSi quieres leerla antes de instalarla, cambia --skill autoresearch por --list para verla.
El resultado correcto es que la skill aparezca en tu carpeta de skills, lista para que la use el agente.
Paso 4: conecta los hooks para que el bucle nunca se detenga
Aquí está la parte ingeniosa. Por sí solo, un agente termina su turno y se detiene.
Un bucle que se detiene después de un intento no sirve.
Por eso la herramienta incluye tres hooks (pequeños scripts que Claude Code ejecuta en momentos determinados) que mantienen el proceso en marcha.
Pega el bloque hooks de templates/claude-settings.json en el archivo .claude/settings.json de tu proyecto.
{
"permissions": { "defaultMode": "acceptEdits" },
"hooks": {
"Stop": [{ "hooks": [{ "type": "command", "command": "autoresearch hook stop --cwd \"$CLAUDE_PROJECT_DIR\"", "timeout": 15 }] }],
"SessionStart": [{ "hooks": [{ "type": "command", "command": "autoresearch hook sessionstart --cwd \"$CLAUDE_PROJECT_DIR\"", "timeout": 15 }] }],
"PreCompact": [{ "hooks": [{ "type": "command", "command": "autoresearch hook precompact --cwd \"$CLAUDE_PROJECT_DIR\"", "timeout": 15 }] }]
}
}Esto es lo que hace cada uno, en palabras sencillas.
El hook Stop impide que termine el turno e impulsa la siguiente iteración. Este es el verdadero motor para «no detenerse nunca», no una línea de un prompt que pide al agente que siga.
El hook SessionStart vuelve a incorporar el estado del bucle para que, si se borra la memoria del agente a mitad de la ejecución, continúe exactamente donde lo dejó.
El hook PreCompact es una comprobación de seguridad antes de que el agente comprima su memoria; el estado real vive en el disco, así que no se pierde nada.
El resultado correcto es que los hooks se interpreten sin problemas al iniciar Claude Code (sin errores de configuración).
Paso 5: escribe tu script de medición
Este es el paso más importante y el que la gente hace con prisas.
El bucle es tan honesto como tu prueba de rendimiento. Defines un archivo que ejecuta lo que quieres medir y muestra la puntuación.
Guárdalo en .auto/measure.sh (o define una receta just measure si usas justfiles).
La única regla: cada cifra que quieras registrar debe mostrarse en una línea METRIC name=value. Se ignora cualquier otra cosa de la salida.
#!/usr/bin/env bash
## .auto/measure.sh: runs the thing, prints the score the loop optimizes.
runtime=$( { /usr/bin/time -p node my-script.js ; } 2>&1 | awk '/real/ {print $2}' )
echo "METRIC runtime=$runtime"El resultado correcto es ejecutar este script a mano y ver exactamente una línea METRIC runtime=... con una cifra real.
Paso 6: añade una comprobación de corrección (esta es la red de seguridad)
La velocidad no significa nada si el cambio rompió el código.
Así que añade una comprobación separada que diga si se aprueba o se falla, independiente de la puntuación.
Guárdala en .auto/checks.sh (o en una receta just check). El tiempo empleado aquí se excluye a propósito de tu métrica de velocidad.
#!/usr/bin/env bash
## .auto/checks.sh: must exit non-zero if the change is broken.
npm testSi falla, el bucle registra el intento como checks_failed y lo revierte, así que nunca se conserva una versión más rápida pero rota.
El resultado correcto es que la comprobación se supere en tu código actual antes de iniciar el bucle.
Paso 7: inicia la ejecución
Ahora diriges al agente hacia la tarea. Primero el agente (o tú) define el objetivo.
autoresearch init --name speed-up-parser --metric runtime --unit seconds --direction lower--direction lower significa que menos es mejor (para una tasa de éxito usarías higher).
Después le dices a tu agente en Claude Code qué quieres y lo dejas trabajar. Basta con una instrucción sencilla: «Usa la skill autoresearch para reducir la métrica runtime de mi analizador. Ejecuta hasta agotar las ideas razonables y después entrega el resultado».
Por detrás, el agente repite un ciclo: elegir un cambio, editar código, llamar a autoresearch run para medirlo y después a autoresearch log para conservarlo o descartarlo.
autoresearch run
autoresearch log --metric runtime --status keep --desc "cache the compiled regex"keep crea un commit del cambio automáticamente. discard, crash y checks_failed lo revierten automáticamente. Tú nunca ejecutas git.
El resultado correcto es que el agente repita el ciclo por su cuenta, aparezcan commits para las mejoras y tu árbol de trabajo quede limpio después de los intentos fallidos.
Paso 8: lee la cifra de confianza antes de confiar en una mejora
Las pruebas de rendimiento tienen ruido. Ejecutar el mismo código dos veces da tiempos ligeramente distintos.
Por eso la herramienta informa de una cifra de confianza: cuánto representa la mejora frente al ruido entre ejecuciones.
Una interpretación aproximada: una confianza de 2 o más significa que la mejora probablemente sea real; por debajo de 1, probablemente veas ruido disfrazado de mejora.
Si una «mejora» tiene poca confianza, mírala con recelo y deja que el bucle vuelva a medir.
El resultado correcto es conservar solo las mejoras de alta confianza y no dejarte engañar por una oscilación de 0.2 segundos.
Paso 9: evita el gran peligro, sobreajustar tu prueba de rendimiento
Esta es la lección que los profesionales aprendieron por las malas.
Un operador ejecutó esto durante 8 rondas para mejorar su CLAUDE.md, puntuando cada versión con tareas extraídas de pull requests reales.
La mejor versión que encontró aun así empeoró con un conjunto nuevo de tareas que el bucle nunca había visto.
Eso es sobreajuste: el agente aprende a sobresalir en tu prueba exacta en lugar de mejorar de verdad. Dale una sola cifra a un optimizador incansable y encontrará el atajo para moverla, incluidas formas que no significan nada fuera de la prueba.
La solución es un conjunto reservado. Conserva un segundo conjunto de tareas o entradas que el bucle de optimización nunca use para medir.
Cuando el bucle diga que terminó, ejecuta una vez la versión ganadora con ese conjunto intacto. Si no se sostiene ahí, la mejora era falsa.
El resultado correcto es una versión ganadora que mejore tanto en la prueba de rendimiento como en el conjunto reservado que mantuviste oculto.
Paso 10: usa el prompt para poner en marcha tu propio bucle
Lo más difícil es escribir un contrato de medición claro. Así que encarga ese trabajo a tu agente.
Pega el prompt de la pestaña Prompt de arriba en Claude Code.
Sustituye [WHAT YOU WANT TO OPTIMIZE] por tu objetivo en una línea (por ejemplo, «reducir el tiempo de respuesta del endpoint /search»).
Sustituye [HOW TO RUN IT] por el comando que ejecuta tu código y [THE NUMBER] por la única métrica que se debe seguir.
El agente escribirá .auto/measure.sh y .auto/checks.sh, ejecutará autoresearch init por ti e iniciará el bucle.
El resultado correcto es una prueba de rendimiento que funcione y un bucle en marcha sin que escribas ningún script de shell a mano.
Paso 11: recoge las ramas entregadas
Cuando el agente decide que terminó, no te deja un montón de commits sin más.
Agrupa los cambios conservados en ramas limpias y separadas, una por mejora independiente, usando finalize/finalize.sh.
Después crea un archivo .auto/.done, que es la señal que detiene definitivamente el bucle.
Revisas cada rama como cualquier pull request normal e integras las que quieras.
El resultado correcto es una lista breve de ramas con nombre, cada una revisable por separado, en lugar de un único enredo.
Paso 12: verifica que realmente se ejecutó
Para confirmar que todo funcionó, mira en la carpeta .auto/, que es la única fuente de verdad de la ejecución.
.auto/log.jsonl es el historial completo: cada intento, su métrica y si se conservó o revirtió. Léelo para ver las decisiones reales del agente.
Si el bucle «terminó» al instante, la causa habitual es un script de medición que no mostró ninguna línea METRIC name=value, por lo que la herramienta no tenía nada que puntuar. Ejecuta .auto/measure.sh a mano y comprueba el formato de salida.
El otro fallo habitual es que el bucle nunca avance porque no se pegaron los hooks en .claude/settings.json; sin el hook Stop no hay un relevo que impulse la siguiente iteración.
El resultado correcto es un log.jsonl con varias entradas de conservación y descarte, un .auto/.done final y ramas entregadas que mejoren tanto tu prueba de rendimiento como tu conjunto reservado.
