Primeros Pasos con Ralph Wiggum Parte 1: Introducción y Fundamentos

Estás mirando una tarea de migración tediosa—200 archivos de test que necesitan convertirse de Jest a Vitest. Los patrones están claros. El trabajo es mecánico. Pero te va a llevar todo el día.

O podrías escribir un comando, irte a comer, y volver para encontrarlo hecho.

Eso es Ralph Wiggum. Y una vez que lo uses, te preguntarás cómo trabajabas sin él.

¿Qué es Claude Code?

Claude Code es la CLI oficial de Anthropic para Claude—un asistente de programación basado en terminal que puede leer, escribir y editar archivos en tu codebase. A diferencia de las interfaces de chat, Claude Code trabaja directamente con tus archivos locales, ejecuta comandos y se integra en tu flujo de trabajo de desarrollo. Para una introducción completa, consulta Claude Code Mastery Parte 1: Primeros Pasos.

¿Qué es Ralph Wiggum?

Ralph es un plugin de Claude Code que convierte tu asistente de IA en un agente de programación autónomo. En vez del habitual ida y vuelta—prompt, revisar, prompt, revisar—le das a Ralph una tarea y te vas. Trabaja hasta que el trabajo esté realmente terminado.

La filosofía es simple: Iteración > Perfección. No intentes acertarlo en el primer prompt. Deja que el bucle se encargue.

Como dice Geoffrey Huntley, el creador de la técnica: "Ralph es un bucle Bash." Es literalmente lo que es—un while true que alimenta a Claude con el mismo prompt hasta que se cumplen los criterios de finalización.

Así funciona la mecánica:

1. Le das a Claude una tarea con criterios de finalización claros
2. Claude trabaja en ella e intenta salir cuando está "terminado"
3. Un Stop hook intercepta y comprueba: ¿realmente está terminado? (Los hooks son acciones automatizadas que se ejecutan en puntos específicos del ciclo de vida de Claude—consulta Mastery Parte 3 para más detalles)
4. Si no, el mismo prompt se alimenta de nuevo
5. Claude ve su trabajo previo en los archivos
6. El bucle continúa hasta completarse de verdad

¿La clave? El prompt nunca cambia—pero el codebase sí. Cada iteración construye sobre la anterior. Claude lee su propio trabajo previo y lo mejora.

Por Qué Esto Importa

Esto no es teórico. Los desarrolladores están ejecutando sesiones autónomas de 14 horas que migran codebases enteros. Geoffrey Huntley ejecutó un bucle de 3 meses que construyó un lenguaje de programación. VentureBeat llamó a Ralph "el nombre más grande en IA ahora mismo."

El plugin fue formalizado por Boris Cherny, Head de Claude Code en Anthropic. Es oficial. Está listo para producción. Y está cambiando cómo trabajan los desarrolladores serios.

Primeros Pasos (5 Minutos)

Paso 1: Instala la Dependencia

Ralph necesita jq para procesamiento JSON. Instálalo primero:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Windows: Usa WSL o descárgalo de https://stedolan.github.io/jq/

Paso 2: Instala el Plugin

Dentro de Claude Code, ejecuta /plugin para abrir la interfaz de descubrimiento de plugins. Busca "ralph" y selecciona ralph-loop de los plugins oficiales.

O instala directamente con:

/plugin install ralph-loop@claude-plugins-official

Paso 3: Configura los Permisos

Aquí es donde la mayoría se traba: Ralph se ejecuta de forma autónoma, lo que significa que no puede pararse y preguntarte "¿esto está bien?" por cada edición de archivo. Si no configuras los permisos, el bucle se rompe en el momento en que Claude encuentra un prompt de permisos.

Opción A: Pre-aprobar en configuración (recomendado)

Añade las herramientas que Ralph necesita a tu .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "Bash(npm:test *)",
      "Bash(npm:run build *)",
      "Bash(git:add *)",
      "Bash(git:commit *)"
    ]
  }
}

Entendiendo la sintaxis de permisos: El patrón Bash(npm:test *) significa "permitir cualquier comando Bash que empiece con npm test". El * actúa como comodín. Esto le da a Ralph permiso para ejecutar tests sin preguntarte cada vez. Consulta Mastery Parte 3: Configuración de Proyecto para detalles completos sobre patrones de permisos.

Opción B: Usa flags de permisos

Para tareas de larga duración en un entorno aislado, puedes saltarte los prompts de permisos completamente:

claude --dangerously-skip-permissions
# o
claude --permission-mode acceptEdits

Advertencia: Solo usa --dangerously-skip-permissions en entornos aislados (contenedores, VMs, instancias cloud desechables). Le da a Claude acceso completo a tu sistema de archivos.

