La Technique Ralph Wiggum

Mise à jour (jan. 2025) : Anthropic a livré la gestion native des tâches avec des dépendances, des bloqueurs et une coordination multi-session via CLAUDE_CODE_TASK_LIST_ID. Beaucoup de contournements Ralph sont maintenant intégrés directement dans le produit. Les principes de base décrits ci-dessous tiennent toujours. Le nouveau système gère simplement la plomberie en natif.

Tu donnes une liste de tâches à un agent. Il en prend une, écrit le code, lance les tests, commit. Puis il passe à la suivante. Et encore la suivante. Tout ça tourne pendant que tu dors.

C'est ça, Ralph Wiggum. Aucun rapport avec le gamin des Simpsons. C'est la boucle de code autonome qui est en train de transformer silencieusement la façon dont les développeurs livrent des logiciels.

Ce qui rend Ralph différent

La plupart des gens pilotent Claude Code comme une appli de chat. Prompt. Attente. Lecture. Nouveau prompt. Bien pour les petits boulots. Mais pour livrer de vraies fonctionnalités, tu deviens le maillon lent.

Ralph inverse ça. Au lieu de piloter chaque virage, tu construis une boucle qui garde Claude en marche jusqu'à ce que le travail soit terminé. L'astuce se trouve dans les stop hooks de Claude Code : ils se déclenchent au moment précis où l'agent essaie de s'arrêter, ce qui te permet d'intercepter cette tentative et de remettre l'agent au boulot.

Voici le schéma de base :

1. Claude travaille sur une tâche
2. Claude essaie de s'arrêter (émet une complétion)
3. Un stop hook intercepte et vérifie : le travail est-il vraiment terminé ?
4. Si non, réinjecte le prompt et continue
5. Si oui, laisse-le terminer

L'étape 4 est tout. Ton agent ne lâche pas à la première fois où il pense avoir fini. Il lâche seulement quand le travail a été vérifié.

La Promesse de Complétion

Ralph s'appuie sur une "promesse de complétion". Un mot ou une phrase précis qui signifie vraiment terminé. Quand Claude est convaincu que la tâche est bouclée, il émet cette promesse (généralement juste le mot "complete").

// In your Ralph loop configuration
completion_promise: "complete"
max_iterations: 25

Chaque fois que Claude essaie de s'arrêter, le hook scanne cette promesse. Absente ? La boucle continue. Présente ? La boucle s'arrête. Les sorties prématurées sont bloquées, et les vraies sorties passent proprement.

Règle critique : Sans promesse, pas d'arrêt. Ça oblige l'agent à continuer jusqu'à ce qu'il soit vraiment convaincu que le travail est fait.

La Vérification : Le Coeur Incontournable

Boris Cherny, le créateur de Claude Code, a une règle qu'il refuse de briser : donne toujours à Claude un moyen de vérifier son travail.

C'est cette règle qui fait fonctionner Ralph. Sans vérification, tu te retrouves avec une boucle qui tourne indéfiniment ou s'arrête bien trop tôt. Avec elle, la boucle sait vraiment quand elle a fini.

Trois approches de vérification fonctionnent bien avec Ralph :

1. Vérification par les tests

Écris les tests en premier. Claude les lance, les regarde échouer, écrit le code, les relance. La boucle tourne jusqu'à ce que tout soit vert.

Workflow:
1. Run all tests in /tests/feature-x/
2. If tests fail, implement code to make them pass
3. Run tests again
4. Repeat until all tests pass
5. Output "complete" only when test suite is green

C'est le chemin le plus fiable. Les tests ne mentent pas. Vert ou rouge. Rien d'ambigu.

2. Vérification par un agent en arrière-plan

Lance un second agent dont le seul rôle est de vérifier le travail de l'agent principal. Boris utilise ça pour les longues exécutions :

After completing work, use a background agent to:
1. Review all changed files
2. Run the full test suite
3. Check for regressions
4. Report any issues found

