Débuter avec Ralph Wiggum Part 1 : introduction et fondamentaux

Tu fixes une tâche de migration fastidieuse — 200 fichiers de tests à convertir de Jest à Vitest. Les patterns sont clairs. Le travail est mécanique. Mais ça va te prendre toute la journée.

Ou tu pourrais taper une commande, aller déjeuner, et revenir pour trouver le tout terminé.

C'est ça Ralph Wiggum. Et une fois que tu l'as utilisé, tu te demanderas comment tu as pu travailler sans.

Qu'est-ce que Claude Code ?

Claude Code est le CLI officiel d'Anthropic pour Claude — un assistant de coding en terminal qui peut lire, écrire et éditer des fichiers dans ta codebase. Contrairement aux interfaces de chat, Claude Code travaille directement avec tes fichiers locaux, exécute des commandes et s'intègre dans ton workflow de développement. Pour une introduction complète, voir Claude Code Mastery Part 1: Getting Started.

Qu'est-ce que Ralph Wiggum ?

Ralph est un plugin Claude Code qui transforme ton assistant IA en agent de coding autonome. Au lieu du va-et-vient habituel — prompt, review, prompt, review — tu donnes une tâche à Ralph et tu t'en vas. Il travaille jusqu'à ce que le travail soit réellement terminé.

La philosophie est simple : Itération > Perfection. N'essaie pas de viser juste du premier prompt. Laisse la boucle s'en charger.

Comme le dit Geoffrey Huntley, le créateur de la technique : "Ralph est une boucle Bash." C'est littéralement ce que c'est — un while true qui renvoie le même prompt à Claude jusqu'à ce que les critères de complétion soient remplis.

Voici la mécanique :

1. Tu donnes à Claude une tâche avec des critères de complétion clairs
2. Claude travaille dessus et essaie de quitter quand c'est "fini"
3. Un hook Stop intercepte et vérifie : est-ce vraiment fini ? (Les hooks sont des actions automatisées qui s'exécutent à des points spécifiques du cycle de vie de Claude — voir Mastery Part 3 pour les détails)
4. Si non, le même prompt est renvoyé
5. Claude voit son travail précédent dans les fichiers
6. La boucle continue jusqu'à la complétion réelle

L'insight clé ? Le prompt ne change jamais — mais la codebase oui. Chaque itération construit sur la précédente. Claude lit son propre travail antérieur et l'améliore.

Pourquoi c'est important

Ce n'est pas théorique. Des développeurs font tourner des sessions autonomes de 14 heures qui migrent des codebases entières. Geoffrey Huntley a fait tourner une boucle de 3 mois qui a construit un langage de programmation. VentureBeat a qualifié Ralph de "plus grand nom de l'IA en ce moment."

Le plugin a été formalisé par Boris Cherny, le responsable de Claude Code chez Anthropic. C'est officiel. C'est prêt pour la production. Et ça change la façon dont les développeurs sérieux travaillent.

Pour démarrer (5 minutes)

Étape 1 : installe la dépendance

Ralph a besoin de jq pour le traitement JSON. Installe-le d'abord :

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Windows: Use WSL or grab it from https://stedolan.github.io/jq/

Étape 2 : installe le plugin

Dans Claude Code, lance /plugin pour ouvrir l'interface de découverte des plugins. Cherche "ralph" et sélectionne ralph-loop depuis les plugins officiels.

Ou installe directement avec :

/plugin install ralph-loop@claude-plugins-official

Étape 3 : configure les permissions

Voici ce qui coince pour la plupart des gens : Ralph tourne de manière autonome, ce qui veut dire qu'il ne peut pas s'arrêter et te demander "c'est ok ?" pour chaque édition de fichier. Si tu ne configures pas les permissions, la boucle casse dès que Claude tombe sur une demande de permission.

Option A : pré-approuver dans les paramètres (recommandé)

Ajoute les outils dont Ralph a besoin dans ton .claude/settings.local.json :

{
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "Bash(npm:test *)",
      "Bash(npm:run build *)",
      "Bash(git:add *)",
      "Bash(git:commit *)"
    ]
  }
}

Comprendre la syntaxe des permissions : Le pattern Bash(npm:test *) signifie "autoriser toute commande Bash commençant par npm test". Le * sert de joker. Ça donne à Ralph la permission de lancer les tests sans te demander à chaque fois. Voir Mastery Part 3: Project Configuration pour tous les détails sur les patterns de permissions.

Option B : utiliser les flags de permission

Pour les tâches longue durée dans un environnement sandboxé, tu peux contourner les prompts de permission entièrement :

claude --dangerously-skip-permissions
# or
claude --permission-mode acceptEdits

Attention : Utilise --dangerously-skip-permissions uniquement dans des environnements sandboxés (conteneurs, VMs, instances cloud jetables). Ça donne à Claude un accès complet à ton système de fichiers.