Como Boris Cherny señala, para tareas muy largas querrás usar --permission-mode=acceptEdits o --dangerously-skip-permissions en un sandbox para que Claude no se quede bloqueado esperándote.

Opción C: Sandboxing Completo (Recomendado para Tareas de Larga Duración)

Para trabajo autónomo serio, el sandboxing integrado de Claude Code aísla a Ralph mientras permite las operaciones necesarias. Actívalo ejecutando /sandbox en Claude Code, lo que proporciona aislamiento de sistema de archivos y red a nivel de SO.

También puedes configurar reglas de permisos en .claude/settings.json para controlar a qué puede acceder Ralph:

{
  "permissions": {
    "allow": [
      "WebFetch(domain:registry.npmjs.org)",
      "WebFetch(domain:github.com)"
    ],
    "deny": [
      "Bash(sudo:*)",
      "Bash(docker:*)",
      "Read(./.env)",
      "Read(~/.ssh/**)"
    ]
  }
}

Personaliza las listas de allow/deny según las necesidades de tu proyecto. Consulta la guía de JeredBlu para más ejemplos de configuración.

Paso 4: Ejecuta Tu Primer Bucle

Empieza con algo pequeño. Aquí tienes un primer experimento seguro:

/ralph-loop "Add JSDoc comments to all exported functions in src/utils.ts. Output <promise>DONE</promise> when complete." --completion-promise "DONE" --max-iterations 10

Míralo trabajar. Revisa los commits. Familiarízate con el ritmo.

Los Dos Parámetros Que Importan

--max-iterations es tu red de seguridad. Configúralo siempre. El valor por defecto es ilimitado, lo que significa que Ralph correrá para siempre si la promesa de finalización nunca se activa.

Empieza pequeño. 10-20 iteraciones para tus primeros experimentos. Un bucle de 50 iteraciones en un codebase grande puede costar $50-100+ en créditos de API.

--completion-promise le dice a Ralph cuándo parar. Es coincidencia exacta de cadena—Claude debe producir este texto preciso para señalar la finalización.

/ralph-loop "<tu tarea>" --max-iterations 30 --completion-promise "TASK COMPLETE"

Plugin vs Bucle Bash vs TUI: Cuál Usar

Hay tres formas de ejecutar Ralph:

Método Plugin (/ralph-loop)

• Se ejecuta en una sola ventana de contexto
• El más fácil de configurar—cero configuración
• Bueno para tareas de menos de 20-30 iteraciones

Método Bucle Bash

• Lanza una ventana de contexto nueva por iteración
• Previene la saturación del contexto y las alucinaciones
• Requiere configuración manual de prompt y archivos

Ralph TUI (cubierto en la Parte 3)

• Contexto nuevo por iteración (como el bucle bash)
• Creación de PRD integrada, seguimiento de tareas y panel de monitoreo
• Se encarga de toda la gestión de prompts y archivos por ti
• Lo mejor para builds serios de larga duración

¿Qué es una ventana de contexto? La ventana de contexto es la memoria de trabajo de Claude—todo lo que Claude sabe sobre tu conversación debe caber aquí (~200K tokens). A medida que trabajas, se llena con tus prompts, código y respuestas de Claude. Cuando está llena, Claude empieza a olvidar detalles anteriores. Consulta Mastery Parte 2: Modelo Mental para una explicación más profunda.

Aquí tienes un ejemplo mínimo de bucle bash:

#!/bin/bash
# loop.sh - Run this instead of the plugin for long tasks
for ((i=1; i<=30; i++)); do
  echo "=== Iteration $i ==="
  result=$(claude -p "$(cat PROMPT.md)" --output-format text 2>&1) || true
  echo "$result"

  if [[ "$result" == *"ALL TASKS COMPLETE"* ]]; then
    echo "Done after $i iterations"
    exit 0
  fi
done

Como JeredBlu señala, el método de bucle bash es "fundamentalmente mejor para tareas de larga duración" porque cada iteración empieza fresca. El plugin ejecuta todo en un solo contexto, lo que puede llevar a un rendimiento degradado después de 30-40 iteraciones.

Mira implementaciones reales: Explora configuraciones completas de Ralph de la comunidad:

• snarktank/ralph — ralph.sh, prompt.md y AGENTS.md completos
• ClaytonFarr/ralph-playbook — Plantillas PROMPT_plan.md y PROMPT_build.md
• frankbria/ralph-claude-code — Implementación con detección inteligente de salida

¿No usas Claude Code? Ralph funciona con otras herramientas también:

• ralph-wiggum-cursor — Integración con Cursor IDE con seguimiento de tokens
• aymenfurter/ralph — Extensión de VS Code con panel de control visual
• opencode-ralph-wiggum — OpenCode con detección de bloqueos

