Guía práctica de snarktank/ralph

Introducción

En el artículo anterior conocimos el principio central de Ralph: bucle infinito + contexto completamente nuevo en cada iteración + archivos como fuente de verdad. Estos tres pilares suenan simples, pero entre comprenderlos y lograr que funcionen en la práctica hay muchos detalles.

En este artículo, pasaremos a la práctica. snarktank/ralph es la implementación del bucle externo de la metodología Ralph, que inicia un proceso de Claude completamente nuevo en cada iteración, resolviendo de raíz el problema del Context Rot. Es una de las implementaciones de Ralph más completas de la comunidad (10k+ stars), compatible con las plataformas Claude Code y Amp, y ofrece una cadena de herramientas completa para generación de PRD, conversión a JSON y ejecución automática.

Otra línea de implementación es frankbria/ralph-claude-code, que proporciona una cadena de herramientas de ingeniería completa (panel de monitoreo, circuit breaker, limitación de velocidad), enfocada en la controlabilidad y los mecanismos de seguridad. La comparación entre ambas se encuentra en ese artículo.

Requisitos previos

Antes de comenzar, asegúrese de que su entorno cumple las siguientes condiciones:

# Verificar dependencias
claude --version   # Claude Code CLI
jq --version       # Procesamiento JSON
git --version      # Git

Instalación y configuración

La forma más sencilla: pegue el enlace de GitHub directamente en una conversación de Claude Code:

Ayúdame a instalar este skill: https://github.com/snarktank/ralph

Claude Code clonará automáticamente el repositorio y copiará los archivos del skill en la ubicación correcta. Una vez completada la instalación, puede utilizar los comandos /prd y /ralph.

snarktank/ralph también admite instalación desde el Marketplace, copia manual de archivos del skill, instalación a nivel de proyecto, entre otros métodos. Consulte las instrucciones en el repositorio de GitHub para más detalles.

Estructura de archivos principales

La memoria de Ralph depende completamente del sistema de archivos. Comprender la función de cada archivo es un requisito previo para utilizar Ralph de manera efectiva.

ralph.sh — Motor del bucle

Este es el núcleo de Ralph: un script bash que se encarga de iniciar repetidamente nuevas instancias de IA.

# Uso básico
./scripts/ralph/ralph.sh [max_iterations]        # Usa Amp por defecto
./scripts/ralph/ralph.sh --tool claude [iterations]  # Usa Claude Code

En cada iteración, ralph.sh realiza lo siguiente:

1. Crea una rama de funcionalidad (basada en el branchName de prd.json)
2. Selecciona el story de mayor prioridad que no ha sido completado (passes: false)
3. Inicia una instancia de IA completamente nueva para implementar ese story
4. Ejecuta verificaciones de calidad (verificación de tipos, pruebas)
5. Si las verificaciones pasan, hace git commit; si fallan, lo deja para la siguiente iteración
6. Actualiza prd.json y marca el story como passes: true
7. Agrega la experiencia aprendida en esta iteración a progress.txt
8. Repite el proceso hasta que todos los stories estén completados o se alcance el límite de iteraciones

El límite de iteraciones predeterminado es 10. Ajústelo según la complejidad del proyecto:

# Proyecto simple
./scripts/ralph/ralph.sh --tool claude 10

# Proyecto complejo
./scripts/ralph/ralph.sh --tool claude 50

prd.json — Definición de tareas

Este es el "cerebro" de Ralph: todas las tareas se definen aquí. El formato es un archivo JSON plano:

