Ralph Wiggum en Claude Code: la guía del bucle autónomo

TL;DR

• Ralph Wiggum es una técnica de desarrollo autónomo: se le da al agente el mismo prompt una y otra vez hasta que la tarea está terminada de verdad. El nombre viene del personaje de Los Simpson, por la insistencia ingenua pero incansable.
• En su forma original, de Geoffrey Huntley (julio de 2025), es un bucle de Bash de una línea: while :; do cat PROMPT.md | claude ; done.
• Anthropic lo empaquetó como plugin oficial de Claude Code. Un hook Stop intercepta la salida de la sesión y vuelve a inyectar el prompt, conservando los archivos y el historial de git entre iteraciones.
• Se controla con dos parámetros: --max-iterations (el límite de seguridad real) y --completion-promise (una cadena exacta que el agente solo debe emitir cuando ha acabado).
• Funciona bien en proyectos nuevos con criterios de éxito verificables por tests. Funciona mal —y sale caro— en código legado, lógica de seguridad, pagos y decisiones de arquitectura.

Qué es la técnica Ralph Wiggum

Ralph Wiggum es un patrón de trabajo con agentes de código, no un producto. La idea cabe en una frase: en vez de pedirle una cosa al agente y revisar el resultado, se le repite el mismo prompt en bucle hasta que se cumple una condición de finalización o se agota un número máximo de intentos.

Cada iteración arranca con el contexto limpio, pero el estado del trabajo sigue ahí: los archivos modificados, los commits, los tests que pasan y los que no. El repositorio es la memoria. El agente lee lo que hizo su iteración anterior, detecta lo que falta y sigue.

El nombre es una broma que describe bien el mecanismo. Ralph Wiggum no es el personaje más brillante de Los Simpson, pero tampoco se rinde. La apuesta de la técnica es que la persistencia con verificación gana a la inteligencia sin verificación.

De dónde viene

Geoffrey Huntley publicó la idea en julio de 2025 en su artículo Ralph Wiggum as a "software engineer". Su definición es literal:

"Ralph is a technique. In its purest form, Ralph is a Bash loop."

while :; do cat PROMPT.md | claude ; done

Eso es todo el invento original: un fichero PROMPT.md y un while infinito. Huntley documentó resultados llamativos con él —seis repositorios en una noche durante un hackathon de Y Combinator, y un contrato de 50.000 USD entregado con 297 USD de coste de API—, siempre en proyectos nuevos y siempre con un ingeniero senior dirigiendo el prompt.

Medio año después la técnica llegó a la caja de herramientas oficial: Anthropic publicó el plugin ralph-wiggum dentro del repositorio de Claude Code, firmado por Daisy Hollman. Ahí es donde la mayoría de la gente se lo encuentra hoy, y por eso se ve indistintamente como "Ralph Wiggum", "Ralph loop" o simplemente "Ralph".

Cómo funciona el plugin por dentro

El plugin no lanza un bucle de shell por fuera de Claude Code. Hace algo más fino: engancha el momento en el que la sesión intenta terminar.

1. /ralph-loop escribe un fichero de estado en .claude/ralph-loop.local.md, con tres campos en el frontmatter: iteration, max_iterations y completion_promise.
2. El plugin registra un hook de tipo Stop. Cuando Claude considera que ha acabado e intenta salir, el hook se ejecuta antes.
3. El hook lee el fichero de estado. Si no existe, la sesión termina con normalidad. Si existe, comprueba el contador y la promesa de finalización.
4. Si no se ha alcanzado max_iterations y la promesa exacta no ha aparecido, el hook bloquea la salida y vuelve a inyectar el prompt original. Los archivos y el historial de git se conservan intactos.
5. Cuando el contador llega al límite, el hook borra el fichero de estado y deja salir a la sesión.

La diferencia con el while de Bash importa. El bucle de shell arranca un proceso nuevo cada vez y pierde todo lo que no esté en disco. El hook mantiene la sesión viva y el agente ve su trabajo anterior dentro del mismo hilo. Si prefieres el aislamiento del contexto limpio, el bucle de Bash sigue siendo válido —y hay skills que lo automatizan.