Comme le note Boris Cherny, pour les tâches très longues tu voudras soit --permission-mode=acceptEdits soit --dangerously-skip-permissions dans un sandbox pour que Claude ne reste pas bloqué à t'attendre.

Option C : sandboxing complet (recommandé pour les tâches longue durée)

Pour le travail autonome sérieux, le sandboxing intégré de Claude Code isole Ralph tout en permettant les opérations nécessaires. Active-le en lançant /sandbox dans Claude Code, ce qui fournit une isolation au niveau OS du système de fichiers et du réseau.

Tu peux aussi configurer des règles de permission dans .claude/settings.json pour contrôler ce à quoi Ralph peut accéder :

{
  "permissions": {
    "allow": [
      "WebFetch(domain:registry.npmjs.org)",
      "WebFetch(domain:github.com)"
    ],
    "deny": [
      "Bash(sudo:*)",
      "Bash(docker:*)",
      "Read(./.env)",
      "Read(~/.ssh/**)"
    ]
  }
}

Personnalise les listes allow/deny selon les besoins de ton projet. Voir le guide de JeredBlu pour plus d'exemples de configuration.

Étape 4 : lance ta première boucle

Commence petit. Voici une première expérience sans risque :

/ralph-loop "Add JSDoc comments to all exported functions in src/utils.ts. Output <promise>DONE</promise> when complete." --completion-promise "DONE" --max-iterations 10

Regarde ça tourner. Revois les commits. Prends le rythme.

Les deux paramètres qui comptent

--max-iterations est ton filet de sécurité. Définis-le toujours. La valeur par défaut est illimitée, ce qui veut dire que Ralph tournera indéfiniment si la promesse de complétion ne se déclenche jamais.

Commence petit. 10-20 itérations pour tes premiers essais. Une boucle de 50 itérations sur une grosse codebase peut coûter 50-100 $+ en crédits API.

--completion-promise dit à Ralph quand s'arrêter. C'est du string matching exact — Claude doit émettre ce texte précis pour signaler la complétion.

/ralph-loop "<your task>" --max-iterations 30 --completion-promise "TASK COMPLETE"

Plugin vs boucle Bash vs TUI : lequel utiliser

Il y a trois façons de faire tourner Ralph :

Méthode Plugin (/ralph-loop)

• Tourne dans une seule fenêtre de contexte
• Le plus facile à configurer — zéro configuration
• Bon pour les tâches de moins de 20-30 itérations

Méthode boucle Bash

• Lance une fenêtre de contexte fraîche par itération
• Empêche le gonflement du contexte et les hallucinations
• Nécessite un setup manuel de prompt et de fichiers

Ralph TUI (couvert dans Part 3)

• Contexte frais par itération (comme la boucle bash)
• Création de PRD intégrée, suivi des tâches et tableau de bord de monitoring
• Gère tout le jonglage de prompts et la gestion de fichiers pour toi
• Le meilleur pour les builds longue durée sérieux

Qu'est-ce qu'une fenêtre de contexte ? La fenêtre de contexte est la mémoire de travail de Claude — tout ce que Claude sait de ta conversation doit tenir ici (~200K tokens). Au fur et à mesure que tu travailles, elle se remplit avec tes prompts, le code et les réponses de Claude. Quand elle est pleine, Claude commence à oublier les détails antérieurs. Voir Mastery Part 2: Mental Model pour une explication plus approfondie.

Voici un exemple minimal de boucle bash :

#!/bin/bash
# loop.sh - Run this instead of the plugin for long tasks
for ((i=1; i<=30; i++)); do
  echo "=== Iteration $i ==="
  result=$(claude -p "$(cat PROMPT.md)" --output-format text 2>&1) || true
  echo "$result"

  if [[ "$result" == *"ALL TASKS COMPLETE"* ]]; then
    echo "Done after $i iterations"
    exit 0
  fi
done

Comme le note JeredBlu, la méthode boucle bash est "fondamentalement meilleure pour les tâches longue durée" parce que chaque itération repart de zéro. Le plugin fait tout tourner dans un seul contexte, ce qui peut mener à une dégradation des performances après 30-40 itérations.

Voir des implémentations réelles : Parcours des setups Ralph complets de la communauté :

• snarktank/ralph — ralph.sh complet, prompt.md et AGENTS.md
• ClaytonFarr/ralph-playbook — Templates PROMPT_plan.md et PROMPT_build.md
• frankbria/ralph-claude-code — Implémentation avec détection intelligente de sortie

Tu n'utilises pas Claude Code ? Ralph fonctionne aussi avec d'autres outils :

• ralph-wiggum-cursor — Intégration Cursor IDE avec suivi des tokens
• aymenfurter/ralph — Extension VS Code avec panneau de contrôle visuel
• opencode-ralph-wiggum — OpenCode avec détection de blocage