Recomendación: Empieza con el plugin para aprender los conceptos. Para tareas de larga duración en producción, usa Ralph TUI—te da los beneficios del enfoque de bucle bash sin la configuración manual. Consulta la Parte 3 para la guía completa de TUI.

Escribiendo Prompts Que Funcionan

Esta es la diferencia entre un prompt que gira para siempre y uno que termina limpiamente:

Prompt malo (finalización vaga):

Make the code better.

Prompt bueno (específico y testeable):

Add comprehensive error handling to src/api/users.ts.

Requirements:
- Wrap all async operations in try/catch
- Return proper HTTP status codes
- Log errors with context
- Add input validation for all endpoints

Run tests after each change. Fix any failures before moving on.

When ALL tests pass, output: <promise>COMPLETE</promise>

El buen prompt tiene:

• Alcance claro — archivo específico, cambios específicos
• Criterios testeables — "los tests pasan" es binario, no subjetivo
• Puertas de calidad integradas — "arregla los fallos antes de continuar"
• Señal de finalización explícita — texto exacto a producir cuando termine

Cuándo Usar Ralph (Y Cuándo No)

Ralph destaca en:

• Refactoring mecánico — Jest → Vitest, CommonJS → ESM
• Añadir tests — "Lleva la cobertura al 80% en este módulo"
• Operaciones CRUD — "Añade endpoints de gestión de usuarios con validación"
• Documentación — "Añade JSDoc a todas las funciones públicas"
• Migraciones — "Actualiza todos los imports para usar alias de rutas"

No uses Ralph para:

• Decisiones estéticas — "Haz la UI más bonita" no es testeable
• Ediciones de un solo paso — Si te lleva 30 segundos manualmente, hazlo tú
• Debugging en producción — Necesitas contexto y juicio, no iteración
• Objetivos poco claros — "Mejóralo" girará para siempre

La regla general: Si puedes escribir un test automatizado para "terminado," Ralph puede hacerlo. Si la finalización requiere juicio humano, hazlo tú mismo.

La Filosofía Ralph

The Ralph Playbook documenta cuatro principios fundamentales que hacen que esto funcione:

1. Iteración > Perfección — No intentes clavarlo en el primer prompt. Deja que el bucle refine.
2. Los Fallos Son Datos — Cuando Ralph falla, aprendes a escribir mejores prompts.
3. La Habilidad del Operador Importa — La calidad de tu prompt determina la tasa de éxito de Ralph.
4. La Persistencia Gana — El bucle maneja los reintentos automáticamente. Tú solo defines "terminado."

El mantra de la comunidad: "Mejor fallar predeciblemente que tener éxito impredeciblemente."

Monitorizando Bucles de Larga Duración

Cuando Ralph se ejecuta durante períodos extendidos, querrás visibilidad. Ralph TUI te da un panel en tiempo real: cuenta de iteraciones, tarea actual, uso de tokens y controles de teclado para pausar o detener.

Cubrimos la monitorización en detalle en la Parte 3: Monitoreo con Ralph TUI.

Qué Viene Después

Tienes Ralph instalado. Entiendes el bucle. Sabes cuándo usarlo y cuándo hacer las cosas manualmente.

Pero solo hemos arañado la superficie.

En la Parte 2: La Metodología de Tres Fases, cubriremos el flujo de trabajo profesional—prompts separados para planificación y construcción, archivos de especificación que guían proyectos de varios días, y las técnicas que hacen que los builds autónomos de larga duración realmente funcionen. Aquí es donde Ralph pasa de "herramienta útil" a "multiplicador de fuerza."

Glosario

¿Nuevo en Claude Code? Aquí tienes los términos clave que encontrarás a lo largo de esta serie:

Ventana de contexto — La memoria de trabajo de Claude. Todo lo que Claude sabe sobre tu conversación debe caber aquí (~200K tokens). Más información

Backpressure — Validación automatizada (tests, lints, comprobaciones de tipos) que rechaza el trabajo malo, forzando a Claude a iterar hasta que esté correcto

Promesa de finalización — Texto exacto que Claude debe producir para señalar que la tarea está completa. Ralph usa coincidencia de cadenas para detectarlo

Iteración — Un ciclo completo de pensar-actuar-observar-corregir. Una tarea puede requerir múltiples iteraciones

Subagente — Worker de IA especializado con contexto independiente que se ejecuta en paralelo. Más información

MCP — Model Context Protocol. Conecta a Claude con servicios externos como bases de datos, APIs y automatización del navegador. Más información

Ultrathink — Palabra clave que asigna el presupuesto máximo de pensamiento (~32K tokens) para razonamiento complejo. Más información