El comando incluye una instrucción explícita contra la trampa más obvia del sistema:

"CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop."

Es una regla en lenguaje natural, no una garantía técnica. Conviene tenerlo presente: la promesa de finalización la emite el mismo agente al que se le pide que no mienta.

Instalación

El plugin vive en el marketplace que Anthropic distribuye con el propio repositorio de Claude Code. Dos comandos dentro de una sesión:

/plugin marketplace add anthropics/claude-code
/plugin install ralph-wiggum@claude-code-plugins

También puedes abrir /plugin y buscarlo en la interfaz. Tras instalarlo quedan disponibles tres comandos:

Si vienes de instalar skills a mano desde repositorios, el flujo de plugins es distinto y bastante más cómodo: lo cubrimos en cómo encontrar e instalar skills de Claude desde GitHub.

Los dos parámetros

/ralph-loop "Migra el módulo de facturación a la nueva API" --max-iterations 15 --completion-promise "MIGRACION COMPLETA"

• --max-iterations <n>. El tope de iteraciones. Es el mecanismo de seguridad principal, no un detalle opcional. Sin él, una tarea imposible se convierte en un bucle que consume tokens hasta agotar tu límite.
• --completion-promise "<texto>". La cadena que señala el final. La comparación es por coincidencia exacta de cadena: un acento, una mayúscula o un espacio de más y el bucle sigue. Solo admite una condición de finalización; no se pueden encadenar varias.

La combinación útil es siempre las dos juntas. La promesa define el éxito; el máximo de iteraciones define el fracaso aceptable.

Cómo escribir el prompt

El plugin es trivial. Lo que decide el resultado es el prompt. La regla práctica: si un humano no podría decidir si la tarea está terminada leyendo solo el prompt, el agente tampoco.

Un prompt que funciona tiene cuatro partes:

1. El objetivo, en una frase.
2. Los criterios de aceptación, comprobables por máquina: los tests pasan, el typecheck está limpio, el build no falla, la cobertura supera un umbral.
3. El comando exacto de verificación, para que el agente no se invente cómo comprobarlo.
4. La promesa de finalización, con el texto literal que debe emitir.

Implementa los endpoints CRUD de /api/facturas siguiendo TDD.

Criterios de aceptación:
- `npm test` pasa sin fallos
- `npm run typecheck` sin errores
- Validación de entrada en los cuatro endpoints
- Cobertura del módulo por encima del 80%

Trabaja en incrementos pequeños y haz commit después de cada test en verde.
Cuando —y solo cuando— los cuatro criterios se cumplan, escribe: MIGRACION COMPLETA

Dos patrones que ayudan mucho:

• Una spec por iteración. En vez de un objetivo grande, una carpeta specs/ con especificaciones pequeñas y un plan de implementación en disco. El agente coge la siguiente pendiente, la termina, la marca y sale. La skill ralph-wiggum del directorio monta exactamente ese esquema, con specs/, ralph_history.txt e IMPLEMENTATION_PLAN.md como estado compartido.
• TDD dentro del bucle. Test que falla, implementación, test en verde, commit. Le da al agente una señal objetiva por iteración en vez de una impresión subjetiva de progreso.

Y el patrón que casi siempre falla: objetivos abiertos del tipo "mejora el rendimiento" o "haz que el código esté más limpio". Sin condición de parada verificable, Ralph itera hasta el límite y para por agotamiento, no por éxito.

Cuándo usarlo y cuándo no

Encaja bien:

• Proyectos nuevos, desde cero, donde no hay nada que romper.
• Tareas mecánicas y repetitivas: migraciones, cobertura de tests, refactors homogéneos.
• Trabajo con verificación automática: compila, pasa tests, despliega.
• Bloques largos sin supervisión: una noche, un fin de semana.

Encaja mal:

• Código existente en producción. Huntley es tajante: "There's no way in heck would I use Ralph in an existing code base."
• Lógica sensible: autenticación, cifrado, pagos. El agente optimiza para tests en verde, y unos tests en verde sobre un diseño inseguro siguen siendo un diseño inseguro.
• Decisiones de arquitectura o de producto. Requieren criterio, y el bucle no lo tiene.
• Tareas con criterio de éxito subjetivo: "que quede bonito", "que sea más intuitivo".
• Depuración en caliente. Si necesitas el resultado ya, el bucle es el camino lento.

