Guía práctica de frankbria/ralph-claude-code

Introducción

El artículo anterior presentó la metodología Ralph, y snarktank/ralph mostró una implementación minimalista del bucle externo. Ahora veamos otra ruta: frankbria/ralph-claude-code.

Si la filosofía de snarktank/ralph es "hacer más con menos código", la filosofía de frankbria es "ingeniería para todo" — asistente de configuración interactivo, panel de monitoreo en tiempo real, circuit breaker, limitación de tasa, gestión de expiración de sesiones. No busca la simplicidad, sino la controlabilidad.

Las dos implementaciones no son mejores ni peores entre sí, simplemente se adaptan a diferentes escenarios de uso. Este artículo le guiará a través de la cadena de herramientas completa de frankbria.

Instalación y configuración

Instalación global

# Clonar el repositorio
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code

# Instalación global
./install.sh

Una vez completada la instalación, obtendrá los siguientes comandos globales:

Inicialización del proyecto

Para proyectos existentes, utilice el asistente interactivo:

cd your-project
ralph-enable

El asistente detectará automáticamente el tipo de proyecto (Node.js, Python, Go, etc.) y el framework (Next.js, FastAPI, etc.), y luego generará los archivos de configuración correspondientes.

Para proyectos completamente nuevos:

ralph-setup my-new-project

Esto creará el directorio del proyecto, inicializará Git y generará el directorio de configuración .ralph/.

Importar requisitos existentes

Si ya tiene documentos PRD o especificaciones de requisitos:

ralph-import path/to/your-prd.md

Ralph analizará el documento, extraerá la lista de tareas y generará un fix_plan.md estructurado.

Estructura del directorio .ralph/

La memoria y configuración de frankbria se centralizan en el directorio .ralph/:

.ralph/
├── PROMPT.md          # Objetivos y contexto del proyecto
├── fix_plan.md        # Lista de tareas (similar a prd.json)
├── AGENT.md           # Comandos de build/test (mantenido automáticamente)
├── specs/             # Documentos de requisitos detallados
│   ├── feature-a.md
│   └── feature-b.md
└── sessions/          # Datos de persistencia de sesiones
    ├── current.json
    └── history/

Comparación con snarktank/ralph:

Note que AGENT.md se mantiene automáticamente — Ralph lo actualiza automáticamente durante la ejecución según las convenciones del proyecto que descubre, similar al progress.txt de snarktank/ralph, pero más estructurado.

Comandos principales

Ejecución básica

# Iniciar el ciclo Ralph
ralph

# Con monitoreo en tiempo real
ralph --monitor

# Iniciar en tmux (recomendado para ejecuciones prolongadas)
ralph --live

Panel de monitoreo

# Iniciar el monitoreo de forma independiente
ralph-monitor

ralph-monitor abrirá un panel tmux que muestra en tiempo real:

• La tarea que se está ejecutando actualmente
• Conteo de tareas completadas/pendientes
• Número de llamadas a la API y estimación de costos
• Estado del circuit breaker
• Registros de errores recientes

Parámetros comunes

# Limitar a 50 llamadas API, 2 horas de tiempo de espera
ralph --calls 50 --timeout 120

# Continuar desde la última interrupción
ralph --resume

Mecanismos de seguridad

La mayor característica diferenciadora de frankbria son sus mecanismos de seguridad multicapa.

Circuit Breaker (Disyuntor)

El circuit breaker detiene automáticamente el ciclo cuando detecta "falta de progreso", previniendo el consumo inútil de la API:

Detección de falta de progreso consecutiva: Si durante N iteraciones consecutivas no se completa ninguna tarea nueva, se activa el circuit breaker.

Detección de errores repetidos: Si aparece consecutivamente el mismo mensaje de error, indica que la IA está atrapada en un ciclo infinito, y se activa el circuit breaker.

Limitación de tasa

Límite por defecto de 100 calls/hour, para prevenir facturas de API inesperadamente altas. Se puede ajustar mediante parámetros:

ralph --calls 200  # Aumentar a 200 calls

Detección de tres capas para el límite de 5 horas de API

La API de Anthropic tiene un límite de uso con ventana deslizante de 5 horas. frankbria incorpora detección en tres capas:

1. Pre-detección: Estima la cuota restante antes de cada llamada a la API
2. Detección de respuesta: Analiza los headers de rate limit en la respuesta de la API
3. Estrategia de retroceso: Reduce automáticamente la frecuencia de llamadas al acercarse al límite

