Primeros Pasos con Ralph Wiggum Parte 2: La Metodología de Tres Fases

Instalaste Ralph, ejecutaste un loop y... ¿más o menos funcionó? Tal vez se quedó atascado. Tal vez dio vueltas en círculos. Tal vez construyó algo, pero no exactamente lo que necesitabas.

Eso es normal. Ralph sin estructura es como cualquier agente autónomo: capaz, pero sin dirección.

Esta parte cubre la Metodología de Tres Fases: un flujo de trabajo práctico para convertir ideas vagas de proyecto en código funcional mientras duermes.

La idea clave: Separa la planificación de la construcción

Geoffrey Huntley lo describe como "Un embudo con 3 Fases, 2 Prompts y 1 Loop." Aquí va el desglose:

• Fase 1: Requisitos — Tú + Claude en conversación, definiendo especificaciones y criterios de aceptación
• Fase 2: Planificación — Claude analiza las especificaciones (loop de solo lectura), genera una lista TODO priorizada
• Fase 3: Construcción — Claude implementa tareas una por una, hace commits, itera hasta terminar

La separación es crucial. Como dice The Ralph Playbook: "El prompt de PLANIFICACIÓN hace un análisis de brechas y genera una lista TODO priorizada — sin implementación, sin commits. El prompt de CONSTRUCCIÓN selecciona tareas, implementa, ejecuta tests y hace commits."

Por qué funciona: El modo de planificación evita que Claude se lance a programar antes de entender el panorama completo. El modo de construcción se mantiene enfocado en una tarea a la vez en lugar de descontrolarse con el alcance.

Fase 1: Requisitos (La parte humana)

Esta es la única fase que requiere tu participación activa. Y es donde la mayoría de la gente se salta pasos — que es exactamente por lo que sus sesiones de Ralph producen basura.

Dedica al menos 30 minutos conversando sobre requisitos con Claude antes de escribir código. En serio. Esta conversación es donde capturas esos momentos de "espera, ¿y qué pasa con..." que de otro modo descarrilarían tu build autónomo.

Qué incluir en los archivos de especificaciones