{
  "projectName": "Blog i18n traducción",
  "branchName": "ralph/i18n-translation",
  "userStories": [
    {
      "id": "US-001",
      "title": "Traducir metadatos de la página principal",
      "description": "Crear content/docs/meta.en.json con la traducción al inglés de todos los elementos de navegación",
      "acceptanceCriteria": [
        "El archivo meta.en.json existe y tiene formato JSON válido",
        "Todos los títulos de navegación han sido traducidos al inglés",
        "pnpm types:check pasa correctamente"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": [],
      "notes": "Consultar la estructura del meta.json existente"
    },
    {
      "id": "US-002",
      "title": "Traducir el artículo del blog hello-world",
      "description": "Crear content/blog/hello-world.en.mdx, traduciendo del chino al inglés",
      "acceptanceCriteria": [
        "El archivo hello-world.en.mdx existe",
        "Todos los componentes QuoteCard tienen configurado defaultLang='en'",
        "Los enlaces internos usan el prefijo /en/",
        "Los bloques de código se mantienen sin traducir",
        "pnpm types:check pasa correctamente"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001"],
      "notes": "Prestar atención a mantener el formato de props de los componentes MDX"
    }
  ]
}

Descripción de los campos:

progress.txt — Registro de experiencias

Esta es la "memoria a largo plazo" de Ralph. Al final de cada iteración, la IA agrega aquí lo aprendido durante esa ronda:

=== Iteración 1 (US-001) ===
- Descubierto: el comando de verificación de tipos es `pnpm types:check`, no `pnpm typecheck`
- Descubierto: meta.en.json necesita reflejar exactamente la estructura de meta.json
- Patrón: fumadocs i18n usa la convención de sufijo `.en.`

=== Iteración 2 (US-002) ===
- Descubierto: QuoteCard requiere ambas propiedades `quote` y `quoteZh`
- Advertencia: los enlaces internos deben usar el prefijo /en/ para páginas en inglés
- Patrón: los bloques de código nunca deben traducirse

La nueva instancia de Claude en la siguiente iteración lee este archivo y obtiene inmediatamente toda la experiencia previa. Esta es la razón por la que Ralph funciona cada vez mejor con el tiempo: el conocimiento se acumula entre iteraciones, pero el contexto se mantiene limpio.

AGENTS.md — Base de conocimientos persistente

Además de progress.txt, Ralph también actualiza el archivo AGENTS.md (o CLAUDE.md) del proyecto. Tanto Claude Code como Amp leen automáticamente estos archivos al iniciarse.

A diferencia de progress.txt, AGENTS.md registra conocimiento estable y universalmente aplicable entre proyectos:

# AGENTS.md

## Convenciones del código base
- Usar fumadocs como framework de documentación
- Los archivos MDX usan componentes personalizados: QuoteCard, BlogImage, GlossaryCard
- Los archivos i18n usan el sufijo `.en.mdx`

## Advertencias
- Siempre ejecutar `pnpm types:check` después de modificar archivos MDX
- QuoteCard: establecer `defaultLang='en'` en las traducciones al inglés

Redacción del PRD

La calidad del PRD (Product Requirements Document) determina directamente la efectividad de la ejecución de Ralph. Si está bien escrito, Ralph avanza sin problemas; si está mal escrito, Ralph fallará repetidamente en el mismo story.

Uso del Skill para generar el PRD

Si ha instalado el skill de snarktank/ralph, puede generar el PRD de forma interactiva:

# En Claude Code o Amp
/prd Quiero agregar soporte i18n al sistema del blog, necesito traducir todo el contenido en chino al inglés

La IA le hará una serie de preguntas de clarificación (qué archivos están involucrados, restricciones del stack tecnológico, estándares de calidad, etc.) y luego generará un documento PRD estructurado.

Una vez generado, utilice el comando /ralph para convertir el PRD al formato prd.json:

/ralph    # Convierte el PRD a prd.json

Redacción manual del PRD

También puede escribir el prd.json directamente. A continuación se presentan los principios clave de diseño.

Principio uno: la granularidad del Story debe ser adecuada

Cada story debe ser lo suficientemente pequeño como para completarse en una sola iteración, pero lo suficientemente grande como para tener un valor de entrega independiente.

// ❌ Demasiado grande: no se puede completar en una iteración
{
  "id": "US-001",
  "title": "Construir un sistema completo de autenticación de usuarios",
  "description": "Implementar registro, inicio de sesión, recuperación de contraseña, OAuth, gestión de permisos..."
}

// ❌ Demasiado pequeño: no tiene valor independiente
{
  "id": "US-001",
  "title": "Crear el campo email de la tabla User",
  "description": "Agregar el campo email al modelo User"
}

// ✅ Adecuado: se puede completar en una vez y tiene valor independiente
{
  "id": "US-001",
  "title": "Implementar inicio de sesión con correo electrónico y contraseña",
  "description": "Crear la API de inicio de sesión y la página de login, con soporte para verificación por correo electrónico y contraseña",
  "acceptanceCriteria": [
    "POST /api/auth/login acepta email + password",
    "Devuelve un token JWT",
    "El formulario de la página de login se puede enviar",
    "Todas las pruebas pasan"
  ]
}

Regla práctica: un story implica la modificación de 1 a 3 archivos y tiene de 3 a 5 criterios de aceptación.

Principio dos: los criterios de aceptación deben ser verificables automáticamente

Ralph necesita determinar si un story está completado, por lo que los criterios de aceptación deben ser objetivamente evaluables:

// ❌ Criterios vagos
"acceptanceCriteria": [
  "La calidad del código es buena",
  "El rendimiento es aceptable",
  "La experiencia de usuario es fluida"
]

// ✅ Criterios verificables
"acceptanceCriteria": [
  "pnpm types:check pasa correctamente",
  "pnpm test pasa correctamente",
  "El tiempo de respuesta de la API es < 200ms",
  "El archivo src/auth/login.ts existe y exporta la función loginHandler"
]

Principio tres: utilizar dependsOn para controlar el orden

Algunos stories tienen relaciones de dependencia entre sí. El campo dependsOn asegura que Ralph los ejecute en el orden correcto:

{
  "userStories": [
    {
      "id": "US-001",
      "title": "Crear el schema de la base de datos",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Implementar la API de registro de usuarios",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "Implementar la página de inicio de sesión",
      "dependsOn": ["US-002"]
    }
  ]
}

Principio cuatro: proporcionar contexto en notes

El campo notes sirve como indicaciones adicionales para la IA. Escriba aquí la información que usted conoce pero que la IA podría desconocer:

{
  "notes": "El proyecto utiliza el framework fumadocs. La regla de nomenclatura para archivos i18n es el sufijo .en.mdx. Consulte el estilo de traducción de content/docs/notes/speckit/concept.en.mdx."
}

Ejecución del Ralph Loop

Con el PRD listo, es hora de ejecutar el bucle.

Iniciar la ejecución

# Usar Claude Code, 10 iteraciones por defecto
./scripts/ralph/ralph.sh --tool claude

# Especificar número de iteraciones
./scripts/ralph/ralph.sh --tool claude 30

# Usar Amp (por defecto)
./scripts/ralph/ralph.sh 20

Proceso de ejecución

Después de iniciar, verá una salida similar a esta:

Iniciando Ralph - Herramienta: claude - Máximo de iteraciones: 35

===============================================================
  Ralph Iteración 1 de 35 (claude)
===============================================================
## US-001 Completado

**Resumen de lo realizado:**
1. Se creó meta.en.json con todos los elementos de navegación traducidos
2. Se ejecutó pnpm types:check — APROBADO
3. Commit: feat: [US-001] - Traducir metadatos de la página principal

Todavía quedan **15 user stories con `passes: false`**.
El siguiente story es **US-002: Traducir el artículo del blog hello-world**.
Iteración 1 completada. Continuando...

===============================================================
  Ralph Iteración 2 de 35 (claude)
===============================================================

Cada iteración es una instancia de Claude completamente nueva. Sabe qué hacer leyendo prd.json y conoce las lecciones previas a través de progress.txt.

Señal de finalización

Cuando todos los stories están marcados como passes: true, Ralph emite la señal de finalización y se detiene:

¡Todos los stories completados!
<promise>COMPLETE</promise>

Monitoreo y depuración

Mientras Ralph está en ejecución, puede usar estos comandos para verificar el progreso:

# Ver el estado de finalización de cada story (con iconos, más visual)
cat tasks/prd.json | python3 -c "
import json,sys
for s in json.load(sys.stdin)['userStories']:
    print(f'{\"✅\" if s[\"passes\"] else \"⬜\"} {s[\"id\"]}: {s[\"title\"]}')"

# O usar jq para verlo
cat tasks/prd.json | jq '.userStories[] | {id, title, passes}'

# Ver el registro de experiencias
cat progress.txt

# Ver los commits recientes de git
git log --oneline -10

# Ver la salida de Ralph en tiempo real
tail -f progress.txt

# Después de completar, ver todos los cambios respecto a la rama principal
git diff main...ralph/your-branch-name --stat

Interrupción y reanudación

Ralph puede funcionar durante mucho tiempo, e interrumpirlo a mitad del proceso es completamente seguro:

• Interrupción: simplemente presione Ctrl+C. Los stories completados (passes: true) no se perderán; ya se han hecho commit y se han registrado en prd.json
• Reanudación: ejecute el mismo comando nuevamente y Ralph continuará automáticamente desde el primer story con passes: false

# Después de una interrupción, para reanudar solo ejecute el mismo comando
./scripts/ralph/ralph.sh --tool claude 35

Si un story falla repetidamente y causa un bloqueo, puede omitirlo manualmente: edite prd.json, cambie el campo passes de ese story a true y vuelva a ejecutar. Ralph lo omitirá y continuará procesando los stories siguientes.

Archivado automático

Cuando inicia una funcionalidad diferente con un nuevo branchName, Ralph archiva automáticamente los archivos de la ejecución anterior en el directorio archive/YYYY-MM-DD-nombre-funcionalidad/, manteniendo el directorio de trabajo ordenado.

Bucle de retroalimentación y controles de calidad

La capacidad de "autocorrección" de Ralph depende completamente de la calidad del bucle de retroalimentación. Sin bucle de retroalimentación, Ralph es simplemente un script que itera ciegamente: produce código continuamente, pero no puede determinar si el código es correcto.

Configuración de verificaciones de calidad

Defina sus comandos de verificación de calidad en CLAUDE.md (o prompt.md):

## Comandos de calidad

Después de implementar cada story, ejecute estas verificaciones EN ORDEN:

1. `pnpm types:check` — Verificación de tipos TypeScript
2. `pnpm test` — Pruebas unitarias
3. `pnpm build` — Verificación de compilación completa

Si alguna verificación falla:
- NO haga commit
- Corrija el problema
- Vuelva a ejecutar todas las verificaciones
- Solo haga commit cuando todas las verificaciones pasen

Niveles de controles de calidad

Para stories de frontend, Ralph recomienda agregar en los criterios de aceptación: "Verify in browser using dev-browser skill", para que la IA abra realmente el navegador y confirme que la página se renderiza correctamente.

Cuando las verificaciones de calidad fallan

Si las verificaciones de calidad de un story fallan repetidamente, Ralph no reintenta el mismo story indefinidamente. Cuando se alcanza el límite de iteraciones, se detiene y deja el estado actual. Usted puede:

1. Revisar progress.txt para ver dónde se atascó la IA
2. Corregir el problema manualmente y volver a ejecutar
3. Ajustar la granularidad del story (tal vez sea demasiado grande)
4. Agregar más contexto en las notas

Personalización del Prompt

La plantilla de prompt de Ralph (CLAUDE.md o prompt.md) es el medio principal para controlar el comportamiento de la IA. Después de la instalación, debe personalizarla según su propio proyecto. Direcciones clave de personalización:

Restricciones de estilo de código

## Convenciones de código
- Usar el modo estricto de TypeScript
- Preferir exportaciones nombradas sobre exportaciones por defecto
- Usar componentes de fumadocs para contenido MDX
- Seguir los patrones de nomenclatura de archivos existentes (kebab-case)

Errores comunes

## Advertencias conocidas
- Archivos MDX: siempre importar componentes al inicio
- i18n: los archivos en inglés usan el sufijo `.en.mdx`
- Enlaces: las páginas en inglés deben usar el prefijo `/en/`
- QuoteCard: establecer `defaultLang` para que coincida con el idioma del archivo

Manejo cuando se queda atascado

## Cuando se quede atascado
Si no puede completar un story después de 3 intentos dentro de la misma iteración:
1. Documente lo que está bloqueando en progress.txt
2. Pase al siguiente story si es posible
3. NO modifique archivos que no estén relacionados con el story actual

Caso práctico: completar la traducción i18n de un blog con Ralph

Para mostrar cómo opera Ralph en un proyecto real, aquí compartimos un caso real: el uso de un agente autónomo estilo Ralph para traducir un blog completo del chino al inglés.

Configuración del proyecto

El proyecto requería traducir más de 22 archivos de contenido (artículos de blog, documentación, metadatos de navegación) del chino al inglés, con el objetivo de lograr soporte i18n en un blog Next.js basado en fumadocs. Las tareas se definieron en un archivo prd.json que contenía 16 user stories, cada uno con criterios de aceptación claros:

scripts/ralph/
├── prd.json          # 16 user stories con criterios de aceptación
└── progress.txt      # Registro de experiencias, actualizado después de cada story

Cada user story seguía un patrón consistente:

• Entregable claro: "Create content/blog/xxx.en.mdx"
• Criterios verificables: "Typecheck passes", "Internal links use /en/ prefix"
• Restricciones técnicas: "Keep code blocks untranslated", "Set defaultLang='en' on QuoteCard"

Modo de ejecución

El agente siguió los principios fundamentales de la metodología Ralph:

1. Los archivos como fuente de verdad: prd.json rastrea el estado de cada story (passes: true/false). progress.txt acumula experiencia entre iteraciones, por ejemplo: "El comando Typecheck es pnpm types:check, no pnpm typecheck"

2. Controles de calidad automatizados: después de cada traducción, se ejecuta pnpm types:check para verificar que los archivos MDX se compilen correctamente. Si el typecheck falla, se corrige el problema antes de hacer commit.

3. Avance incremental: cada story se hace commit de forma independiente, con mensajes de commit descriptivos (feat: [US-003] - Translate blog/claude-code-quality-control.mdx), facilitando la reversión cuando sea necesario.

4. Ejecución en paralelo: para artículos más extensos, múltiples subagentes traducen simultáneamente; por ejemplo, US-010 (claude-skills concept + practice), US-011 (speckit concept + practice) y US-012 (claude-architecture + claude-subagent) se ejecutaron en paralelo al mismo tiempo.

Lecciones clave

Resultados

Los 16 user stories se completaron en una sola sesión: se crearon 8 archivos meta.en.json de navegación, se tradujeron 3 artículos de blog, se tradujeron 12 páginas de documentación y la compilación completa del sitio pasó la verificación. Cada traducción mantuvo una calidad consistente porque los criterios de aceptación eran claros y el bucle de retroalimentación (typecheck) detectaba problemas de inmediato.

Este proyecto demostró el Modo de Implementación Completa (Full Implementation Mode) de Ralph: tareas claramente definidas, criterios de éxito explícitos, verificación automatizada y entrega incremental a través del sistema de archivos.

Mejores prácticas y preguntas frecuentes

Control de costos

La ejecución automatizada de Ralph significa que los costos de API se generan de forma continua. Algunas medidas de control:

• Siempre establecer max_iterations: esta es la red de seguridad más básica
• Granularidad razonable de los stories: stories demasiado grandes consumen múltiples iteraciones; stories demasiado fragmentados aumentan la sobrecarga de inicio
• Probar a pequeña escala primero: en proyectos nuevos, haga una prueba con 3 a 5 iteraciones para confirmar que el prompt y los controles de calidad funcionan correctamente antes de escalar

Errores comunes

Error 1: Story demasiado grande

Síntoma: un story falla repetidamente y las iteraciones se agotan rápidamente.

Solución: divídalo en 2-3 stories más pequeños. "Construir un sistema de autenticación completo" se divide en "Implementar la API de inicio de sesión" + "Crear la página de inicio de sesión" + "Agregar middleware JWT".

Error 2: sin bucle de retroalimentación

Síntoma: Ralph afirma que el story está completado, pero el código en realidad tiene problemas.

Solución: agregue comandos de verificación ejecutables en los criterios de aceptación. "El código está listo" no es un criterio de aceptación; "pnpm test pasa completamente" sí lo es.

Error 3: progress.txt no se utiliza

Síntoma: el mismo error aparece repetidamente en diferentes iteraciones.

Solución: confirme que la plantilla del prompt tiene instrucciones claras de "leer progress.txt y seguir las lecciones allí registradas". Si la IA no agrega contenido de aprendizaje automáticamente, añada en el prompt: "After each story, append learnings to progress.txt".

Error 4: orden de dependencias incorrecto

Síntoma: un story depende de código que aún no existe, lo que hace que la implementación falle.

Solución: configure correctamente el campo dependsOn y asegúrese de que los stories de infraestructura se ejecuten primero.

Preguntas frecuentes

P: ¿Se puede modificar manualmente prd.json para intervenir a mitad del proceso?

Sí. Ralph vuelve a leer prd.json al inicio de cada iteración. Puede modificar la descripción de un story entre iteraciones, agregar nuevos stories o marcar manualmente un story como passes: true (para omitirlo).

P: ¿Qué hacer si Ralph se queda atascado fallando repetidamente en un story?

1. Revise progress.txt para ver la causa del fallo
2. Agregue más contexto en las notas
3. Divida el story (puede que la granularidad sea demasiado grande)
4. Corrija manualmente el problema de bloqueo y vuelva a ejecutar

P: ¿Puedo hacer otras cosas mientras Ralph está en ejecución?

Sí. Ralph está diseñado como "Human on the Loop": no necesita supervisarlo constantemente. En modo AFK, inícielo antes de salir del trabajo y revise los resultados al día siguiente. Simplemente no modifique los archivos que Ralph está operando mientras se ejecuta.

P: ¿Cómo controlar los costos?

Tres métodos: establecer un max_iterations razonable, mantener una granularidad adecuada de los stories (reducir iteraciones innecesarias) y hacer pruebas a pequeña escala primero para confirmar que el flujo funciona correctamente. En general, un proyecto con 10 a 20 stories está en el rango de $50 a $100 de costo de API.

Resumen

El flujo de uso de Ralph se puede resumir en cinco pasos:

Instalación → Redacción del PRD → Configuración de controles de calidad → Ejecución del bucle → Revisión de resultados

La idea central permanece invariable: hacer que los archivos sean la fuente de verdad, que cada iteración sea un comienzo completamente nuevo y que los controles de calidad se encarguen de la supervisión por usted.

Ahora, regrese a su proyecto, prepare el prd.json, ejecute ./scripts/ralph/ralph.sh --tool claude y vaya a tomarse un café.

Lecturas complementarias

• Análisis profundo de Ralph Wiggum -- Repaso de los principios fundamentales de Ralph
• Guía práctica de frankbria/ralph-claude-code -- Implementación de Ralph orientada a ingeniería: monitoreo, circuit breaker y mecanismos de seguridad
• Análisis profundo de GSD -- Sistema completo de ingeniería de contexto construido sobre Ralph
• Qué son los Claude Skills -- El skill PRD de Ralph es un Claude Skill
• Guía práctica de Speckit -- Otro flujo de trabajo estructurado para programación con IA