Premiers pas avec Ralph Wiggum Partie 2 : La méthodologie en trois phases

Tu as installé Ralph, lancé une boucle, et... ça a plus ou moins fonctionné ? Peut-être qu'il s'est bloqué. Peut-être qu'il tournait en rond. Peut-être qu'il a construit quelque chose, mais pas exactement ce dont tu avais besoin.

C'est normal. Ralph sans structure, c'est comme n'importe quel agent autonome — capable mais sans direction.

Cette partie couvre la Méthodologie en Trois Phases : un workflow pratique pour transformer des idées de projet vagues en code fonctionnel pendant que tu dors.

L'idée clé : Séparer la planification de la construction

Geoffrey Huntley décrit ça comme « Un entonnoir avec 3 Phases, 2 Prompts et 1 Boucle. » Voici le détail :

• Phase 1 : Exigences — Toi + Claude en conversation, pour définir les spécifications et les critères d'acceptation
• Phase 2 : Planification — Claude analyse les spécifications (boucle en lecture seule), produit une liste TODO priorisée
• Phase 3 : Construction — Claude implémente les tâches une par une, commite, boucle jusqu'à ce que ce soit terminé

Cette séparation est cruciale. Comme le décrit The Ralph Playbook : « Le prompt PLANNING fait l'analyse des écarts et produit une liste TODO priorisée — pas d'implémentation, pas de commits. Le prompt BUILDING choisit les tâches, implémente, lance les tests, commite. »

Pourquoi ça marche : Le mode planification empêche Claude de se jeter dans le code avant de comprendre la vue d'ensemble. Le mode construction reste concentré sur une tâche à la fois au lieu de dériver vers le chaos.

Phase 1 : Les exigences (La partie humaine)

C'est la seule phase qui nécessite ta participation active. Et c'est là que la plupart des gens bâclent — ce qui explique exactement pourquoi leurs sessions Ralph produisent n'importe quoi.

Passe au moins 30 minutes à discuter des exigences avec Claude avant d'écrire le moindre code. Sérieusement. C'est dans cette conversation que tu attrapes les moments « oh attends, et si... » qui sinon feraient dérailler ta construction autonome.

Ce que contiennent les fichiers de spécifications