La expectativa realista que da el propio autor de la técnica es un 90 % de avance, no un producto terminado. Y la posibilidad de despertarte con el repositorio roto es parte del trato: trabaja siempre en una rama o en un worktree aparte.

El coste, que es la parte que sorprende

Un bucle autónomo gasta tokens a un ritmo que no se parece al de una sesión normal. Cada iteración vuelve a leer archivos, vuelve a razonar y vuelve a escribir. Diez iteraciones sobre un repositorio grande pueden costar más que una semana de uso interactivo.

Tres medidas que reducen la factura sin tocar el resultado:

• Empieza con --max-iterations bajo —cinco o diez— y súbelo cuando el prompt demuestre que converge.
• Acota el alcance. Un módulo, no el repositorio entero.
• Vigila lo que hay cargado en la sesión. Las skills y los servidores MCP conectados ocupan contexto en cada iteración, multiplicado por el número de vueltas. Es el efecto que explicamos en cuánto contexto te cuesta una skill, y en un bucle se paga tantas veces como iteraciones haya.

Alternativas dentro de Claude Code

Antes de instalar el plugin, conviene saber que parte de lo que la gente busca en Ralph ya viene de serie:

• /loop repite un prompt o un comando a intervalos, y se corta con Esc. Sirve para vigilar algo que cambia —un despliegue, una cola— más que para construir.
• /batch paraleliza cambios mecánicos repartiéndolos entre varios agentes en worktrees separados. Para una migración homogénea sobre muchos archivos suele ser mejor herramienta que un bucle secuencial.

Ralph sigue siendo la opción cuando lo que quieres es una sola tarea, iterada en profundidad, hasta una condición de finalización concreta.

Skills del directorio relacionadas

El patrón Ralph aparece empaquetado de varias formas en skills de la comunidad:

• ralph-wiggum — el bucle de Bash clásico con contexto limpio en cada iteración, specs en disco y la señal <promise>DONE</promise> solo cuando los criterios se cumplen y los tests pasan.
• ralph-loop-workflow — un bucle con preflight: antes de arrancar comprueba que cada CLI necesaria está instalada, enlazada y autenticada, y en cada vuelta verifica con typecheck, build, tests y navegador.
• ralph-tui-prd y ralph-tui-create-json — la parte de planificación: convierten una funcionalidad en un PRD con quality gates y luego en tareas del tamaño de una iteración. Es el trabajo previo que hace que un bucle converja.

Preguntas frecuentes

¿Ralph Wiggum es un plugin oficial de Anthropic? Sí. El plugin ralph-wiggum está en el repositorio oficial de Claude Code y se instala desde el marketplace que Anthropic distribuye con él. La técnica, en cambio, es anterior y externa: la creó Geoffrey Huntley en julio de 2025.

¿Cómo paro un bucle que se ha desmadrado? Con /cancel-ralph, que borra el fichero de estado en .claude/ralph-loop.local.md. Si la sesión ya no responde, borrar ese fichero a mano también corta el bucle en la siguiente salida.

¿Necesito el plugin o me vale un bucle de Bash? Las dos cosas funcionan. El bucle de Bash arranca un contexto limpio en cada vuelta y obliga a que todo el estado esté en disco, lo cual es una disciplina útil. El plugin mantiene la sesión viva y es más cómodo. Para empezar, el plugin; para proyectos largos con muchas specs, el bucle con estado en ficheros.

¿Funciona sobre un proyecto que ya existe? Puede funcionar en tareas acotadas y verificables dentro de un proyecto existente —subir cobertura de un módulo, terminar una migración mecánica—, siempre en una rama aparte. Para cambios amplios sobre código en producción, no es la herramienta.

¿Por qué el agente dice que ha terminado si no ha terminado? Porque la promesa de finalización la emite él mismo. La defensa no es confiar más en el prompt, sino que los criterios de aceptación sean comprobables por un comando: tests, typecheck, build. Si el criterio es objetivo, el agente tiene poco margen para autoengañarse.