Guide pratique de frankbria/ralph-claude-code

Introduction

L'article precedent presentait la methodologie Ralph, et snarktank/ralph montrait une implementation minimaliste de la boucle externe. Examinons maintenant une autre approche : frankbria/ralph-claude-code.

Si la philosophie de snarktank/ralph est "faire le maximum avec un minimum de code", celle de frankbria est "tout industrialiser" — assistant de configuration interactif, tableau de bord de surveillance en temps reel, disjoncteur, limitation de debit, gestion de l'expiration des sessions. L'objectif n'est pas la concision, mais la maitrise.

Les deux implementations n'ont pas de hierarchie de valeur, elles conviennent a des cas d'utilisation differents. Cet article vous presente la chaine d'outils complete de frankbria.

Installation et configuration

Installation globale

# Cloner le depot
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code

# Installation globale
./install.sh

Une fois l'installation terminee, vous disposez des commandes globales suivantes :

Initialisation du projet

Pour un projet existant, utilisez l'assistant interactif :

cd your-project
ralph-enable

L'assistant detecte automatiquement le type de projet (Node.js, Python, Go, etc.) et le framework (Next.js, FastAPI, etc.), puis genere les fichiers de configuration correspondants.

Pour un tout nouveau projet :

ralph-setup my-new-project

Cela cree le repertoire du projet, initialise Git et genere le repertoire de configuration .ralph/.

Importer des exigences existantes

Si vous disposez deja d'un document PRD ou d'une specification d'exigences :

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

Ralph analyse le document, extrait la liste des taches et genere un fix_plan.md structure.

Structure du repertoire .ralph/

La memoire et la configuration de frankbria sont centralisees dans le repertoire .ralph/ :

.ralph/
├── PROMPT.md          # Objectifs et contexte du projet
├── fix_plan.md        # Liste des taches (equivalent de prd.json)
├── AGENT.md           # Commandes de build/test (maintenu automatiquement)
├── specs/             # Documents d'exigences detailles
│   ├── feature-a.md
│   └── feature-b.md
└── sessions/          # Donnees de persistance de session
    ├── current.json
    └── history/

Comparaison avec snarktank/ralph :

Notez que AGENT.md est maintenu automatiquement — Ralph met a jour ce fichier au fil de l'execution en fonction des conventions de projet decouvertes, de maniere similaire au progress.txt de snarktank/ralph, mais de facon plus structuree.

Commandes principales

Execution de base

# Demarrer la boucle Ralph
ralph

# Avec surveillance en temps reel
ralph --monitor

# Demarrer dans tmux (recommande pour les executions longues)
ralph --live

Tableau de bord de surveillance

# Demarrer la surveillance independamment
ralph-monitor

ralph-monitor ouvre un tableau de bord tmux qui affiche en temps reel :

• La tache en cours d'execution
• Le nombre de taches terminees/en attente
• Le nombre d'appels API et l'estimation des couts
• L'etat du disjoncteur
• Les journaux d'erreurs recents

Parametres courants

# Limiter a 50 appels API, delai d'expiration de 2 heures
ralph --calls 50 --timeout 120

# Reprendre depuis la derniere interruption
ralph --resume

Mecanismes de securite

La principale caracteristique differenciante de frankbria est son systeme de securite multicouche.

Disjoncteur (Circuit Breaker)

Le disjoncteur arrete automatiquement la boucle lorsqu'il detecte une "absence de progression", evitant ainsi une consommation inutile de l'API :

Detection d'absence de progression consecutive : si aucune nouvelle tache n'est terminee apres N iterations consecutives, le disjoncteur se declenche.

Detection d'erreurs identiques : si la meme erreur apparait consecutivement, cela indique que l'IA est prise dans une boucle infinie, et le disjoncteur se declenche.

Limitation de debit

Limite par defaut de 100 appels/heure, pour eviter une explosion inattendue de la facture API. Ajustable via les parametres :

ralph --calls 200  # Augmenter a 200 appels

Detection a trois niveaux du quota API de 5 heures

L'API Anthropic dispose d'un quota d'utilisation avec une fenetre glissante de 5 heures. frankbria integre une detection a trois niveaux :

1. Pre-detection : estimation du quota restant avant chaque appel API
2. Detection de reponse : analyse des headers de rate limit dans les reponses API
3. Strategie de repli : reduction automatique de la frequence d'appels a l'approche du quota

Gestion de l'expiration des sessions