Crea archivos specs/*.md que se conviertan en la fuente de verdad. No te compliques con el formato — enfócate en la claridad:

Consejo: Si quieres un enfoque estructurado para la recopilación de requisitos, echa un vistazo al PRD Creator de JeredBlu — un sistema de prompts conversacionales que te guía para crear especificaciones completas.

specs/
├── authentication.md    # Login, JWT, sesiones
├── api-design.md        # Endpoints, formatos request/response
├── database.md          # Schema, relaciones
└── testing.md           # Requisitos de cobertura, estrategia de tests

La conversación que importa

Así fluye una buena conversación de requisitos:

Tú: "Quiero construir una REST API para gestionar todos"

Claude: "Vamos a desglosarlo. ¿Qué operaciones necesitas?"

Tú: "Operaciones CRUD - crear, leer, actualizar, eliminar todos"

Claude: "Entendido. ¿Y la autenticación? ¿Cuentas de usuario?"

Tú: "Sí, los usuarios solo deberían ver sus propios todos"

Claude: "Tiene sentido. ¿Cómo deberíamos manejar..."

Este ida y vuelta saca a la luz casos extremos en los que no pensarías solo. Después de la conversación, Claude genera especificaciones estructuradas documentando todo lo discutido.

La inversión vale la pena: 30 minutos de conversación sobre requisitos previenen horas de Ralph girando sobre objetivos ambiguos.

Fase 2: Planificación

Este es un modo separado que usa PROMPT_plan.md. Ejecutas el modo de planificación explícitamente cuando necesitas generar o regenerar tu plan de implementación.

El modo de planificación hace un análisis de brechas entre las especificaciones y el código, creando una lista TODO priorizada sin ninguna implementación ni commits.

Dos formas de ejecutar Ralph

Hay dos métodos para ejecutar loops de Ralph, y entender cuándo usar cada uno es crítico:

Método del Plugin (/ralph-loop) — Ejecuta iteraciones dentro de una sola ventana de contexto. Más fácil de configurar, bueno para tareas cortas (menos de 20-30 iteraciones).

Método del Bash Loop (loop.sh) — Lanza una instancia fresca de Claude por iteración. Como explica la guía original de Geoffrey Huntley, cada iteración "carga determinísticamente los mismos archivos y lee el estado actual del disco." Esto previene la inflación de contexto y las alucinaciones que pueden ocurrir al ejecutar muchas iteraciones en un solo contexto. Ver ejemplos de la comunidad: snarktank/ralph.sh, frankbria/ralph_loop.sh, gist de peteristhegreat.

Por qué importa el contexto fresco: El plugin ejecuta todo en una sola ventana de contexto, que se llena con el tiempo. Después de 30-40 iteraciones, Claude puede empezar a ignorar partes de tu prompt o tomar decisiones inconsistentes. El método del bash loop evita esto empezando fresco cada vez — el único estado compartido es lo que está escrito en disco (tu código, IMPLEMENTATION_PLAN.md y progress.txt). Para técnicas avanzadas, consulta Advanced Context Engineering for Coding Agents.

Te mostraremos cómo crear loop.sh en la sección El Script del Bash Loop más abajo.

Cómo ejecutar el modo de planificación

Para la planificación, el método del plugin funciona bien ya que solo necesitas ~5 iteraciones (la inflación de contexto no es una preocupación):

/ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"

O usando el bash loop (ver El Script del Bash Loop más abajo):

./loop.sh plan

Plantilla de PROMPT_plan.md

Aquí está la plantilla completa para el modo de planificación. Para ejemplos reales, consulta PROMPT_plan.md de ClaytonFarr o prompt.md de snarktank.

# PLANNING MODE

You are in PLANNING mode. Your job is analysis, not implementation.

## Your Task
1. Read all files in specs/
2. Review the existing codebase in src/
3. Perform gap analysis between requirements and current implementation
4. Create/update IMPLEMENTATION_PLAN.md with prioritized tasks

## Task Structure
Each task in the plan should include:
- Unique ID (e.g., TASK-001, TASK-002)
- Priority level (high/medium/low)
- Clear description (what needs to be built)
- Acceptance criteria (how you'll know it's done)
- Required tests (specific test files or patterns)
- Dependencies (tasks that must complete first)

## File Organization
Organize tasks by priority:
- High Priority: Critical path items
- Medium Priority: Important but not blocking
- Low Priority: Nice-to-haves

## Critical Rules
- DO NOT write any code
- DO NOT make any commits
- DO NOT implement features
- DO NOT run tests or builds
- ONLY analyze and plan

When complete, output "PLAN COMPLETE"

Mira ejemplos reales: Explora archivos de prompt reales de la comunidad:

• snarktank/ralph — prompt.md completo con AGENTS.md
• ClaytonFarr/ralph-playbook — Plantilla PROMPT_plan.md
• frankbria/ralph-claude-code — Implementación con detección de salida

Qué produce la planificación

El modo de planificación genera:

IMPLEMENTATION_PLAN.md - Tu lista TODO viva

Ejemplo de estructura:

# Implementation Plan

## High Priority

### TASK-001: User Authentication
- **Status**: pending
- **Description**: Implement JWT-based auth with login/logout
- **Acceptance Criteria**:
  - User can register with email/password
  - User can login and receive JWT token
  - Protected routes require valid JWT
- **Tests**: `auth.test.ts`
- **Dependencies**: none

### TASK-002: Todo CRUD Endpoints
- **Status**: pending
- **Description**: Create POST, GET, PUT, DELETE endpoints for todos
- **Acceptance Criteria**:
  - POST /api/todos creates a todo
  - GET /api/todos returns user's todos
  - PUT /api/todos/:id updates a todo
  - DELETE /api/todos/:id deletes a todo
- **Tests**: `todos.test.ts`
- **Dependencies**: TASK-001

## Medium Priority

### TASK-003: Input Validation
- **Status**: pending
- **Description**: Add Zod validation for all endpoints
...

Importante: Como señala The Ralph Playbook, el plan es desechable. Si se vuelve obsoleto o impreciso, bórralo y regénéralo ejecutando el modo de planificación de nuevo.

Fase 3: Construcción

Este es el modo de loop continuo usando PROMPT_build.md. Aquí es donde Ralph brilla — implementando tareas de forma autónoma mientras duermes.

¿Qué es la contrapresión (backpressure)? En la metodología Ralph, la contrapresión se refiere a mecanismos de validación automatizados — tests, verificación de tipos, linters, builds — que rechazan trabajo inaceptable. En lugar de prescribir exactamente cómo Claude debería implementar algo, creas "compuertas" que rechazan resultados malos. Los tests que fallan obligan a Claude a iterar hasta que el código sea correcto. Esta es la idea central detrás de los loops de codificación autónoma.

El modo de construcción asume que el plan existe, toma una tarea a la vez, la implementa con tests, hace commit, y luego itera con contexto fresco.

Cómo ejecutar el modo de construcción

Inicio rápido con el plugin:

/ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"

Para builds de larga duración (recomendado): Usa el método del bash loop para contexto fresco por iteración. Después de configurar loop.sh (mostrado abajo):

./loop.sh              # El modo por defecto es construcción
./loop.sh build 100    # Con límite de iteraciones personalizado

Plantilla de PROMPT_build.md

Aquí está la plantilla completa para el modo de construcción. Para ejemplos reales, consulta PROMPT_build.md de ClaytonFarr o PROMPT.md de frankbria.

# BUILDING MODE

You are in BUILDING mode. Your job is implementation with quality gates.

## Your Task Loop
For each iteration:
1. Read IMPLEMENTATION_PLAN.md and progress.txt
2. Pick the SINGLE highest priority task with status: pending
3. Study existing code before implementing
4. Implement the feature completely
5. Write comprehensive tests
6. Run all tests and type checks: npm test && npm run type-check
7. If tests fail, fix them immediately—DO NOT proceed
8. When all tests pass:
   - Commit with descriptive message format: "feat(area): description"
   - Update task status to completed in IMPLEMENTATION_PLAN.md
   - Append learnings to progress.txt with timestamp

## Critical Rules
- Work on ONE task at a time—no exceptions
- NEVER commit failing tests
- NEVER skip test execution
- Tests are your backpressure—respect them
- Each commit must be atomic and working
- Don't add features not in the plan
- Don't refactor unrelated code

## Backpressure Enforcement
Tests MUST pass before committing:
```bash
npm test && npm run type-check && npm run lint
```

If any check fails, fix it in the same iteration.

## Progress Tracking
After completing each task, append to progress.txt:
```
[YYYY-MM-DD HH:MM] Completed TASK-XXX: Task Title
- What was implemented
- Key decisions made
- Challenges encountered
- Learnings for next tasks
```

When all tasks show status: completed, output "ALL TASKS COMPLETE"

Mira ejemplos reales: Explora implementaciones reales de PROMPT_build.md:

• ClaytonFarr/ralph-playbook — Plantilla PROMPT_build.md
• frankbria/ralph-claude-code — Implementación con detección inteligente de salida
• mikeyobrien/ralph-orchestrator — Implementación de orquestación mejorada

Profundización: El artículo Don't Waste Your Back Pressure de Geoffrey Huntley explica por qué los mecanismos de validación y rechazo son críticos para los loops autónomos.

El Script del Bash Loop

Aquí tienes un script loop.sh que soporta tanto el modo de planificación como el de construcción. Este patrón viene de la guía de JeredBlu y el enfoque original de Geoffrey Huntley:

#!/bin/bash
# loop.sh - Fresh context per iteration

MODE=${1:-build}  # Default to build mode
MAX_ITERATIONS=${2:-50}

if [[ "$MODE" == "plan" ]]; then
  PROMPT_FILE="PROMPT_plan.md"
  COMPLETION="PLAN COMPLETE"
  MAX_ITERATIONS=${2:-5}  # Planning needs fewer iterations
else
  PROMPT_FILE="PROMPT_build.md"
  COMPLETION="ALL TASKS COMPLETE"
fi

echo "Running in $MODE mode with max $MAX_ITERATIONS iterations"
echo "Using prompt: $PROMPT_FILE"
echo "Completion signal: $COMPLETION"
echo "=========================================="

for ((i=1; i<=$MAX_ITERATIONS; i++)); do
  echo "Iteration $i / $MAX_ITERATIONS"
  echo "--------------------------------"

  # The -p flag runs Claude in one-shot mode (see Mastery Part 1: https://jocv.dev/blog/claude-code-mastery-01-getting-started#one-shot-mode-quick-questions)
  result=$(claude -p "$(cat $PROMPT_FILE)" --output-format text 2>&1) || true
  echo "$result"

  if [[ "$result" == *"$COMPLETION"* ]]; then
    echo "=========================================="
    echo "$MODE complete after $i iterations."
    exit 0
  fi

  echo "--- End of iteration $i ---"
done

echo "Reached max iterations ($MAX_ITERATIONS)"
exit 1

Hazlo ejecutable:

chmod +x loop.sh

Uso:

./loop.sh plan      # Ejecutar modo de planificación (5 iteraciones por defecto)
./loop.sh build     # Ejecutar modo de construcción (50 iteraciones por defecto)
./loop.sh           # Igual que ./loop.sh build
./loop.sh build 30  # Modo de construcción con máximo 30 iteraciones

Esto te da contexto fresco por iteración, previniendo la inflación de contexto que puede ocurrir con el método del plugin en ejecuciones largas.

Para implementaciones más sofisticadas con manejo de errores, logging y ejecución paralela, consulta snarktank/ralph y mikeyobrien/ralph-orchestrator.

El flujo del loop de construcción

Como documenta 11 Tips for AI Coding with Ralph Wiggum:

1. Selecciona la tarea de mayor prioridad de IMPLEMENTATION_PLAN.md
2. Implementa la funcionalidad
3. Ejecuta todos los tests y verificaciones de tipos (¡contrapresión!)
4. Haz commit solo si todo pasa
5. Actualiza progress.txt con los aprendizajes
6. Itera con contexto fresco → repite

Idea clave: Cada iteración se ejecuta en una ventana de contexto fresca (con el método del bash loop). Esto previene la degradación del contexto y mantiene a Claude enfocado.

Flujo de trabajo completo de las Tres Fases

Así fluye todo junto (usando el script loop.sh de la sección anterior):

# Fase 1: Definir requisitos (conversacional, no en loop)
# Habla con Claude para crear archivos specs/*.md
# Ejemplo: specs/authentication.md, specs/api-design.md, specs/database.md

# Fase 2: Generar el plan (ejecutar una vez, o cuando el plan necesite actualizarse)
./loop.sh plan
# O con el plugin: /ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"
# Crea IMPLEMENTATION_PLAN.md con tareas priorizadas

# Fase 3: Construir de forma autónoma (loop continuo)
./loop.sh
# O con el plugin: /ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"
# Implementa tareas una por una, hace commits, itera

# Cuando el plan se vuelve obsoleto (funcionalidades cambiaron, nuevos requisitos):
rm IMPLEMENTATION_PLAN.md
./loop.sh plan          # Regenerar el plan
./loop.sh               # Reanudar la construcción

Estructura de archivos

Tu proyecto debería tener esta estructura:

your-project/
├── specs/
│   ├── authentication.md
│   ├── api-design.md
│   ├── database.md
│   └── testing.md
├── PROMPT_plan.md          # Prompt del modo de planificación
├── PROMPT_build.md         # Prompt del modo de construcción
├── IMPLEMENTATION_PLAN.md  # Generado por planificación, actualizado por construcción
├── progress.txt            # Log de solo escritura con aprendizajes
├── loop.sh                 # Script orquestador en Bash
└── src/                    # Tu código real
    ├── api/
    ├── auth/
    └── tests/

Diferencias clave entre los modos

Modo de Planificación:

• Archivo de prompt: PROMPT_plan.md
• Objetivo: Analizar y planificar
• ¿Hace commits? No
• ¿Escribe código? No
• ¿Ejecuta tests? No
• ¿Actualiza el plan? Sí (crea/sobrescribe)
• Iteraciones típicas: 1-5
• ¿Cuándo ejecutar? Una vez, o al refrescar el plan

Modo de Construcción:

• Archivo de prompt: PROMPT_build.md
• Objetivo: Implementar y testear
• ¿Hace commits? Sí
• ¿Escribe código? Sí
• ¿Ejecuta tests? Sí
• ¿Actualiza el plan? Sí (marca tareas como completadas)
• Iteraciones típicas: 20-100+
• ¿Cuándo ejecutar? Continuamente hasta terminar

Archivos esenciales para loops largos de Ralph

progress.txt

Lleva registro de lo logrado entre iteraciones. Como explica The Ralph Playbook: "El progress.txt es una práctica estándar para agentes de larga ejecución. Aliméntaselo al agente vía el prompt, y usa el verbo 'append' para asegurarte de que no sobrescriba entradas anteriores."

Ralph lo lee para entender el contexto sin tener que re-explorar todo el codebase.

Cómo usarlo:

En tu prompt, instruye al agente a:
"After each task, APPEND (don't overwrite) your learnings to progress.txt"

Ejemplo de entrada en progress.txt:

[2026-01-16 14:30] Completed TASK-001: User Authentication
- Implemented JWT signing/verification using jsonwebtoken
- Added httpOnly cookie storage for tokens
- All auth tests passing (12/12)
- Learning: Cookie sameSite setting needed for cross-origin requests
- Challenge: Had to debug token expiry edge case
- Next: Tackle TASK-002 (Todo CRUD endpoints)

IMPLEMENTATION_PLAN.md

Tu lista TODO viva que Ralph actualiza conforme completa tareas. Este archivo conecta los modos de Planificación y Construcción.

Estructura:

# Implementation Plan

## High Priority

- [ ] TASK-001: User Authentication (status: pending)
  - Tests: auth.test.ts
  - Dependencies: none

## Medium Priority

- [ ] TASK-002: Todo CRUD (status: pending)
  - Tests: todos.test.ts
  - Dependencies: TASK-001

## Completed

- [x] TASK-000: Project Setup (status: completed)
  - Completed: 2026-01-15 22:00

Escribir prompts efectivos para Ralph

Elementos críticos del prompt

Como se documenta en 11 Tips for AI Coding with Ralph Wiggum, todo prompt de Ralph debería incluir estos elementos:

Seguimiento de progreso:

Read progress.txt to see what's been accomplished.
After completing each task, APPEND (never overwrite) your progress.

Contrapresión mediante testing:

Each commit MUST pass all tests and type checks.
Run: npm test && npm run type-check && npm run lint
If anything fails, fix it before moving on.
NEVER commit broken code.

Control de alcance:

Pick the SINGLE highest priority task from IMPLEMENTATION_PLAN.md.
Work ONLY on that task—don't add features or refactor unrelated code.

Exploración primero:

Study the codebase first.
Don't assume something isn't implemented—verify by reading files.
Use ultrathink before making changes.

Patrones de lenguaje que funcionan

Basándose en los aprendizajes de la comunidad de The Ralph Wiggum Playbook y 11 Tips, estas frases mejoran el comportamiento de Claude:

• "Study the codebase first" → Reduce las suposiciones sobre lo que existe
• "Don't assume not implemented" → Fomenta la verificación antes de escribir
• "Ultrathink before acting" → Promueve la planificación cuidadosa antes de los cambios (ultrathink asigna el presupuesto máximo de razonamiento para lógica compleja — ver Mastery Part 9)
• "Capture the why in commits" → Mejora la calidad del historial de git
• "MUST pass all tests" → Impone las compuertas de calidad de forma estricta

Qué viene después

Ahora tienes la metodología profesional: especificaciones para requisitos, modo de planificación para análisis de brechas, modo de construcción para ejecución autónoma. La estructura de archivos. Las plantillas de prompts.

En la Parte 3: Monitorización con Ralph TUI, cubriremos la visibilidad en tiempo real para loops de larga ejecución — dashboards, controles de teclado y gestión de sesiones.

Luego en la Parte 4: Patrones Avanzados y Solución de Problemas, nos sumergiremos en ingeniería avanzada de prompts, errores comunes, solución integral de problemas y patrones de nivel empresarial.