Guía práctica de Ralph

Introducción

En artículo anterior, entendimos los principios básicos de Ralph: bucle infinito + contexto nuevo cada vez + archivo como única fuente de verdad. Estos tres pilares parecen simples, pero desde comprender el concepto hasta ejecutarlo, hay muchos detalles que deben resolverse.

En este artículo, comencemos. Aprenderá a utilizar snarktank/ralph para completar el proceso completo desde la instalación hasta la ejecución. snarktank/ralph es una de las implementaciones de Ralph más maduras en la comunidad (más de 10.000 estrellas). Admite dos herramientas, Claude Code y Amp, y una cadena de herramientas completa para la generación de PRD, conversión JSON y ejecución automatizada.

Condiciones previas

Antes de comenzar, asegúrese de que su entorno cumpla los siguientes requisitos:

# 检查依赖
claude --version   # Claude Code CLI
jq --version       # JSON 处理
git --version      # Git

Instalación y configuración

snarktank/ralph proporciona una variedad de métodos de instalación, que se pueden seleccionar según el escenario de uso.

Método 1: instalar directamente en Claude Code (recomendado)

La forma más sencilla: pegue el enlace de GitHub en la conversación de Claude Code y deje que Claude complete automáticamente la instalación:

Install this skill for me: https://github.com/snarktank/ralph

Claude Code clonará automáticamente el repositorio y copiará los archivos de habilidades en la ubicación correcta. Los comandos /prd y /ralph están disponibles después de la instalación.

Método 2: Instalación en el mercado del Código Claude

Instalar mediante comando de mercado:

# 添加并安装插件
/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

Después de la instalación, puede utilizar las dos habilidades /prd (generar PRD) y /ralph (convertir a JSON).

Método 3: Instalación manual de habilidades (Claude Code/Amp)

Copie manualmente el archivo de habilidades al directorio de configuración global de la herramienta correspondiente:

# 先克隆仓库
git clone https://github.com/snarktank/ralph.git /tmp/ralph

# Claude Code 用户
cp -r /tmp/ralph/skills/prd ~/.claude/skills/
cp -r /tmp/ralph/skills/ralph ~/.claude/skills/

# Amp 用户
cp -r /tmp/ralph/skills/prd ~/.config/amp/skills/
cp -r /tmp/ralph/skills/ralph ~/.config/amp/skills/

Los comandos /prd y /ralph están disponibles después de la instalación.

Método 4: instalación a nivel de proyecto

Copie el script de Ralph directamente en el proyecto, ideal para escenarios en los que se requiere compartir en equipo o scripts personalizados:

# 克隆 Ralph 仓库
git clone https://github.com/snarktank/ralph.git /tmp/ralph

# 复制核心文件到项目
mkdir -p scripts/ralph
cp /tmp/ralph/ralph.sh scripts/ralph/
cp /tmp/ralph/CLAUDE.md scripts/ralph/   # Claude Code 用户
# 或
cp /tmp/ralph/prompt.md scripts/ralph/   # Amp 用户

# 赋予执行权限
chmod +x scripts/ralph/ralph.sh

Una vez completada la instalación, la estructura del proyecto es la siguiente:

your-project/
├── scripts/ralph/
│   ├── ralph.sh        # 核心循环脚本
│   └── CLAUDE.md       # Claude Code 的 Prompt 模板
├── tasks/              # PRD 文件目录（执行时自动创建）
│   └── prd.json        # 你的任务定义
└── ...

Sugerencia: El primer método es el más fácil: simplemente envíe el enlace de GitHub a Claude Code. Si desea controlar manualmente el proceso de instalación, elija el método 2 (comando de mercado) o el método 3 (copia manual). Elija el método 4 cuando necesite compartir el script con el equipo o personalizarlo.

Estructura de archivos principal

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

ralph.sh - motor de bucle

Este es el núcleo de Ralph: un script bash que genera constantemente nuevas instancias de IA.

