Un développeur a lancé une commande à 22h. À 7h le lendemain, 47 commits l’attendaient. Une feature complète. Testée. Documentée. Prête pour la review.
Ce n’est pas une promesse marketing. C’est ce que permet Ralph Wiggum, une technique qui force Claude Code à travailler en boucle jusqu’à terminer le travail.
Le nom vient d’un personnage des Simpsons connu pour sa persistance naïve. L’idée : faire travailler l’IA de manière simple et répétitive jusqu’à atteindre l’objectif. Pas de magie. Juste de la ténacité automatisée.
Ce guide vous montre comment l’utiliser concrètement.
Ce que Ralph change vraiment
Claude Code standard fonctionne en mode conversation. Vous demandez, il répond, vous validez. Efficace pour des tâches courtes. Problématique pour des projets ambitieux.
Après 150 000 tokens environ, Claude vous demande de “compacter” la conversation. Il perd le contexte. Vous devez relancer. Sur une feature de 20 fichiers, comptez une dizaine d’interventions manuelles.
Ralph supprime ce problème.
Au lieu d’une longue conversation, Ralph découpe le travail en tâches atomiques. Claude traite une tâche, commit, puis s’arrête. Un script le relance immédiatement pour la tâche suivante. La mémoire persiste dans les fichiers, pas dans la conversation.
Le résultat : Claude peut générer plus d’un million de tokens sur un projet. Là où il s’arrêtait après 200 000.
Geoffrey Huntley, créateur de la technique, résume simplement : “Ralph est une boucle Bash.” Rien de complexe. L’efficacité vient de la répétition systématique, pas de l’intelligence.
Comment ça fonctionne techniquement
Ralph repose sur trois fichiers qui servent de mémoire externe à Claude.
Le fichier prd.json liste les tâches à accomplir. Chaque tâche a un statut : fait ou à faire. Claude lit ce fichier, trouve la première tâche non terminée, l’exécute, puis met à jour le statut.
Le fichier prompt.md contient les instructions pour chaque itération. Il dit à Claude quoi faire : lire le PRD, implémenter la tâche, commit, mettre à jour le statut, documenter.
Le fichier progress.txt garde trace des décisions et actions. Claude y écrit ce qu’il a fait, les problèmes rencontrés, les fichiers modifiés. Ce fichier devient la mémoire entre les itérations.
Un script bash orchestre le tout :
while [ "$REMAINING_TASKS" -gt 0 ]; do
claude --dangerously-skip-permissions -p "$(cat prompt.md)"
sleep 2
done
Chaque itération est indépendante. Claude ne garde pas le contexte de l’itération précédente. Il reconstruit sa compréhension à partir des fichiers. Cette approche contourne la limite de contexte.
Le flag --dangerously-skip-permissions permet à Claude d’agir sans demander confirmation. Sans lui, vous devriez valider chaque action manuellement. Ce qui annulerait l’intérêt de l’autonomie.
Les deux méthodes d’installation
Deux approches existent. Le plugin officiel d’Anthropic. Et la méthode script personnalisé.
Le plugin officiel
Anthropic a intégré Ralph directement dans Claude Code. Installation en une commande :
/plugin install ralph-wiggum
Utilisation :
/ralph-loop "Migrer tous les tests de Jest vers Vitest" --max-iterations 25 --completion-promise "DONE"
Le plugin utilise un “Stop Hook” qui intercepte les tentatives de sortie de Claude. Si le travail n’est pas terminé, il réinjecte le prompt. La boucle se fait dans la même session.
Avantages : simple, intégré, pas de script externe. Limites : moins de contrôle sur le workflow, pas de gestion de tâches structurée.
La méthode script personnalisé
L’alternative est de créer vos propres fichiers. Plus de travail initial, mais plus de contrôle.
Créez un dossier .claude/ralph/ dans votre projet avec quatre fichiers :
prompt.md — Les instructions pour Claude :
Tu es en mode Ralph.
1. Lis prd.json et trouve la première tâche avec pass: false
2. Implémente cette tâche uniquement
3. Commit avec un message descriptif
4. Mets pass: true dans prd.json
5. Documente ton travail dans progress.txt
6. Si toutes les tâches sont terminées, écris RALPH_COMPLETE
prd.json — La liste des tâches :
{
"feature": "API Utilisateurs",
"stories": [
{"id": 1, "pass": false, "title": "Créer l'entité User", "note": "Champs: id, email, passwordHash, createdAt"},
{"id": 2, "pass": false, "title": "Créer le UserService", "note": "Méthodes: create, findById, update, delete"},
{"id": 3, "pass": false, "title": "Créer le UserController", "note": "Routes REST standard"},
{"id": 4, "pass": false, "title": "Ajouter les tests", "note": "Couverture 80% minimum"}
]
}
progress.txt — Fichier de mémoire, initialement vide ou avec un en-tête.
ralph.sh — Le script de boucle :
#!/bin/bash
for ((i=1; i<=25; i++)); do
REMAINING=$(jq '[.stories[] | select(.pass == false)] | length' prd.json)
[ "$REMAINING" -eq 0 ] && echo "Terminé" && break
OUTPUT=$(claude --dangerously-skip-permissions -p "$(cat prompt.md)
### prd.json
$(cat prd.json)
### progress.txt
$(cat progress.txt)")
echo "$OUTPUT" | grep -q "RALPH_COMPLETE" && break
sleep 2
done
Lancez avec ./ralph.sh et partez faire autre chose.
Quand utiliser Ralph, quand s’abstenir
Ralph excelle sur certains types de tâches. Il échoue sur d’autres.
Utilisez Ralph pour :
Les migrations techniques. Passer de Jest à Vitest. Mettre à jour une version de framework. Convertir des composants class vers functional. Tâches répétitives avec critère de succès clair : les tests passent ou non.
La génération de tests. Ajouter la couverture sur un module existant. Claude peut itérer jusqu’à atteindre le pourcentage cible. Mesurable. Automatisable.
Les refactorings systématiques. Standardiser la gestion d’erreurs. Remplacer une dépendance partout. Appliquer un pattern à tous les fichiers d’un dossier.
Les corrections de bugs en lot. Listez 10 bugs dans prd.json. Ralph les corrige un par un pendant la nuit.
Évitez Ralph pour :
Les décisions architecturales. Choisir entre GraphQL et REST. Définir la structure d’une base de données. Ces décisions nécessitent du jugement humain.
Les features floues. “Améliorer l’UX” n’est pas une tâche Ralph. “Ajouter un bouton de confirmation sur le formulaire de suppression” l’est.
Le code critique sans filet de sécurité. Si une erreur de Ralph peut casser la production, gardez un humain dans la boucle.
La règle simple : si vous pouvez vérifier automatiquement que le travail est bien fait (tests, linting, compilation), Ralph convient. Sinon, supervisez.
Les coûts réels
La question revient toujours. Combien ça coûte ?
Les chiffres varient selon la complexité. Voici des ordres de grandeur observés.
Une itération simple consomme 5 000 à 10 000 tokens. Une itération complexe avec beaucoup de contexte peut atteindre 20 000 tokens.
Sur 25 itérations moyennes, comptez 200 000 à 400 000 tokens. Avec les tarifs Claude actuels, cela représente 3 à 8 dollars pour le modèle Sonnet.
Un cas extrême documenté : des équipes YC hackathon ont livré 6 dépôts complets pour 297 dollars de coûts API. Geoffrey Huntley a fait tourner une boucle pendant 3 mois pour construire un langage de programmation.
Pour un abonnement Claude Pro à 20$/mois avec quota limité, surveillez votre consommation. Ralph peut épuiser votre quota hebdomadaire en une nuit.
Le calcul à faire : combien d’heures de travail manuel Ralph remplace-t-il ? Si une feature de 5 heures coûte 10 dollars en API mais vous libère une demi-journée, le ROI est évident.
Configuration d’un projet type
Prenons un cas concret. Vous voulez ajouter un système d’authentification JWT à une API Express existante.
Première étape : définir les tâches dans prd.json.
{
"feature": "Authentification JWT",
"branch": "feature/auth-jwt",
"stories": [
{
"id": 1,
"pass": false,
"title": "Explorer le code existant",
"note": "Analyser la structure actuelle. Identifier où placer les nouveaux fichiers. Documenter dans progress.txt les conventions observées."
},
{
"id": 2,
"pass": false,
"title": "Installer les dépendances",
"note": "Ajouter jsonwebtoken et bcrypt. Mettre à jour package.json et package-lock.json."
},
{
"id": 3,
"pass": false,
"title": "Créer le service AuthService",
"note": "Fichier src/services/AuthService.ts. Méthodes: hashPassword, comparePassword, generateToken, verifyToken. Utiliser les patterns du projet."
},
{
"id": 4,
"pass": false,
"title": "Créer le middleware d'authentification",
"note": "Fichier src/middlewares/auth.ts. Vérifier le header Authorization. Décoder le token. Attacher l'utilisateur à req.user."
},
{
"id": 5,
"pass": false,
"title": "Ajouter les routes login et register",
"note": "POST /auth/login et POST /auth/register. Validation des inputs. Réponses JSON standardisées."
},
{
"id": 6,
"pass": false,
"title": "Protéger les routes existantes",
"note": "Appliquer le middleware auth sur les routes qui nécessitent une authentification. Identifier ces routes dans le code existant."
},
{
"id": 7,
"pass": false,
"title": "Écrire les tests",
"note": "Tests pour AuthService et middleware. Cas: token valide, token expiré, token absent, credentials invalides. Minimum 80% couverture sur les nouveaux fichiers."
},
{
"id": 8,
"pass": false,
"title": "Vérification finale",
"note": "Lancer npm test. Lancer npm run lint. Corriger les erreurs. S'assurer que tout compile."
}
]
}
Chaque tâche est atomique. Une seule responsabilité. Un critère de succès implicite.
La première tâche est cruciale : l’exploration. Claude analyse le code existant et documente ses observations. Ces notes serviront de contexte pour les tâches suivantes.
La dernière tâche sert de filet de sécurité. Elle attrape les problèmes résiduels.
Écrire des prompts qui fonctionnent
La qualité du prompt détermine la qualité des résultats. Un prompt vague produit du code vague.
Le prompt doit être explicite sur le processus :
Tu travailles en mode Ralph sur une itération unique.
ÉTAPE 1 : IDENTIFICATION
Lis prd.json fourni ci-dessous. Trouve la PREMIÈRE tâche avec "pass": false.
ÉTAPE 2 : EXÉCUTION
Implémente cette tâche en suivant les instructions dans "note".
Respecte les conventions du projet.
Si tu rencontres un problème, documente-le et continue.
ÉTAPE 3 : VALIDATION
Lance les tests si applicable.
Vérifie que le code compile.
Corrige les erreurs avant de continuer.
ÉTAPE 4 : COMMIT
git add -A
git commit -m "feat: [titre de la tâche]"
ÉTAPE 5 : MISE À JOUR
Dans prd.json, change "pass": false en "pass": true pour la tâche terminée.
ÉTAPE 6 : DOCUMENTATION
Ajoute dans progress.txt :
- Date et heure
- Tâche terminée
- Fichiers modifiés
- Problèmes rencontrés et solutions
ÉTAPE 7 : FIN
Si toutes les tâches ont pass: true, écris exactement : RALPH_COMPLETE
Sinon, termine normalement.
RÈGLES :
- UNE seule tâche par itération
- Toujours commit après chaque tâche
- Ne jamais anticiper sur les tâches suivantes
Ce prompt laisse peu de place à l’interprétation. Claude sait exactement quoi faire à chaque étape.
Surveiller pendant l’exécution
Même en mode autonome, vous pouvez observer ce qui se passe.
Ouvrez un terminal séparé et suivez le fichier progress :
tail -f .claude/ralph/progress.txt
Vous verrez les entrées s’ajouter en temps réel. Utile pour repérer si Ralph tourne en rond sur une tâche.
Pour voir l’avancement des tâches :
watch -n 5 'cat .claude/ralph/prd.json | jq ".stories[] | {id, title, pass}"'
Cette commande rafraîchit l’affichage toutes les 5 secondes.
Les commits Git montrent aussi le travail accompli :
watch -n 10 'git log --oneline -5'
Si Ralph bloque sur une tâche depuis trop longtemps, vous pouvez interrompre avec Ctrl+C. Les tâches déjà terminées restent commitées. Vous pouvez ajuster la tâche problématique et relancer.
Les erreurs courantes à éviter
Après avoir observé des dizaines d’exécutions Ralph, certains patterns d’échec reviennent.
Tâches trop larges
“Implémenter toute l’authentification” est trop vague. Claude peut partir dans une mauvaise direction pendant plusieurs itérations avant d’échouer. Découpez en tâches de 10-15 minutes maximum.
Instructions ambiguës
“Ajouter des tests” ne dit pas quels tests, pour quels cas, avec quelle couverture cible. Soyez précis : “Tests unitaires pour UserService couvrant les cas : création réussie, email dupliqué, validation échouée.”
Pas de tâche d’exploration initiale
Si Claude ne connaît pas la structure du projet, il invente. Commencez toujours par une tâche qui analyse le code existant et documente les conventions.
Oublier la tâche de vérification finale
Sans tâche finale qui lance les tests et le linting, vous risquez de vous retrouver avec du code qui ne compile pas. Ajoutez systématiquement une tâche de cleanup.
Pas de fichier CLAUDE.md
Claude travaille mieux s’il connaît le contexte du projet. Créez un fichier CLAUDE.md à la racine décrivant l’architecture, les conventions, les technologies utilisées. Il sera lu automatiquement.
L’alternative du plugin officiel
Le plugin ralph-wiggum d’Anthropic simplifie certains aspects. Il gère la boucle en interne, sans script externe.
Installation :
/plugin install ralph-wiggum
Utilisation basique :
/ralph-loop "Migrer les composants React de class vers functional hooks" --max-iterations 30 --completion-promise "MIGRATION_COMPLETE"
Le paramètre --completion-promise définit le signal de fin. Quand Claude écrit exactement cette chaîne, la boucle s’arrête.
Pour des tâches complexes, structurez le prompt :
/ralph-loop "Implémenter le système de notifications.
Critères de succès :
- Service NotificationService créé
- Routes POST /notifications et GET /notifications/:userId
- Tests avec couverture > 80%
- Documentation Swagger ajoutée
Si bloqué après 20 itérations :
- Documenter ce qui bloque
- Lister les approches tentées
- Suggérer des alternatives
Output <promise>NOTIFICATIONS_DONE</promise> quand terminé." --max-iterations 30
Le plugin est plus simple pour des tâches ponctuelles. Le script personnalisé convient mieux pour des workflows structurés avec prd.json.
Ce que Ralph ne fait pas
Ralph automatise l’exécution. Il ne remplace pas la réflexion.
Il ne choisit pas quoi construire. Vous définissez les tâches. Ralph les exécute.
Il ne garantit pas la qualité. Le code produit peut fonctionner mais être mal structuré. Une review reste nécessaire.
Il ne gère pas les décisions ambiguës. Face à deux approches possibles, Claude en choisit une arbitrairement. Si le choix compte, spécifiez-le dans les instructions.
Il ne protège pas contre les erreurs coûteuses. Un prompt mal écrit peut faire tourner Claude en boucle pendant des heures. Le paramètre --max-iterations est votre filet de sécurité.
Geoffrey Huntley résume la philosophie : “Mieux vaut échouer de manière prévisible que réussir de manière imprévisible.” Ralph échoue souvent. Mais ses échecs sont instructifs. Ils montrent où le prompt doit être amélioré.
Par où commencer
Si vous n’avez jamais utilisé Ralph, commencez petit.
Choisissez une tâche répétitive que vous repoussez. Ajouter des tests sur un module. Mettre à jour des dépendances. Standardiser le formatage d’un dossier.
Créez un prd.json avec 3-4 tâches simples. Lancez Ralph avec --max-iterations 10. Observez ce qui se passe.
Votre premier essai ne sera pas parfait. C’est normal. Chaque échec vous apprend quelque chose sur l’écriture des prompts.
Après quelques essais, vous saurez quelles tâches confier à Ralph. Vous aurez des templates de prompt qui fonctionnent pour votre type de projet.
Le développeur qui se réveille avec 47 commits n’y est pas arrivé du premier coup. Il a itéré sur ses prompts jusqu’à trouver ce qui marche.
Ralph est un outil. Sa valeur dépend de comment vous l’utilisez.
Ressources pour aller plus loin :
- Documentation officielle du plugin : github.com/anthropics/claude-code/blob/main/plugins/ralph-wiggum/README.md
- Implémentation communautaire avec gestion avancée : github.com/frankbria/ralph-claude-code
- Article originel de Geoffrey Huntley sur la philosophie Ralph : ghuntley.com/ralph
- Guide des 11 tips pour utilisateurs avancés : aihero.dev/tips-for-ai-coding-with-ralph-wiggum
- Analyse technique détaillée : paddo.dev/blog/ralph-wiggum-autonomous-loops