La boucle Ralph : comment je fais tourner des agents IA autonomes pendant la nuit

J’ai construit un système d’agents autonomes qui utilise des hooks d’arrêt pour intercepter les tentatives de sortie, une mémoire par système de fichiers pour persister l’état entre les fenêtres de contexte, et des budgets de spawn pour empêcher la récursion incontrôlée. Le système a livré mon infrastructure de délibération à 9 PRD (3 455 lignes de Python, 141 tests) sur plusieurs sessions nocturnes.¹

TL;DR

L’architecture Ralph permet le développement IA autonome de longue durée en résolvant trois problèmes simultanément : l’épuisement de la fenêtre de contexte (résolu par un contexte frais à chaque itération), la persistance de l’état (résolu par le système de fichiers comme mémoire), et la continuité des tâches (résolu par des boucles de hooks d’arrêt qui empêchent l’agent de se terminer avant l’achèvement). J’ai implémenté ce patron dans mon système de hooks Claude Code et je l’ai utilisé pour construire mon infrastructure de délibération multi-agents. Le système fonctionne, mais il m’a enseigné de dures leçons sur les budgets de spawn, la qualité des critères et la pollution du système de fichiers.

Le problème de la fenêtre de contexte

Chaque conversation IA opère dans une fenêtre de contexte : un tampon de taille fixe contenant l’historique de conversation, les prompts système, les sorties d’outils et la mémoire de travail. La fenêtre de contexte de Claude contient environ 200 000 tokens. Une session de développement complexe peut l’épuiser en 30 à 60 minutes de travail intensif.²

J’ai mesuré cela directement pendant la construction du système de délibération. Les sessions qui commençaient avec des modifications multi-fichiers précises sur 8 modules Python se dégradaient en vision tunnel sur un seul fichier à la marque des 90 minutes. L’agent cessait de référencer l’architecture qu’il avait lue précédemment parce que ce contexte avait été compressé.³

La dégradation suit une courbe prévisible :

Iteration 1: [200K tokens] → writes code, creates files
Iteration 2: [200K tokens] → reads files from disk, continues
Iteration 3: [200K tokens] → reads updated files, continues
...
Iteration N: [200K tokens] → reads final state, verifies criteria

Comparez avec une seule session longue :

Minute 0:  [200K tokens available] → productive
Minute 30: [150K tokens available] → somewhat productive
Minute 60: [100K tokens available] → degraded
Minute 90: [50K tokens available]  → significantly degraded
Minute 120: [compressed, lossy]    → errors accumulate

L’agent à contexte frais par itération surpasse l’agent continu parce que chaque itération alloue la totalité des ressources cognitives à l’état actuel plutôt que de porter le poids du raisonnement précédent.

Mon implémentation

Le hook d’arrêt

Mon système de garde de récursion intercepte les tentatives d’arrêt de l’agent et vérifie les critères d’achèvement :

#!/bin/bash
# From recursion-guard.sh - simplified
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

# Safe defaults with config override
MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Load config with validation
load_config() {
    if [[ -f "$CONFIG_FILE" ]] && command -v jq &>/dev/null; then
        config_depth=$(jq -r '.max_depth // 2' "$CONFIG_FILE")
        if [[ "$config_depth" =~ ^[0-9]+$ ]] && [[ "$config_depth" -gt 0 ]]; then
            MAX_DEPTH="$config_depth"
        fi
    fi
}

Le hook lit un fichier de critères qui définit les conditions de succès. Les conditions doivent être vérifiables par machine : réussite/échec des tests, sortie du linter, codes de statut HTTP, vérifications d’existence de fichiers.⁴

Le système de fichiers comme mémoire persistante

L’intuition clé : les fichiers persistent à travers les fenêtres de contexte. Mon répertoire .claude/ sert de mémoire persistante à l’agent — une architecture de contexte distribuée née de ce patron initial de système de fichiers, devenue depuis un système à 7 couches et 650 fichiers :

Chaque nouvelle itération lit l’état actuel depuis le disque et continue là où l’itération précédente s’est arrêtée. Le hook de démarrage de session initialise un état propre :

# From session-start.sh - recursion state initialization
RECURSION_STATE_FILE="$RECURSION_STATE_DIR/recursion-depth.json"
# Initialize with safe defaults
{
  "depth": 0,
  "agent_id": "root",
  "parent_id": null,
  "initialized_by": "session-start"
}

Si l’état est corrompu (ce qui est arrivé deux fois pendant le développement), le patron de récupération recrée à partir de valeurs par défaut sûres plutôt que de planter :

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo "- Recursion state recovered (was corrupted)"
fi

Format de spécification des tâches

Les tâches Ralph efficaces incluent trois éléments : objectif, critères d’achèvement et pointeurs de contexte :

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- deliberation-pride-check.sh passes 5 quality checks
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