# 基本用法
./scripts/ralph/ralph.sh [max_iterations]        # 默认：Amp
./scripts/ralph/ralph.sh --tool claude [iterations]  # 使用 Claude Code

En cada iteración, ralph.sh realiza los siguientes pasos:

1. Cree una rama de funciones (desde branchName en prd.json)
2. Seleccione la historia inacabada con mayor prioridad (passes: false)
3. Genere una nueva instancia de IA para implementar esta historia.
4. Ejecute controles de calidad (verificaciones de tipo, pruebas)
5. Verificación aprobada → git commit; verificación fallida → déjelo para la siguiente iteración
6. Actualice prd.json y marque la historia como passes: true
7. Adjunte las lecciones aprendidas al archivo Progress.txt.
8. Repita hasta que se completen todas las historias o se alcance el número máximo de iteraciones.

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

# 简单项目
./scripts/ralph/ralph.sh --tool claude 10

# 复杂项目
./scripts/ralph/ralph.sh --tool claude 50

prd.json - definición de tarea

Este es el "cerebro" de Ralph, donde se definen todas las tareas. Es un archivo JSON plano:

{
  "projectName": "Blog i18n Translation",
  "branchName": "ralph/i18n-translation",
  "userStories": [
    {
      "id": "US-001",
      "title": "Translate homepage metadata",
      "description": "Create content/docs/meta.en.json with English translations for all navigation items",
      "acceptanceCriteria": [
        "meta.en.json file exists with valid JSON format",
        "All navigation titles are translated to English",
        "pnpm types:check passes"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": [],
      "notes": "Reference the existing meta.json structure"
    },
    {
      "id": "US-002",
      "title": "Translate blog post hello-world",
      "description": "Create content/blog/hello-world.en.mdx, translated from Chinese to English",
      "acceptanceCriteria": [
        "hello-world.en.mdx file exists",
        "All QuoteCard components have defaultLang='en'",
        "Internal links use /en/ prefix",
        "Code blocks remain untranslated",
        "pnpm types:check passes"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001"],
      "notes": "Preserve MDX component props format"
    }
  ]
}

Descripción del campo:

progreso.txt - registro de experiencia

Esta es la "memoria a largo plazo" de Ralph. Después de cada iteración, la IA agregará experiencia aprendida adicional:

=== Iteration 1 (US-001) ===
- Discovered: typecheck command is `pnpm types:check`, not `pnpm typecheck`
- Discovered: meta.en.json needs to mirror exact structure of meta.json
- Pattern: fumadocs i18n uses `.en.` suffix convention

=== Iteration 2 (US-002) ===
- Discovered: QuoteCard requires both `quote` and `quoteZh` props
- Gotcha: internal links must use /en/ prefix for English pages
- Pattern: code blocks should never be translated

Una nueva instancia de Claude para la próxima iteración leerá este archivo e inmediatamente obtendrá toda la experiencia anterior. Esta es la razón por la que las ejecuciones de Ralph son cada vez mejores: el conocimiento se acumula entre iteraciones, pero el contexto permanece limpio.

AGENTS.md - Base de conocimientos persistente

Además de Progress.txt, Ralph también actualiza el archivo AGENTS.md (o CLAUDE.md) en el proyecto. Tanto Claude Code como Amp leerán automáticamente estos archivos cuando se inicien.

A diferencia de Progress.txt, AGENTS.md registra conocimiento estable entre proyectos:

# AGENTS.md

## Codebase Conventions
- Use fumadocs for documentation framework
- MDX files use custom components: QuoteCard, BlogImage, GlossaryCard
- i18n files use `.en.mdx` suffix

## Gotchas
- Always run `pnpm types:check` after modifying MDX files
- QuoteCard: set `defaultLang='en'` in English translations

Escribe PRD

La calidad del PRD (Documento de requisitos del producto) determina directamente los resultados de ejecución de Ralph. Bien escrito, todo viento en popa, Ralph. Mal escrito, Ralph fracasará repetidamente en la misma historia.

Usa habilidad para generar PRD

Si tienes instalada la habilidad snarktank/ralph, puedes generar PRD de forma interactiva:

# 在 Claude Code 或 Amp 中
/prd I want to add i18n support to the blog, translating all Chinese content to English

La IA le hará algunas preguntas aclaratorias (qué documentos están involucrados, limitaciones de la pila de tecnología, estándares de calidad, etc.) y luego generará un documento PRD estructurado.

Después de la generación, use el comando /ralph para convertir el PRD al formato prd.json:

/ralph    # 转换 PRD 为 prd.json

Escribir PRD manualmente

También puedes escribir prd.json directamente. Los siguientes son principios clave de diseño.

Principio 1: la granularidad de la historia es moderada

Cada historia debe ser lo suficientemente pequeña como para completarse en una iteración y lo suficientemente grande como para ofrecer valor de forma independiente.

// ❌ 太大：一次迭代完不成
{
  "id": "US-001",
  "title": "Build complete user authentication system",
  "description": "Implement registration, login, forgot password, OAuth, permission management..."
}

// ❌ 太小：没有独立价值
{
  "id": "US-001",
  "title": "Create email field on User table",
  "description": "Add email field to User model"
}

// ✅ 刚好：一次迭代能完成，有独立价值
{
  "id": "US-001",
  "title": "Implement email/password login",
  "description": "Create login API and login page with email/password authentication",
  "acceptanceCriteria": [
    "POST /api/auth/login accepts email + password",
    "Returns JWT token",
    "Login page form submits successfully",
    "All tests pass"
  ]
}

Regla general: Una historia implica de 1 a 3 modificaciones de archivos y tiene de 3 a 5 criterios de aceptación.

Principio 2: Los criterios de aceptación deben ser verificables automáticamente

Ralph necesita determinar si la historia está completa, por lo que los criterios de aceptación deben poder evaluarse objetivamente:

// ❌ 模糊的标准
"acceptanceCriteria": [
  "Code quality is good",
  "Performance is decent",
  "User experience is smooth"
]

// ✅ 可验证的标准
"acceptanceCriteria": [
  "pnpm types:check passes",
  "pnpm test passes",
  "API response time < 200ms",
  "File src/auth/login.ts exists and exports loginHandler function"
]

Principio 3: Utilice depende de para controlar el orden de ejecución

Algunas historias tienen dependencias. El campo dependsOn garantiza que Ralph se ejecute en el orden correcto:

{
  "userStories": [
    {
      "id": "US-001",
      "title": "Create database schema",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Implement user registration API",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "Implement login page",
      "dependsOn": ["US-002"]
    }
  ]
}

Principio 4: Proporcionar contexto en las notas

El campo de notas le da a la IA pistas adicionales. Escriba aquí información que sepa y que la IA tal vez no conozca:

{
  "notes": "Project uses fumadocs framework, i18n files follow .en.mdx suffix naming. Reference content/docs/notes/speckit/concept.en.mdx for translation style."
}

Ejecutar bucle Ralph

Una vez que el PRD esté listo, es hora de ejecutar el ciclo.

Iniciar ejecución

# 使用 Claude Code，默认 10 次迭代
./scripts/ralph/ralph.sh --tool claude

# 指定迭代次数
./scripts/ralph/ralph.sh --tool claude 30

# 使用 Amp（默认）
./scripts/ralph/ralph.sh 20

Proceso de ejecución

Después de comenzar, verá un resultado similar a este:

=== Ralph Loop - Iteration 1 ===
Branch: ralph/i18n-translation
Selected story: US-001 - Translate homepage metadata
Spawning fresh Claude instance...

[Claude Code executing...]

Quality check: pnpm types:check ... PASSED
Committing: feat: [US-001] - Translate homepage metadata
Updating prd.json: US-001 passes: true
Appending to progress.txt

=== Ralph Loop - Iteration 2 ===
Selected story: US-002 - Translate blog post hello-world
Spawning fresh Claude instance...

Cada iteración es una instancia completamente nueva de Claude. Sabe qué hacer leyendo prd.json y qué ha aprendido previamente leyendo Progress.txt.

###Señal completa

Cuando todas las historias están marcadas como passes: true, Ralph emite una señal de finalización y sale:

All stories completed!
<promise>COMPLETE</promise>

Monitoreo y depuración

Mientras Ralph se ejecuta, puede utilizar el siguiente comando para ver el progreso:

# 查看每个 story 的完成状态
cat tasks/prd.json | jq '.userStories[] | {id, title, passes}'

# 查看经验日志
cat progress.txt

# 查看最近的 git 提交
git log --oneline -10

# 实时跟踪 Ralph 输出
tail -f progress.txt

Archivado automático

Cuando inicia una nueva función (usando un branchName diferente), Ralph archivará automáticamente los archivos de la última ejecución en el directorio archive/YYYY-MM-DD-feature-name/, manteniendo limpio el directorio de trabajo.

Bucles de retroalimentación y control de puerta de calidad

La capacidad de Ralph para "autocorregirse" depende enteramente de la calidad del circuito de retroalimentación. Sin un ciclo de retroalimentación, Ralph es solo un script que se repite a ciegas: sigue generando código sin poder decir si es correcto.

Configurar control de calidad

Defina comandos de control de calidad en CLAUDE.md (o Prompt.md):

## Quality Commands

After implementing each story, run these checks IN ORDER:

1. `pnpm types:check` — TypeScript type checking
2. `pnpm test` — Unit tests
3. `pnpm build` — Full build verification

If any check fails:
- DO NOT commit
- Fix the issue
- Re-run all checks
- Only commit when all checks pass

Nivel de control de acceso de calidad

Para historias de front-end, Ralph recomienda agregar este criterio de aceptación: "Verificar en el navegador usando la habilidad del navegador de desarrollo": permita que la IA abra el navegador para confirmar que la página se muestra correctamente.

Cuando falla el control de calidad

Si una historia falla repetidamente en el control de calidad, Ralph no volverá a intentar la misma historia indefinidamente. Se detendrá después de alcanzar el límite superior de iteración y conservará el estado actual. Puedes:

1. Vea el archivo Progress.txt para comprender el motivo del bloqueo.
2. Solucione el problema manualmente y luego ejecútelo nuevamente.
3. Ajuste la granularidad de la historia (quizás demasiado grande)
4. Agregue más contexto al campo de notas.

Personalización inmediata

La plantilla de aviso de Ralph (CLAUDE.md o aviso.md) es su principal medio para controlar el comportamiento de la IA. Después de la instalación, debes personalizarlo según tu proyecto.

Elementos clave de personalización

1. Comandos de calidad específicos del proyecto

## Project-Specific Commands
- Typecheck: `pnpm types:check` (not `tsc` or `pnpm typecheck`)
- Test: `pnpm vitest run`
- Build: `pnpm build`
- Lint: `pnpm lint`

2. Restricciones de estilo de código

## Code Conventions
- Use TypeScript strict mode
- Prefer named exports over default exports
- Use fumadocs components for MDX content
- Follow existing file naming patterns (kebab-case)

3. Errores conocidos

## Known Gotchas
- MDX files: always import components at the top
- i18n: English files use `.en.mdx` suffix
- Links: English pages must use `/en/` prefix
- QuoteCard: set `defaultLang` to match the file language

4. Manejo cuando está atascado

## When Stuck
If you cannot complete a story after 3 attempts within the same iteration:
1. Document what's blocking in progress.txt
2. Move to the next story if possible
3. Do NOT modify files unrelated to the current story

Caso práctico: Traducir blogs con Ralph

Para mostrar cómo funciona Ralph en la práctica, he aquí un ejemplo de la vida real: utilizar un agente autónomo al estilo Ralph para traducir un blog completo del chino al inglés.

Configuración del proyecto

Este proyecto requiere traducir más de 22 archivos de contenido (publicaciones de blog, documentos, metadatos de navegación) del chino al inglés. El proyecto se basa en el blog Next.js de fumadocs y es compatible con i18n. La tarea está definida en el archivo prd.json y contiene 16 historias de usuario, cada una con criterios de aceptación claros:

scripts/ralph/
├── prd.json          # 16 个 user story，带验收标准
└── progress.txt      # 经验日志，每个 story 完成后更新

Cada historia de usuario sigue un patrón consistente:

• Entregable explícito: "Crear contenido/blog/xxx.en.mdx"
• Criterios verificables: "Pases de verificación de tipo", "Los enlaces internos usan el prefijo /en/"
• Restricciones técnicas: "Mantener los bloques de código sin traducir", "Establecer defaultLang='en' en QuoteCard"

Modo de ejecución

El agente sigue los principios básicos de la metodología de Ralph:

1. Los documentos son la fuente de la verdad: prd.json rastrea qué historias pasaron (passes: true/false). progress.txt Adquiera experiencia entre iteraciones, p. "El comando Typecheck es pnpm types:check, no pnpm typecheck"

2. Puerta de calidad automatizada: después de cada traducción, se ejecuta pnpm types:check para verificar que el archivo MDX se haya compilado correctamente. Si la verificación de tipo falla, corríjala antes de enviarla.

3. Avance incremental: cada historia se envía de forma independiente, con información descriptiva de envío (feat: [US-003] - Translate blog/claude-code-quality-control.mdx) y se puede revertir fácilmente cuando sea necesario.

4. Ejecución paralela: para artículos más largos, se traducen varios subagentes simultáneamente; por ejemplo, US-010 (concepto de habilidades de claude + práctica), US-011 (concepto de speckit + práctica) y US-012 (arquitectura de claude + subagente de claude) se ejecutan en paralelo.

Lecciones clave

Resultados

Las 16 historias de usuarios se completaron en una sola sesión: se crearon 8 archivos de navegación meta.en.json, se tradujeron 3 publicaciones de blog, se tradujeron 12 páginas de documentación y se verificó la construcción completa del sitio. Cada traducción mantiene una calidad constante porque los criterios de aceptación son claros y un circuito de retroalimentación (verificación de tipos) detecta los problemas de inmediato.

Este proyecto demuestra el modelo de implementación completo de Ralph: tareas bien definidas + criterios de éxito claros + verificación automatizada + entrega incremental a través del sistema de archivos.

Implementación comunitaria y alternativas

snarktank/ralph no es la única opción. Cada una de estas implementaciones tiene sus propias fortalezas y debilidades, según sus necesidades:

Alternativa: GSD

GSD no es estrictamente una "implementación comunitaria" de Ralph; es una alternativa. Aplica los principios básicos de Ralph (gestión del contexto, tareas atómicas) pero proporciona un flujo de trabajo más completo: discutir → planificar → ejecutar → verificar.

Si cree que Ralph es demasiado "crudo" y necesita más apoyo en el proceso, GSD puede ser más adecuado. Consulte Análisis en profundidad de GSD para obtener más detalles.

Recursos recomendados

Fuente oficial:

Tutorial en vídeo:

Mejores prácticas y preguntas frecuentes

Control de costos

La ejecución automatizada de Ralph significa que se incurre en tarifas API de forma continua. Varias medidas de control:

• Siempre configurado max_iterations: esta es la red de seguridad más básica
• Mantenga la granularidad de la historia razonable: una historia que es demasiado grande consumirá múltiples iteraciones; una historia demasiado detallada aumentará los gastos generales de puesta en marcha.
• Primero pruebas a pequeña escala: los nuevos proyectos se ejecutarán primero durante 3 a 5 iteraciones y luego se ampliarán después de confirmar que las indicaciones y el control de acceso de calidad funcionan correctamente.

Errores comunes

Trampa 1: La historia es demasiado grande

Síntomas: una historia falla repetidamente y el número de iteraciones se agota rápidamente.

Solución: divídalo en 2 o 3 pisos más pequeños. "Crear 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".

Trampa 2: Sin circuito de retroalimentación

Síntoma: Ralph afirma que la historia está completa, pero hay algún problema con el código real.

Solución: agregue comandos de verificación ejecutables en los criterios de aceptación. "El código está escrito" no es un criterio de aceptación; "pnpm prueba todos los pases" sí lo es.

Trampa 3: Progress.txt no se utiliza

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

Resolución: asegúrese de que su plantilla de aviso indique explícitamente "lea el archivo Progress.txt y siga las reglas que contiene". Si la IA no agrega experiencia automáticamente, agregue "Después de completar cada historia, agregue experiencia a Progress.txt" en el mensaje.

Trampa 4: Orden de dependencia incorrecto

Síntoma: una historia se basa en un código que aún no existe, lo que provoca que falle la implementación.

Resolución: establezca el campo dependsOn correctamente. Asegúrese de que la historia de la infraestructura sea lo primero.

FAQ

**P: ¿Cuál es la diferencia entre Ralph y el complemento oficial? **

Diferencia principal: snarktank/ralph genera nuevos procesos en cada iteración (verdaderamente un contexto completamente nuevo), mientras que el complemento oficial se repite dentro de la misma sesión (el contexto continúa acumulándose). Ver análisis del artículo anterior para más detalles.

**P: ¿Se puede modificar prd.json manualmente durante la ejecución? **

Sí. Ralph vuelve a leer prd.json al comienzo de cada iteración. Puede modificar las descripciones de las historias entre iteraciones, agregar nuevas historias o marcar manualmente una historia como passes: true (omitirla).

**P: ¿Qué debería hacer Ralph si se queda atrapado en una historia que falla repetidamente? **

1. Consulte el archivo Progress.txt para comprender el motivo del error.
2. Añade más contexto en las notas.
3. Divida la historia (quizás demasiado grande)
4. Solucione manualmente el problema de bloqueo y luego ejecútelo nuevamente.

**P: ¿Puedo hacer otras cosas mientras Ralph está corriendo? **

Sí. Ralph está diseñado para ser "Human on the Loop": no es necesario que lo mires fijamente. En el modo AFK, comience antes de salir del trabajo y verifique los resultados a la mañana siguiente. Simplemente no modifique el archivo en el que está trabajando Ralph.

**P: ¿Cómo controlar los costos? **

Tres métodos: establecer un max_iterations razonable, mantener la granularidad de la historia adecuada (para reducir las iteraciones desperdiciadas) y primero realizar una prueba a pequeña escala para confirmar que el proceso es correcto. En términos generales, para proyectos con 10 a 20 pisos, la tarifa API está entre $50 y $100.

Resumen

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

安装 → 编写 PRD → 配置质量门禁 → 运行循环 → 检查结果

El concepto central sigue siendo el mismo: Deje que el documento sea la única fuente de verdad, deje que cada iteración comience desde cero y deje que la puerta de calidad controle por usted.

Ahora, regresa a tu proyecto, prepara prd.json, ejecuta ./scripts/ralph/ralph.sh --tool claude y prepara una taza de café.

Lectura adicional

• Análisis en profundidad de Ralph Wiggum - Revisando los principios fundamentales de Ralph
• Análisis en profundidad de GSD - Un completo sistema de ingeniería de contexto construido sobre la base de Ralph
• ¿Qué son las habilidades de Claude? ——La habilidad PRD de Ralph es una habilidad de Claude
• Guía práctica de Speckit - Otro flujo de trabajo estructurado de programación de IA