Duree de validite par defaut de la session : 24 heures. Au-dela, les donnees de session sont automatiquement nettoyees pour eviter qu'un contexte perime n'affecte les executions suivantes.

Detection intelligente de sortie

frankbria ne se contente pas de quitter simplement lorsque toutes les taches sont terminees. Il utilise une porte de sortie a double condition :

Condition de sortie = completion_indicators >= 2 AND EXIT_SIGNAL: true

completion_indicators represente le nombre de signaux d'achevement detectes dans la sortie de l'IA, notamment :

• "Toutes les taches sont terminees"
• "Il n'y a plus d'elements a traiter"
• Tous les tests passent
• Toutes les entrees de fix_plan.md sont marquees comme done

EXIT_SIGNAL est une declaration explicite d'intention de sortie par l'IA dans sa sortie.

Pourquoi deux conditions ? Pour eviter une sortie prematuree. Un signal unique peut etre un faux positif — par exemple, l'IA dit "tache terminee" alors qu'elle n'a termine que la story en cours. La double condition garantit que la sortie n'a lieu que lorsque plusieurs signaux independants confirment tous l'achevement.

Comparaison avec snarktank/ralph

Difference fondamentale : le degre d'industrialisation

Les deux sont des boucles bash externes lancant de nouveaux processus Claude. La difference fondamentale ne reside pas dans le mode de gestion des sessions (frankbria peut basculer en mode nouvelle session via --no-continue), mais dans le degre d'industrialisation :

• snarktank : script minimaliste, quelques centaines de lignes de bash, concentre sur la boucle elle-meme
• frankbria : chaine d'outils entierement industrialisee — tableau de bord de surveillance, disjoncteur, limitation de debit, gestion de l'expiration des sessions

frankbria active --continue par defaut pour reutiliser les sessions, adapte aux taches courtes. Pour les taches longues, vous pouvez utiliser --no-continue pour basculer en mode nouvelle session, obtenant la meme protection contre le Context Rot que snarktank, tout en conservant les avantages d'industrialisation de frankbria.

Comment desactiver la reutilisation de session

frankbria propose trois methodes pour desactiver --continue :

# Methode 1 : parametre en ligne de commande
ralph --no-continue

# Methode 2 : variable d'environnement
export CLAUDE_USE_CONTINUE=false

# Methode 3 : configuration .ralphrc
SESSION_CONTINUITY=false

Une fois desactive, le comportement de frankbria est equivalent a celui de snarktank (nouvelle session a chaque fois), tout en conservant tous les outils d'ingenierie (surveillance, disjoncteur, limitation de debit, etc.).

Les compromis concrets du Context Rot

Le choix du mode de reutilisation de session est fondamentalement un compromis entre le Context Rot et le cout de demarrage :

Taches courtes (< 50k tokens) : la reutilisation de session est plus avantageuse. Le contexte n'a pas encore eu le temps de se degrader, et la memoire des premieres iterations peut encore etre exploitee par les suivantes. Le cout de demarrage d'une nouvelle session a chaque fois est plutot du gaspillage.

Taches longues (100k+ tokens) : les nouvelles sessions sont plus fiables. Au-dela de 100k tokens, le Context Rot s'intensifie nettement, et le contexte accumule passe d'un atout a un passif. Les nouvelles sessions ont un cout de demarrage, mais elles offrent un etat optimal a chaque fois.

Recommandations pratiques :

Les utilisateurs de frankbria peuvent choisir de maniere flexible en fonction de l'ampleur des taches : mode --continue par defaut pour les taches courtes, basculement en mode --no-continue pour les taches longues. Par rapport a snarktank, l'avantage de frankbria est de conserver la chaine d'outils d'ingenierie complete quel que soit le mode choisi.

Conclusion

frankbria/ralph-claude-code represente la voie d'implementation industrialisee de la methodologie Ralph. Il sacrifie une partie de la concision de snarktank au profit d'une surveillance, d'une securite et d'une capacite de configuration plus abouties.

Le choix de l'implementation depend de vos besoins specifiques — il n'y a pas de reponse "plus correcte", seulement un choix "plus adapte".

Lectures complementaires :

• Analyse approfondie de Ralph Wiggum — Principes fondamentaux et methodologie
• Guide pratique de snarktank/ralph — Implementation minimaliste de la boucle externe
• Analyse approfondie de GSD — Systeme complet d'ingenierie de contexte construit sur Ralph
• Architecture complete du systeme Claude — Comprendre l'architecture globale des composants tels que Hooks, Subagent, etc.