Recommandation : Commence par le plugin pour apprendre les concepts. Pour les tâches longue durée en production, utilise Ralph TUI — il te donne les avantages de l'approche boucle bash sans le setup manuel. Voir Part 3 pour le guide TUI complet.

Écrire des prompts qui marchent

Voici la différence entre un prompt qui tourne en rond et un qui finit proprement :

Mauvais prompt (complétion vague) :

Make the code better.

Bon prompt (spécifique et testable) :

Add comprehensive error handling to src/api/users.ts.

Requirements:
- Wrap all async operations in try/catch
- Return proper HTTP status codes
- Log errors with context
- Add input validation for all endpoints

Run tests after each change. Fix any failures before moving on.

When ALL tests pass, output: <promise>COMPLETE</promise>

Le bon prompt a :

• Un scope clair — fichier spécifique, changements spécifiques
• Des critères testables — "les tests passent" c'est binaire, pas subjectif
• Des portes qualité intégrées — "corrige les échecs avant de continuer"
• Un signal de complétion explicite — texte exact à émettre quand c'est fini

Quand utiliser Ralph (et quand non)

Ralph excelle pour :

• Le refactoring mécanique — Jest → Vitest, CommonJS → ESM
• L'ajout de tests — "Monte la couverture à 80% sur ce module"
• Les opérations CRUD — "Ajoute des endpoints de gestion utilisateurs avec validation"
• La documentation — "Ajoute des JSDoc à toutes les fonctions publiques"
• Les migrations — "Mets à jour tous les imports pour utiliser des path aliases"

N'utilise pas Ralph pour :

• Les décisions esthétiques — "Rends l'UI plus jolie" n'est pas testable
• Les éditions one-shot — Si ça prend 30 secondes manuellement, fais-le toi-même
• Le debug en production — Tu as besoin de contexte et de jugement, pas d'itération
• Les objectifs flous — "Améliore ça" va tourner en boucle indéfiniment

La règle de base : Si tu peux écrire un test automatisé pour "c'est fini," Ralph peut le faire. Si la complétion nécessite un jugement humain, fais-le toi-même.

La philosophie Ralph

Le Ralph Playbook documente quatre principes fondamentaux qui font que ça marche :

1. Itération > Perfection — N'essaie pas de viser juste du premier prompt. Laisse la boucle affiner.
2. Les échecs sont des données — Quand Ralph échoue, tu apprends à écrire de meilleurs prompts.
3. La compétence de l'opérateur compte — La qualité de ton prompt détermine le taux de réussite de Ralph.
4. La persistance gagne — La boucle gère les retries automatiquement. Toi, tu définis juste "fini."

Le mantra de la communauté : "Mieux vaut échouer de façon prévisible que réussir de façon imprévisible."

Monitorer les boucles longue durée

Quand Ralph tourne pendant de longues périodes, tu voudras de la visibilité. Ralph TUI te donne un tableau de bord en temps réel : nombre d'itérations, tâche en cours, consommation de tokens et contrôles clavier pour mettre en pause ou arrêter.

Le monitoring est couvert en détail dans Part 3: Ralph TUI Monitoring.

La suite

Tu as installé Ralph. Tu comprends la boucle. Tu sais quand l'utiliser et quand faire les choses manuellement.

Mais on n'a fait qu'effleurer la surface.

Dans Part 2: The Three-Phase Methodology, on couvrira le workflow professionnel — des prompts séparés pour la planification et la construction, des fichiers de spec qui guident les projets multi-jours, et les techniques qui font que les builds autonomes longue durée marchent vraiment. C'est là que Ralph passe d'un "outil utile" à un "multiplicateur de force."

Glossaire

Nouveau sur Claude Code ? Voici les termes clés que tu rencontreras tout au long de cette série :

Fenêtre de contexte — La mémoire de travail de Claude. Tout ce que Claude sait de ta conversation doit tenir ici (~200K tokens). En savoir plus

Backpressure — Validation automatisée (tests, lints, vérifications de types) qui rejette le mauvais travail, forçant Claude à itérer jusqu'à correction

Promesse de complétion — Texte exact que Claude doit émettre pour signaler la complétion de la tâche. Ralph utilise du string matching pour le détecter

Itération — Un cycle complet penser-agir-observer-corriger. Une tâche peut nécessiter plusieurs itérations

Sous-agent — Worker IA spécialisé avec un contexte indépendant qui tourne en parallèle. En savoir plus

MCP — Model Context Protocol. Connecte Claude à des services externes comme les bases de données, APIs et automatisation du navigateur. En savoir plus

Ultrathink — Mot-clé qui alloue le budget de réflexion maximum (~32K tokens) pour le raisonnement complexe. En savoir plus