Tu obtiens une vérification indépendante. Si l'agent en arrière-plan repère des problèmes, la boucle principale reprend le travail.

3. Validation dans le stop hook

Le stop hook lui-même peut exécuter une validation. Vérifie un fichier de progression, lance le linter, contrôle le build. La validation échoue ? Bloque l'arrêt et renvoie l'agent au boulot.

// Stop hook pseudocode
if (agent_trying_to_stop) {
  validation_result = run_tests();
  if (validation_result.failed) {
    return { decision: "block", reason: "Tests failing, continue work" };
  }
  return { decision: "allow" };
}

Le Workflow en Deux Phases

La première erreur que font la plupart des gens : ils planifient et implémentent dans la même fenêtre de contexte.

Sépare-les.

Phase 1 : Session de planification

• Génère les spécifications via la conversation
• Relis et édite à la main
• Crée un plan d'implémentation avec des références de fichiers explicites
• Garde la spec comme "épingle" qui empêche les inventions

Phase 2 : Session d'implémentation

• Contexte frais (efface la conversation précédente)
• N'injecte que le document de plan
• Lance la boucle Ralph
• Laisse l'agent itérer jusqu'à complétion

Pourquoi séparer ? Parce que la dégradation de la fenêtre de contexte est réelle. Après suffisamment d'échanges, Claude commence à s'appuyer sur des messages périmés du début. Un départ propre avec seulement le plan maintient le focus.

Ton plan devient l'ancre. Chaque itération de la boucle y revient. C'est ce qui empêche l'agent de dériver vers quelque chose que tu n'as pas demandé.

Implémentation Pratique : L'Approche PRD

La version de Ryan Carson ressemble à ça :

1. Commence par un PRD (Product Requirements Document)

• Qu'est-ce qu'on construit ?
• Qu'est-ce qui est dans le scope ?
• Qu'est-ce qui est explicitement hors scope ?

2. Convertis en user stories avec critères d'acceptation

• Chaque story est une unité petite et testable
• Les critères d'acceptation définissent "terminé"

3. Structure pour la consommation par l'agent

• Format JSON ou markdown
• Des cases à cocher claires pour le suivi de progression
• Des liens vers les emplacements de code pertinents

4. Lance la boucle

• L'agent prend la prochaine story non complétée
• L'implémente
• Lance la vérification (tests)
• La marque comme complète
• Passe à la suivante

Voilà le gain : tu pars simplement. Tu te réveilles avec des fonctionnalités finies, des tests verts, et des commits déjà dans le log.

Vérification UI : Le Piège Caché

Un problème qui touche tout le monde tôt ou tard : les tests passent au vert, mais l'UI est cassée.

Voilà pourquoi. Ralph peut confirmer allègrement que le code tourne tout en restant complètement aveugle aux bugs visuels. Le composant se rend, les tests passent, et le bouton est quand même hors écran ou le texte est coupé en deux.

Règle ça avec un protocole de vérification par captures d'écran.

After implementing UI changes:
1. Take screenshots of affected components
2. Rename each with "verified_" prefix after review
3. Do NOT output completion promise yet
4. Let the next iteration confirm all files are verified
5. Only then output "complete"

Ça force au moins deux passes de boucle pour tout changement UI. La première implémente et capture les screenshots. La seconde confirme que chaque screenshot a été examiné. La vérification visuelle ne peut pas être sautée.

L'insight clé : Indique à Claude que renommer les screenshots ne vaut PAS la promesse de complétion. C'est l'itération suivante qui signale que c'est terminé. Ça bloque les sorties prématurées.

Économie : Pourquoi Ça Change Tout

Un agent de code qui tourne en continu sur Sonnet coûte environ 10,42 USD par heure (mesuré sur une utilisation de 24 heures).

Moins que le salaire minimum dans la plupart des pays. Et tu paies pour une machine qui peut :