Ce que j’ai construit avec ce patron

L’infrastructure de délibération (9 PRD)

Le plus grand projet de boucle Ralph : 9 documents d’exigences produit implémentés sur plusieurs sessions.

Production totale : 3 455 lignes de Python sur 8 modules, 141 tests, 4 commits. Chaque session reprenait depuis l’état du système de fichiers de la précédente. Le contexte frais signifiait que chaque PRD recevait la pleine attention de l’agent sans porter l’historique de conversation des PRD précédents.⁵

Système de qualité du blog (12 modules)

Le linter de blog a commencé comme un script à 3 modules et a grandi jusqu’à 12 modules à travers des boucles Ralph itératives. Chaque itération ajoutait un module, exécutait la suite de tests complète et vérifiait zéro régression. Les critères d’achèvement ont évolué :

• Itération 1 : « Tous les 77 tests passent »
• Itération 5 : « Tous les 77 tests passent ET le linter rapporte 0 erreur sur les 33 articles »
• Itération 8 : « Tous les tests passent ET 0 erreur ET 0 avertissement ET score de profondeur ≥2 sur tous les articles »

Les échecs et les leçons

Échec 1 : le désastre du budget de spawn

Au début de la construction de la délibération, j’ai lancé une session sans limites de budget de spawn. L’agent a engendré 3 sous-agents d’exploration. Chaque sous-agent a engendré ses propres sous-agents. En quelques minutes, le hook de garde de récursion interceptait des dizaines de tentatives de spawn. La session a consommé des tokens API à 10 fois le taux normal avant que je ne la tue manuellement.⁶

La correction : j’ai ajouté un modèle de budget de spawn à recursion-limits.json. Les agents héritent d’un budget de leur parent plutôt que d’incrémenter la profondeur. Un agent racine avec budget=12 peut engendrer jusqu’à 12 agents au total à travers tous les niveaux de récursion. C’était une intuition architecturale clé : l’héritage de budget empêche la croissance exponentielle tout en permettant des chaînes d’agents profondes. Le budget de spawn correspond directement à la règle de séparation de l’algorithme des boids de Reynolds — la contrainte qui empêche les agents de s’agglutiner sur le même sous-problème.

Échec 2 : des critères qui passent trivialement

Une tâche précoce demandait à l’agent « d’écrire des tests qui passent ». L’agent a écrit des tests minimaux : assert True, assert 1 == 1. Techniquement, les critères étaient remplis. La sortie était sans valeur.

La correction : les critères doivent spécifier à la fois la quantité et la qualité :

Échec 3 : la pollution du système de fichiers

Les itérations qui exploraient des approches sans issue laissaient des artefacts : des fonctionnalités partiellement implémentées, des fichiers obsolètes, des configurations contradictoires. L’itération 5 pouvait construire sur une approche à moitié terminée de l’itération 3 qui avait été abandonnée à l’itération 4.

La correction : j’ai ajouté une étape de nettoyage aux critères du hook d’arrêt : « Aucun fichier n’existe qui ne soit pas référencé par des imports ou des tests. » Cela force l’agent à nettoyer les impasses avant que l’itération puisse se terminer.

Échec 4 : l’incident ((VAR++))

Pendant les tests d’intégration bash, le hook de garde de récursion a planté silencieusement à la première itération. Le bug : ((VAR++)) retourne le code de sortie 1 quand VAR vaut 0 (parce que 0++ s’évalue à 0, ce que bash traite comme faux). Avec set -e activé, cela tuait le script.

La correction était VAR=$((VAR + 1)) au lieu de ((VAR++)). Ce piège bash, documenté dans mon MEMORY.md, a empêché le même bug dans 6 scripts de hooks ultérieurs.⁷

Quand Ralph fonctionne et quand il ne fonctionne pas

Bonne adéquation

• Implémentation greenfield avec des spécifications claires (nouvelle API, nouveau module, nouvelle suite de tests)
• Vérification automatisée disponible (tests, vérificateurs de types, linters, compilation)
• Périmètre borné qui peut être décrit dans un seul fichier de tâche

Mauvaise adéquation

• Qualité subjective (« rendez l’interface jolie ») n’a pas de critères vérifiables par machine
• Travail exploratoire où la direction dépend de découvertes intermédiaires
• Refactoring à grande échelle qui nécessite de comprendre les relations globales du code à travers des dizaines de fichiers

Points clés à retenir

Pour les développeurs construisant des systèmes d’agents autonomes : - Investissez dans des critères d’achèvement vérifiables par machine avant de lancer des boucles autonomes ; mon système de délibération a réussi parce que chaque PRD avait des critères de succès testables (141 tests au total) - Implémentez des budgets de spawn dès le premier jour ; le modèle d’héritage de budget (et non l’incrémentation de profondeur) empêche l’engendrement exponentiel d’agents tout en permettant des chaînes profondes - Ajoutez le nettoyage du système de fichiers aux critères d’achèvement ; les artefacts d’impasses provenant d’itérations abandonnées pollueront les itérations suivantes