Gestión de expiración de sesiones

La sesión tiene una validez por defecto de 24 horas. Después de ese período, los datos de sesión se limpian automáticamente para evitar que el contexto obsoleto afecte ejecuciones posteriores.

Detección inteligente de salida

frankbria no simplemente sale cuando todas las tareas están completas. Utiliza una puerta de salida de doble condición:

Condición de salida = completion_indicators >= 2 AND EXIT_SIGNAL: true

completion_indicators es el número de señales de finalización detectadas en la salida de la IA, incluyendo:

• "Todas las tareas están completas"
• "No hay más elementos pendientes"
• Todas las pruebas pasaron
• Todos los elementos en fix_plan.md marcados como done

EXIT_SIGNAL es la declaración explícita de intención de salida de la IA en su salida.

¿Por qué se necesitan dos condiciones? Para prevenir salidas prematuras. Una señal única podría ser un falso positivo — por ejemplo, la IA dice "tarea completada" pero en realidad solo completó la story actual. La doble condición asegura que solo se sale realmente cuando múltiples señales independientes confirman la finalización.

Comparación con snarktank/ralph

Diferencia principal: nivel de ingeniería

Ambos son bucles bash externos que inician nuevos procesos de Claude. La diferencia principal no está en el modo de gestión de sesiones (frankbria puede cambiar a modo de sesión nueva con --no-continue), sino en el nivel de ingeniería:

• snarktank: Script minimalista, unos cientos de líneas de bash, enfocado en el ciclo en sí
• frankbria: Cadena de herramientas completamente ingenieril — panel de monitoreo, circuit breaker, limitación de tasa, gestión de expiración de sesiones

frankbria tiene habilitado --continue por defecto para reutilizar sesiones, ideal para tareas cortas. Para tareas largas, se puede cambiar al modo de sesión nueva con --no-continue, obteniendo la misma protección contra Context Rot que snarktank, mientras se conservan las ventajas de ingeniería de frankbria.

Cómo deshabilitar la reutilización de sesiones

frankbria ofrece tres formas de deshabilitar --continue:

# Forma uno: parámetro de línea de comandos
ralph --no-continue

# Forma dos: variable de entorno
export CLAUDE_USE_CONTINUE=false

# Forma tres: configuración .ralphrc
SESSION_CONTINUITY=false

Una vez deshabilitado, el comportamiento de frankbria es equivalente al de snarktank (sesión nueva cada vez), pero conserva todas las herramientas de ingeniería (monitoreo, circuit breaker, limitación de tasa, etc.).

La realidad del Context Rot y sus compensaciones

La elección del modo de reutilización de sesiones es esencialmente una compensación entre Context Rot y el costo de inicio:

Tareas cortas (< 50k tokens): Reutilizar la sesión es más ventajoso. El contexto aún no ha tenido tiempo de degradarse, y la memoria de las primeras iteraciones aún puede ser aprovechada por las posteriores. El costo de inicio de crear una sesión nueva cada vez es más bien un desperdicio.

Tareas largas (100k+ tokens): Las sesiones nuevas son más confiables. Después de superar los 100k tokens, el Context Rot se intensifica notablemente, y el contexto acumulado pasa de ser un activo a una carga. Las sesiones nuevas tienen costo de inicio, pero cada vez se parte del estado óptimo.

Recomendaciones prácticas:

Los usuarios de frankbria pueden elegir flexiblemente según la escala de las tareas: para tareas cortas usar el modo --continue por defecto, para tareas largas cambiar al modo --no-continue. En comparación con snarktank, la ventaja de frankbria es que en cualquiera de los dos modos conserva la cadena de herramientas de ingeniería completa.

Resumen

frankbria/ralph-claude-code representa la ruta de implementación ingenieril de la metodología Ralph. Sacrifica algo de la simplicidad de snarktank a cambio de capacidades de monitoreo, seguridad y configuración más completas.

La elección de qué implementación usar depende de sus necesidades específicas — no hay una respuesta "más correcta", solo una elección "más adecuada".

Lectura complementaria:

• Análisis profundo de Ralph Wiggum — Principios fundamentales y metodología
• Guía práctica de snarktank/ralph — Implementación minimalista de bucle externo
• Análisis profundo de GSD — Sistema completo de ingeniería de contexto construido sobre Ralph
• Arquitectura completa del sistema Claude — Comprender la arquitectura general de componentes como Hooks, Subagent, etc.