• Vider les backlogs la nuit
• Faire tourner plusieurs fonctionnalités en parallèle
• Ne jamais se fatiguer ni se distraire
• Scaler avec plus de compute

Le goulot d'étranglement se déplace donc. Il n'est plus "combien suis-je prêt à dépenser ?" mais "combien de travail fiable puis-je définir ?"

Les équipes qui font tourner des boucles fiables vont prendre une longueur d'avance énorme sur celles qui ne le font pas. L'écart se creuse déjà.

Pannes Courantes et Correctifs

La Boucle ne Se Termine Jamais

Cause : Tâche impossible ou critères de complétion manquants. Correctif : Fixe un nombre maximum d'itérations (ex. 25). Ajoute des critères de complétion explicites à ton prompt.

La Boucle Se Termine Trop Tôt

Cause : Claude émet la promesse avant que le travail soit terminé. Correctif : Renforce ta vérification. Ajoute des tests. Utilise le protocole de screenshots pour l'UI. Rends "terminé" objectivement mesurable.

La Qualité Dégrade au Fil des Itérations

Cause : La fenêtre de contexte se remplit de tentatives échouées. Correctif : Implémente un état de checkpoint. Marque le travail complété dans un fichier externe. Laisse la boucle reprendre proprement si le contexte se remplit.

L'Agent Invente des Fonctionnalités

Cause : La spec est vague ou manquante. Correctif : Ta spec est l'"épingle" qui empêche les inventions. Rends-la spécifique. Inclus des références explicites au code existant. Dis à Claude ce qu'il ne doit PAS faire.

Mettre en Place ta Première Boucle Ralph

Commence petit pour le premier run. Choisis une fonctionnalité que tu connais bien, avec des tests qui existent déjà.

1. Installe le plugin Ralph (ou implémente toi-même le pattern de stop hook)

2. Crée ton fichier de prompt :

Study the implementation plan in /docs/plan.md
Pick the single most important incomplete task
Implement it following existing patterns
Run tests with: npm test
On pass: mark task complete in plan.md, commit changes
On fail: fix the issue and run tests again
Output "complete" only when all tasks are done and tests pass

1. Fixe des contraintes :

• Nombre max d'itérations : 25
• Promesse de complétion : "complete"
• Quality gates : les tests doivent passer, le linting doit passer

2. Observe le premier run. Ne pars pas encore. Annule si le comportement semble bizarre. Ajuste ton prompt. Relance.

3. Augmente progressivement l'autonomie au fur et à mesure que la confiance s'installe.

La Philosophie Ralph

Ralph ne vise pas à exclure les humains du code. Il vise à exclure les humains de la boucle fastidieuse entre les tentatives.

Le design est toujours le tien. Les specs sont toujours les tiennes. Tu définis ce que "terminé" signifie. Tu examines le résultat final.

Ce que Ralph prend en charge, c'est le débogage à 2h du matin. La grind interminable test-correctif-test. Le passage d'une fonctionnalité à l'autre. C'est ça qu'il gère.

Boris revient toujours à la même ligne : la vérification conduit tout. Donne à Claude un moyen de vérifier son propre travail, et il tournera fiablement pendant des heures. Enlève ça, et tu joues à la loterie.

Commence par la vérification. Construis tes boucles autour d'elle. L'avenir du code autonome, ce ne sont pas des prompts plus malins. Ce sont de meilleurs systèmes de feedback.

Prochaines Étapes

• Essaie la gestion native des tâches pour la persistance intégrée et la coordination multi-session
• Apprends les hooks pour implémenter des comportements d'arrêt personnalisés
• Explore les workflows asynchrones pour faire tourner plusieurs boucles
• Lis le guide sur le thread-based engineering pour scaler tes workflows autonomes
• Consulte les feedback loops pour les patterns de vérification

Les gens qui maîtrisent Ralph ne sont pas juste des utilisateurs de Claude Code. Ils construisent des systèmes qui livrent du code pendant qu'ils dorment.