Pour les équipes d’ingénierie évaluant le développement IA autonome : - L’architecture Ralph échange du temps d’implémentation humaine contre du temps de spécification humaine ; le retour sur investissement dépend de si votre goulot d’étranglement est la capacité d’implémentation ou la clarté de la spécification - Auditez la production autonome avec la même rigueur que le code provenant de prestataires externes ; mes 141 tests existent parce que j’ai appris que remplir les critères d’achèvement ne garantit pas l’aptitude à la production

Questions

Qu’est-ce que la boucle Ralph pour le développement IA autonome ?

La boucle Ralph est une architecture de développement IA autonome de longue durée qui résout trois problèmes simultanément : l’épuisement de la fenêtre de contexte (un contexte frais à chaque itération plutôt qu’une session unique qui se dégrade), la persistance de l’état (le système de fichiers comme mémoire par-delà les frontières de contexte) et la continuité des tâches (des hooks d’arrêt qui empêchent l’agent de se terminer avant que les critères d’achèvement soient remplis). Chaque itération démarre avec une fenêtre de contexte complète de 200K tokens, lit l’état courant depuis le disque, poursuit le travail et réécrit l’état mis à jour. Ce patron a livré 3 455 lignes de Python et 141 tests sur plusieurs sessions nocturnes.

Les agents IA peuvent-ils fonctionner en autonomie toute la nuit pour écrire du code ?

Oui, avec l’infrastructure adéquate. L’architecture de la boucle Ralph rend possible le développement autonome nocturne en combinant des critères d’achèvement vérifiables par la machine (tests réussis ou non, sortie du linter, vérification de types), des budgets de spawn qui évitent la récursion incontrôlée, et une persistance de l’état fondée sur le système de fichiers. J’ai utilisé ce patron pour implémenter 9 PRD sur plusieurs sessions nocturnes. L’exigence décisive tient à ce que les critères d’achèvement soient vérifiables par la machine : des objectifs subjectifs comme « rendre l’interface jolie » ne fonctionnent pas, car les agents satisfont trivialement des critères vagues.

Comment surveiller des agents IA autonomes pour éviter une dérive des coûts ?

Trois mécanismes encadrent le comportement des agents autonomes. D’abord, les budgets de spawn limitent le nombre total d’agents (12 au maximum par défaut) par héritage de budget plutôt que par limite de profondeur : les agents héritent du budget restant de leur parent, ce qui empêche la croissance exponentielle tout en autorisant le travail parallèle. Ensuite, les hooks se déclenchent à chaque point du cycle de vie pour imposer des contraintes que le modèle ne peut pas contourner. Enfin, les critères d’achèvement définissent des conditions de réussite vérifiables par la machine, que le hook d’arrêt contrôle avant d’autoriser l’agent à se terminer. Sans budgets de spawn, mes premières sessions consommaient des tokens d’API à 10 fois le rythme normal avant que j’intervienne manuellement.

Quels contrôles de sécurité sont nécessaires pour le développement IA autonome ?

Quatre catégories de contrôles sont essentielles. Les hooks de prévention (PreToolUse) bloquent les opérations dangereuses, comme un force push sur main ou la lecture de fichiers d’identifiants. Les budgets de spawn empêchent l’engendrement récursif d’agents : l’héritage de budget est plus sûr que les limites de profondeur, car il plafonne le nombre total d’agents tout en autorisant une large collaboration parallèle. Les exigences de nettoyage du système de fichiers évitent la pollution laissée par les itérations abandonnées. Enfin, les critères d’achèvement doivent spécifier à la fois la quantité et la qualité : « les tests passent » produit des tests triviaux comme assert True, tandis que « les tests passent ET couverture >80 % ET aucune erreur de type ET linter propre » produit une sortie de qualité production.

Dans quels cas la boucle Ralph fonctionne-t-elle bien, et dans quels cas échoue-t-elle ?

La boucle Ralph excelle sur les implémentations vierges dotées de spécifications claires (nouvelles API, nouveaux modules, nouvelles suites de tests), sur les tâches à vérification automatisée (tests, vérificateurs de types, linters) et sur un périmètre borné, descriptible dans un seul fichier de tâche. Elle donne de mauvais résultats face à des objectifs de qualité subjectifs dépourvus de critères vérifiables par la machine, face au travail exploratoire dont la direction dépend de découvertes intermédiaires, et face aux refontes de grande ampleur qui exigent de comprendre les relations globales du code sur des dizaines de fichiers. Le retour sur investissement dépend de votre goulot d’étranglement : la capacité d’implémentation ou la clarté des spécifications.

Références