Débuter avec Ralph : Faire tourner des agents IA en boucle pour coder à votre place

Ralph est une technique pour faire tourner des agents de développement IA en boucle. Vous exécutez le même prompt de manière répétée. L'IA choisit ses propres tâches à partir d'un PRD (Product Requirements Document) ou d’un plan d’implémentation créé à partir d’un PRD (voir mon guide du vibe coder). Elle commit après chaque fonctionnalité. Vous revenez plus tard devant du code fonctionnel.

Ce guide vous accompagne dans la création de votre première boucle Ralph. Nous utiliserons Claude Code et Docker Desktop.

Ce tutoriel est prévu pour Linux, mais vous pouvez demander à une IA de traduire ces instructions pour votre système d'exploitation ou votre CLI de codage IA.

Pour plus de conseils sur Ralph, consultez les 11 conseils de Matt Pocock pour coder avec Ralph.
Ou mes conseils de vibe coding (en français).

1. Installer Claude Code

Claude Code est le CLI d'Anthropic pour le codage agentique. Installez-le avec le binaire natif, puis si vous obtenez "command not found: claude" après l'installation, ajoutez l'emplacement d'installation à votre PATH :

bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Vous pouvez aussi l'installer via npm :

bash

npm i -g @anthropic-ai/claude-code

Lancez claude pour vous authentifier avec votre compte Anthropic.

2. Installer Docker Desktop

Docker Desktop vous permet d'exécuter Claude Code dans un sandbox isolé. L'IA peut exécuter des commandes, installer des packages et modifier des fichiers sans toucher à votre machine locale.

Installez Docker Desktop 4.50+ puis lancez :

bash

docker sandbox run claude

Au premier lancement, vous vous authentifierez avec Anthropic. Vos identifiants sont stockés dans un volume Docker.

Avantages clés des sandboxes :

• Votre répertoire de travail est monté au même chemin à l'intérieur du conteneur

• La config Git est automatiquement injectée pour une attribution correcte des commits

• Un sandbox par workspace : l'état persiste entre les exécutions

Consultez la documentation Docker Sandboxes pour plus de détails.

3. Créer votre fichier de plan

Ralph a besoin d'un PRD (Product Requirements Document) pour choisir ses tâches. Vous pouvez en écrire un manuellement, mais c'est plus rapide d'utiliser le mode plan de Claude.

Lancez Claude :

bash

claude

Puis appuyez sur shift-tab pour entrer en mode plan. Vous pourrez itérer sur un plan jusqu'à ce qu'il vous convienne.

Quand vous êtes satisfait du plan, demandez à Claude de le sauvegarder dans PRD.md.

Créez aussi un fichier de progression vide :

bash

touch progress.txt

Le PRD définit l'état final. Le fichier de progression trace ce qui est fait. Claude lit les deux à chaque itération de la boucle, trouve le prochain élément non coché, l'implémente et met à jour la progression.

Le PRD peut être dans n'importe quel format : checklist markdown, JSON, prose simple. Ce qui compte, c'est que le périmètre soit clair et que l'agent puisse en extraire des tâches individuelles.

4. Créer votre script ralph-once.sh

Avant de partir complètement AFK (Away From Keyboard), commencez par un Ralph avec humain dans la boucle. Vous lancez le script, observez ce qu'il fait, puis le relancez. Cela vous permet de comprendre comment la boucle fonctionne.

Créez ralph-once.sh :

bash

#!/bin/bash

claude --permission-mode acceptEdits "@PRD.md @progress.txt \
1. Lis le PRD et le fichier de progression. \
2. Trouve la prochaine tâche incomplète et implémente-la. \
3. Commit tes changements. \
4. Mets à jour progress.txt avec ce que tu as fait. \
NE FAIS QU'UNE SEULE TÂCHE À LA FOIS."

Éléments clés :

• --permission-mode acceptEdits : accepte automatiquement les modifications de fichiers pour que la boucle ne bloque pas

• @PRD.md : pointe Claude vers votre document de requirements

• @progress.txt : trace le travail complété entre les exécutions

• NE FAIS QU'UNE SEULE TÂCHE : force des commits petits et incrémentaux

Rendez-le exécutable :

bash

chmod +x ralph-once.sh

Lancez-le avec ./ralph-once.sh. Observez ce que Claude fait. Vérifiez le commit. Relancez-le.

5. Créer votre script afk-ralph.sh

Une fois à l'aise avec le Ralph humain-dans-la-boucle, encapsulez-le dans une boucle :

bash

#!/bin/bash
set -e

if [ -z "$1" ]; then
  echo "Usage: $0 <iterations>"
  exit 1
fi

for ((i=1; i<=$1; i++)); do
  result=$(claude --permission-mode acceptEdits -p "@PRD.md @progress.txt \
  1. Trouve la tâche de plus haute priorité et implémente-la. \
  2. Lance tes tests et vérifications de types. \
  3. Mets à jour le PRD avec ce qui a été fait. \
  4. Ajoute ta progression à progress.txt. \
  5. Commit tes changements. \
  NE TRAVAILLE QUE SUR UNE SEULE TÂCHE. \
  Si le PRD est complet, affiche <promise>COMPLETE</promise>.")

  echo "$result"

  if [[ "$result" == *"<promise>COMPLETE</promise>"* ]]; then
    echo "PRD terminé après $i itérations."
    exit 0
  fi
done

Le flag -p lance Claude en mode print : non-interactif, sortie vers stdout. Cela nous permet de capturer le résultat et vérifier le sigil de complétion.

Lancez-le dans un sandbox Docker :

bash

docker sandbox run claude ./afk-ralph.sh 20

Allez vous faire un café. Revenez devant des commits.

Éléments clés :

• set -e : quitte en cas d'erreur

• $1 (itérations) : limite la boucle pour éviter des coûts incontrôlés

• -p : mode print, sortie non-interactive

• <promise>COMPLETE</promise> : sigil de complétion que Claude affiche quand c'est terminé

6. Personnalisez-le

Ralph n'est qu'une boucle. Cette simplicité le rend infiniment personnalisable.

Vous pouvez changer la source des tâches. Au lieu d'un PRD local, tirez les tâches depuis GitHub Issues, Linear ou d'autres outils. L'agent choisit toujours sur quoi travailler — vous changez juste où vit la liste.

Vous pouvez changer la sortie. Au lieu de commiter sur main, chaque itération pourrait créer une branche et ouvrir une PR. Utile pour trier un backlog d'issues.

Vous pouvez exécuter des types de boucles complètement différents :

• Couverture de tests : trouve les lignes non couvertes, écrit des tests jusqu'à atteindre la cible

• Linting : corrige les erreurs de lint une par une

• Duplication : se branche sur jscpd, refactorise les clones en utilitaires partagés

• Entropie : scanne les code smells, les nettoie

Toute tâche qui correspond à "regarde le repo, améliore quelque chose, commit" fonctionne avec Ralph.

Pour aller plus loin

Pour des conseils plus approfondis sur les boucles de feedback, le dimensionnement des tâches, la priorisation et plus encore, lisez les 11 conseils de Matt Pocock pour coder avec Ralph (en anglais).
Ou mes conseils de vibe coding (en français).