Crée des fichiers specs/*.md qui deviennent la source de vérité. Ne te prends pas trop la tête sur le format — concentre-toi sur la clarté :

Astuce : Si tu veux une approche structurée pour la collecte des exigences, jette un œil au PRD Creator de JeredBlu — un système de prompts conversationnels qui te guide dans la création de spécifications complètes.

specs/
├── authentication.md    # Login, JWT, sessions
├── api-design.md        # Endpoints, formats requête/réponse
├── database.md          # Schéma, relations
└── testing.md           # Exigences de couverture, stratégie de test

La conversation qui compte

Voici comment se déroule une bonne conversation sur les exigences :

Toi : "Je veux construire une API REST pour gérer des todos"

Claude : "Décomposons ça. De quelles opérations as-tu besoin ?"

Toi : "Des opérations CRUD — créer, lire, mettre à jour, supprimer des todos"

Claude : "Compris. Et pour l'authentification ? Les comptes utilisateurs ?"

Toi : "Oui, les utilisateurs ne doivent voir que leurs propres todos"

Claude : "Logique. Comment on devrait gérer..."

Cet échange fait remonter des cas limites auxquels tu n'aurais pas pensé seul. Après la conversation, Claude génère des spécifications structurées documentant tout ce qui a été discuté.

L'investissement est rentable : 30 minutes de conversation sur les exigences évitent des heures de Ralph qui tourne dans le vide sur des objectifs ambigus.

Phase 2 : La planification

C'est un mode séparé utilisant PROMPT_plan.md. Tu lances le mode planification explicitement quand tu as besoin de générer ou régénérer ton plan d'implémentation.

Le mode planification fait l'analyse des écarts entre les spécifications et le code, créant une liste TODO priorisée sans aucune implémentation ni commits.

Deux façons de lancer Ralph

Il existe deux méthodes pour exécuter les boucles Ralph, et comprendre quand utiliser chacune est essentiel :

Méthode Plugin (/ralph-loop) — Exécute les itérations dans une seule fenêtre de contexte. Plus simple à configurer, adapté pour les tâches courtes (moins de 20-30 itérations).

Méthode Boucle Bash (loop.sh) — Lance une instance Claude fraîche par itération. Comme l'explique le guide original de Geoffrey Huntley, chaque itération « charge de façon déterministe les mêmes fichiers et lit l'état actuel depuis le disque. » Cela prévient l'engorgement du contexte et les hallucinations qui peuvent survenir quand on exécute beaucoup d'itérations dans un seul contexte. Voir les exemples de la communauté : snarktank/ralph.sh, frankbria/ralph_loop.sh, le gist de peteristhegreat.

Pourquoi un contexte frais est important : Le plugin exécute tout dans une seule fenêtre de contexte, qui se remplit au fil du temps. Après 30-40 itérations, Claude peut commencer à ignorer des parties de ton prompt ou prendre des décisions incohérentes. La méthode boucle bash évite ça en repartant de zéro à chaque fois — le seul état partagé est ce qui est écrit sur le disque (ton code, IMPLEMENTATION_PLAN.md et progress.txt). Pour des techniques avancées, voir Advanced Context Engineering for Coding Agents.

On te montrera comment créer loop.sh dans la section Le script de boucle Bash ci-dessous.

Comment lancer le mode planification

Pour la planification, la méthode plugin fonctionne bien puisqu'il te faut seulement ~5 itérations (l'engorgement du contexte n'est pas un problème) :

/ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"

Ou avec la boucle bash (voir Le script de boucle Bash ci-dessous) :

./loop.sh plan

Template PROMPT_plan.md

Voici le template complet pour le mode planification. Pour des exemples concrets, voir le PROMPT_plan.md de ClaytonFarr ou le prompt.md de snarktank.

# PLANNING MODE

You are in PLANNING mode. Your job is analysis, not implementation.

## Your Task
1. Read all files in specs/
2. Review the existing codebase in src/
3. Perform gap analysis between requirements and current implementation
4. Create/update IMPLEMENTATION_PLAN.md with prioritized tasks

## Task Structure
Each task in the plan should include:
- Unique ID (e.g., TASK-001, TASK-002)
- Priority level (high/medium/low)
- Clear description (what needs to be built)
- Acceptance criteria (how you'll know it's done)
- Required tests (specific test files or patterns)
- Dependencies (tasks that must complete first)

## File Organization
Organize tasks by priority:
- High Priority: Critical path items
- Medium Priority: Important but not blocking
- Low Priority: Nice-to-haves

## Critical Rules
- DO NOT write any code
- DO NOT make any commits
- DO NOT implement features
- DO NOT run tests or builds
- ONLY analyze and plan

When complete, output "PLAN COMPLETE"

Voir des exemples concrets : Parcours les fichiers de prompts de la communauté :

• snarktank/ralph — prompt.md complet avec AGENTS.md
• ClaytonFarr/ralph-playbook — Template PROMPT_plan.md
• frankbria/ralph-claude-code — Implémentation avec détection de sortie

Ce que produit la planification

Le mode planification génère :

IMPLEMENTATION_PLAN.md - Ta liste TODO vivante

Exemple de structure :

# Implementation Plan

## High Priority

### TASK-001: User Authentication
- **Status**: pending
- **Description**: Implement JWT-based auth with login/logout
- **Acceptance Criteria**:
  - User can register with email/password
  - User can login and receive JWT token
  - Protected routes require valid JWT
- **Tests**: `auth.test.ts`
- **Dependencies**: none

### TASK-002: Todo CRUD Endpoints
- **Status**: pending
- **Description**: Create POST, GET, PUT, DELETE endpoints for todos
- **Acceptance Criteria**:
  - POST /api/todos creates a todo
  - GET /api/todos returns user's todos
  - PUT /api/todos/:id updates a todo
  - DELETE /api/todos/:id deletes a todo
- **Tests**: `todos.test.ts`
- **Dependencies**: TASK-001

## Medium Priority

### TASK-003: Input Validation
- **Status**: pending
- **Description**: Add Zod validation for all endpoints
...

Important : Comme le note The Ralph Playbook, le plan est jetable. S'il devient obsolète ou imprécis, supprime-le et régénère-le en relançant le mode planification.

Phase 3 : La construction

C'est le mode boucle continue utilisant PROMPT_build.md. C'est là que Ralph brille — il implémente les tâches de façon autonome pendant que tu dors.

Qu'est-ce que la contre-pression ? Dans la méthodologie Ralph, la contre-pression désigne les mécanismes de validation automatisés — tests, vérification de types, linters, builds — qui rejettent le travail inacceptable. Au lieu de prescrire exactement comment Claude doit implémenter quelque chose, tu crées des « barrières » qui rejettent les mauvaises sorties. Les tests échoués forcent Claude à itérer jusqu'à ce que le code soit correct. C'est l'idée fondamentale derrière les boucles de codage autonome.

Le mode construction suppose que le plan existe, choisit une tâche à la fois, l'implémente avec des tests, commite, puis boucle avec un contexte frais.

Comment lancer le mode construction

Démarrage rapide avec le plugin :

/ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"

Pour les builds longue durée (recommandé) : Utilise la méthode boucle bash pour un contexte frais par itération. Après avoir configuré loop.sh (montré ci-dessous) :

./loop.sh              # Le mode par défaut est construction
./loop.sh build 100    # Avec une limite d'itérations personnalisée

Template PROMPT_build.md

Voici le template complet pour le mode construction. Pour des exemples concrets, voir le PROMPT_build.md de ClaytonFarr ou le PROMPT.md de frankbria.

# BUILDING MODE

You are in BUILDING mode. Your job is implementation with quality gates.

## Your Task Loop
For each iteration:
1. Read IMPLEMENTATION_PLAN.md and progress.txt
2. Pick the SINGLE highest priority task with status: pending
3. Study existing code before implementing
4. Implement the feature completely
5. Write comprehensive tests
6. Run all tests and type checks: npm test && npm run type-check
7. If tests fail, fix them immediately—DO NOT proceed
8. When all tests pass:
   - Commit with descriptive message format: "feat(area): description"
   - Update task status to completed in IMPLEMENTATION_PLAN.md
   - Append learnings to progress.txt with timestamp

## Critical Rules
- Work on ONE task at a time—no exceptions
- NEVER commit failing tests
- NEVER skip test execution
- Tests are your backpressure—respect them
- Each commit must be atomic and working
- Don't add features not in the plan
- Don't refactor unrelated code

## Backpressure Enforcement
Tests MUST pass before committing:
```bash
npm test && npm run type-check && npm run lint
```

If any check fails, fix it in the same iteration.

## Progress Tracking
After completing each task, append to progress.txt:
```
[YYYY-MM-DD HH:MM] Completed TASK-XXX: Task Title
- What was implemented
- Key decisions made
- Challenges encountered
- Learnings for next tasks
```

When all tasks show status: completed, output "ALL TASKS COMPLETE"

Voir des exemples concrets : Parcours les implémentations réelles de PROMPT_build.md :

• ClaytonFarr/ralph-playbook — Template PROMPT_build.md
• frankbria/ralph-claude-code — Implémentation avec détection de sortie intelligente
• mikeyobrien/ralph-orchestrator — Implémentation d'orchestration améliorée

Pour aller plus loin : L'article de Geoffrey Huntley Don't Waste Your Back Pressure explique pourquoi les mécanismes de validation et de rejet sont essentiels pour les boucles autonomes.

Le script de boucle Bash

Voici un script loop.sh qui supporte les modes planification et construction. Ce pattern vient du guide de JeredBlu et de l'approche originale de Geoffrey Huntley :

#!/bin/bash
# loop.sh - Fresh context per iteration

MODE=${1:-build}  # Default to build mode
MAX_ITERATIONS=${2:-50}

if [[ "$MODE" == "plan" ]]; then
  PROMPT_FILE="PROMPT_plan.md"
  COMPLETION="PLAN COMPLETE"
  MAX_ITERATIONS=${2:-5}  # Planning needs fewer iterations
else
  PROMPT_FILE="PROMPT_build.md"
  COMPLETION="ALL TASKS COMPLETE"
fi

echo "Running in $MODE mode with max $MAX_ITERATIONS iterations"
echo "Using prompt: $PROMPT_FILE"
echo "Completion signal: $COMPLETION"
echo "=========================================="

for ((i=1; i<=$MAX_ITERATIONS; i++)); do
  echo "Iteration $i / $MAX_ITERATIONS"
  echo "--------------------------------"

  # The -p flag runs Claude in one-shot mode (see Mastery Part 1: https://jocv.dev/blog/claude-code-mastery-01-getting-started#one-shot-mode-quick-questions)
  result=$(claude -p "$(cat $PROMPT_FILE)" --output-format text 2>&1) || true
  echo "$result"

  if [[ "$result" == *"$COMPLETION"* ]]; then
    echo "=========================================="
    echo "$MODE complete after $i iterations."
    exit 0
  fi

  echo "--- End of iteration $i ---"
done

echo "Reached max iterations ($MAX_ITERATIONS)"
exit 1

Rends-le exécutable :

chmod +x loop.sh

Utilisation :

./loop.sh plan      # Lancer le mode planification (5 itérations par défaut)
./loop.sh build     # Lancer le mode construction (50 itérations par défaut)
./loop.sh           # Identique à ./loop.sh build
./loop.sh build 30  # Mode construction avec max 30 itérations

Ça te donne un contexte frais par itération, ce qui évite l'engorgement de contexte qui peut survenir avec la méthode plugin sur de longues sessions.

Pour des implémentations plus sophistiquées avec gestion d'erreurs, logging et exécution parallèle, voir snarktank/ralph et mikeyobrien/ralph-orchestrator.

Le flux de la boucle de construction

Comme le documente 11 Tips for AI Coding with Ralph Wiggum :

1. Choisir la tâche la plus prioritaire dans IMPLEMENTATION_PLAN.md
2. Implémenter la fonctionnalité
3. Lancer tous les tests et vérifications de types (contre-pression !)
4. Commiter uniquement si tout passe
5. Mettre à jour progress.txt avec les apprentissages
6. Boucler avec un contexte frais → recommencer

Point clé : Chaque itération tourne dans une fenêtre de contexte fraîche (avec la méthode boucle bash). Cela empêche la dégradation du contexte et garde Claude concentré.

Le workflow complet en trois phases

Voici comment tout s'enchaîne (en utilisant le script loop.sh de la section précédente) :

# Phase 1 : Définir les exigences (conversationnel, pas en boucle)
# Discute avec Claude pour créer les fichiers specs/*.md
# Exemple : specs/authentication.md, specs/api-design.md, specs/database.md

# Phase 2 : Générer le plan (à lancer une fois, ou quand le plan doit être rafraîchi)
./loop.sh plan
# Ou avec le plugin : /ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"
# Crée IMPLEMENTATION_PLAN.md avec les tâches priorisées

# Phase 3 : Construire de façon autonome (boucle continue)
./loop.sh
# Ou avec le plugin : /ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"
# Implémente les tâches une par une, commite, boucle

# Quand le plan devient obsolète (fonctionnalités changées, nouvelles exigences) :
rm IMPLEMENTATION_PLAN.md
./loop.sh plan          # Régénérer le plan
./loop.sh               # Reprendre la construction

Structure des fichiers

Ton projet devrait avoir cette structure :

your-project/
├── specs/
│   ├── authentication.md
│   ├── api-design.md
│   ├── database.md
│   └── testing.md
├── PROMPT_plan.md          # Prompt du mode planification
├── PROMPT_build.md         # Prompt du mode construction
├── IMPLEMENTATION_PLAN.md  # Généré par la planification, mis à jour par la construction
├── progress.txt            # Journal en ajout seul des apprentissages
├── loop.sh                 # Script orchestrateur Bash
└── src/                    # Ton code
    ├── api/
    ├── auth/
    └── tests/

Différences clés entre les modes

Mode planification :

• Fichier prompt : PROMPT_plan.md
• Objectif : Analyser et planifier
• Fait des commits ? Non
• Écrit du code ? Non
• Lance des tests ? Non
• Met à jour le plan ? Oui (crée/écrase)
• Itérations typiques : 1-5
• Quand lancer ? Une fois, ou pour rafraîchir le plan

Mode construction :

• Fichier prompt : PROMPT_build.md
• Objectif : Implémenter et tester
• Fait des commits ? Oui
• Écrit du code ? Oui
• Lance des tests ? Oui
• Met à jour le plan ? Oui (marque les tâches comme terminées)
• Itérations typiques : 20-100+
• Quand lancer ? En continu jusqu'à la fin

Fichiers essentiels pour les boucles Ralph longue durée

progress.txt

Trace ce qui a été accompli à travers les itérations. Comme l'explique The Ralph Playbook : « Le fichier progress.txt est une pratique standard pour les agents longue durée. Passe-le à l'agent via le prompt, et utilise le verbe "append" pour t'assurer qu'il ne modifie pas les entrées précédentes. »

Ralph le lit pour comprendre le contexte sans ré-explorer toute la codebase.

Comment l'utiliser :

Dans ton prompt, instruis l'agent de :
"After each task, APPEND (don't overwrite) your learnings to progress.txt"

Exemple d'entrée progress.txt :

[2026-01-16 14:30] Completed TASK-001: User Authentication
- Implemented JWT signing/verification using jsonwebtoken
- Added httpOnly cookie storage for tokens
- All auth tests passing (12/12)
- Learning: Cookie sameSite setting needed for cross-origin requests
- Challenge: Had to debug token expiry edge case
- Next: Tackle TASK-002 (Todo CRUD endpoints)

IMPLEMENTATION_PLAN.md

Ta liste TODO vivante que Ralph met à jour au fur et à mesure qu'il complète les tâches. Ce fichier fait le lien entre les modes Planification et Construction.

Structure :

# Implementation Plan

## High Priority

- [ ] TASK-001: User Authentication (status: pending)
  - Tests: auth.test.ts
  - Dependencies: none

## Medium Priority

- [ ] TASK-002: Todo CRUD (status: pending)
  - Tests: todos.test.ts
  - Dependencies: TASK-001

## Completed

- [x] TASK-000: Project Setup (status: completed)
  - Completed: 2026-01-15 22:00

Écrire des prompts Ralph efficaces

Éléments essentiels d'un prompt

Comme documenté dans 11 Tips for AI Coding with Ralph Wiggum, chaque prompt Ralph devrait inclure ces éléments :

Suivi de progression :

Read progress.txt to see what's been accomplished.
After completing each task, APPEND (never overwrite) your progress.

Contre-pression par les tests :

Each commit MUST pass all tests and type checks.
Run: npm test && npm run type-check && npm run lint
If anything fails, fix it before moving on.
NEVER commit broken code.

Contrôle du périmètre :

Pick the SINGLE highest priority task from IMPLEMENTATION_PLAN.md.
Work ONLY on that task—don't add features or refactor unrelated code.

Explorer d'abord :

Study the codebase first.
Don't assume something isn't implemented—verify by reading files.
Use ultrathink before making changes.

Formulations qui fonctionnent

D'après les apprentissages de la communauté via The Ralph Wiggum Playbook et 11 Tips, ces formulations améliorent le comportement de Claude :

• "Study the codebase first" → Réduit les suppositions sur ce qui existe
• "Don't assume not implemented" → Encourage la vérification avant l'écriture
• "Ultrathink before acting" → Favorise une planification soigneuse avant les changements (ultrathink alloue le budget de réflexion maximum pour le raisonnement complexe — voir Mastery Part 9)
• "Capture the why in commits" → Améliore la qualité de l'historique git
• "MUST pass all tests" → Impose strictement les barrières de qualité

La suite

Tu as maintenant la méthodologie professionnelle : les spécifications pour les exigences, le mode planification pour l'analyse des écarts, le mode construction pour l'exécution autonome. La structure de fichiers. Les templates de prompts.

Dans la Partie 3 : Monitoring avec Ralph TUI, on couvrira la visibilité en temps réel pour les boucles longue durée — tableaux de bord, raccourcis clavier et gestion des sessions.

Puis dans la Partie 4 : Patterns avancés et dépannage, on plongera dans l'ingénierie avancée des prompts, les pièges courants, le dépannage complet et les patterns de niveau entreprise.