invincible04/awesome-loop-engineering

Ingénierie des Boucles

Aidez l'utilisateur à se remplacer lui-même en tant que chose qui invite un agent de codage. La livraison est un petit système qui découvre du travail, le confie à un exécutant, vérifie le résultat avec un vérificateur séparé, note ce qui est fait, décide de la suite et s'exécute à nouveau jusqu'à ce qu'un objectif soit atteint, puis s'arrête pour une raison honnête.

Votre travail dans cette compétence n'est pas d'écrire la boucle pour eux en une seule fois. Il s'agit d'interviewer, de concevoir le contrat, puis d'échafauder afin qu'ils se retrouvent avec une boucle qu'ils peuvent réellement exécuter et à laquelle ils peuvent faire confiance.

Ce qu'une boucle est, et n'est pas

Une boucle n'est pas une tâche cron. Une tâche cron se répète aveuglément. Une boucle découvre du travail, le vérifie avec un vérificateur séparé, persiste l'état, décide de la suite et s'arrête pour une raison. Si la chose que vous construisez ne peut pas s'arrêter d'elle-même, c'est un bogue, pas une boucle.

Construisez les conditions d'arrêt en premier. Ce sont elles qui permettent à l'utilisateur de s'éloigner.

Étape 0 : décider si une boucle est même le bon outil

Avant de concevoir quoi que ce soit, appliquez ce test. Une boucle est rentable uniquement lorsque les deux sont vraies :

1. Il existe un critère de succès clair et vérifiable par machine (un test passe, une build est verte, un schéma valide, une grille d'évaluation retourne RÉUSSITE).
2. L'atteindre implique des essais et erreurs fastidieux que l'utilisateur ferait autrement à la main, tour après tour.

Si l'utilisateur ne peut pas indiquer comment une machine saurait que le travail est terminé, arrêtez et dites-le. Une boucle sans condition d'achèvement vérifiable ne converge pas ; elle s'agite et brûle des tokens. Aidez-les d'abord à trouver un proxy vérifiable, ou recommandez-leur de continuer à inviter manuellement. Ne construisez pas une boucle pour éviter de comprendre le travail.

Bons candidats pour une boucle : réparer une CI défaillante, trier une boîte de réception de tickets, mises à jour de dépendances avec une suite de tests solide, réglage des performances avec un benchmark, chasse aux tests instables, builds de documentation qui doivent rester verts. Mauvais candidats : conception ouverte, tout ce où « bon » est une question de goût sans proxy, tâches uniques.

Étape 1 : interroger l'utilisateur (remplir le contrat de boucle)

Posez ces questions. Commencez par la question de vérification — c'est celle qui décide si la boucle est viable. Ne posez pas les onze à la fois ; posez-les par petits lots et déduisez ce que vous pouvez en toute sécurité du dépôt.

1. Objectif. Quel est le travail récurrent que vous faites à la main ? Que devrait rendre la boucle vrai ?
2. Condition d'achèvement (demandez d'abord, demandez fermement). Comment une machine saurait-elle que c'est terminé, sans aucun humain qui regarde ? Nommez la commande ou la vérification exacte.
3. Déclencheur. Qu'est-ce qui lance une exécution : une planification (toutes les N minutes / toutes les nuits) ou un événement (push, nouveau ticket, webhook, échec CI) ?
4. Découverte / prise en charge. Comment une exécution choisit-elle sur quoi travailler ? (lire le statut CI, interroger le gestionnaire de tickets, lire un fix_plan.md, scanner les alertes)
5. Espace de travail. Où agit-elle et qu'est-ce qui est strictement interdit ? (un worktree git ou un bac à sable ; jamais force-push, toucher aux secrets, changer les dépendances, toucher à la production)
6. Contexte. Que doit lire chaque exécution pour ne pas redériver le projet à partir de zéro ? (un SKILL.md / AGENTS.md, le cahier des charges, le fichier mémoire)
7. Délégation. Quel agent fait le travail (l'exécutant), et lequel séparé le vérifie (le vérificateur) ? Ils ne doivent pas être le même appel.
8. Vérification. Quelles portes doivent passer pour que « terminé » soit vrai ? (tests unitaires, lint, types, une grille d'évaluation LLM-en-tant-que-juge retournant RÉUSSITE/ÉCHEC avec des preuves)
9. Mémoire / état. Où la progression est-elle stockée pour qu'une exécution puisse reprendre après un redémarrage ? (un fichier markdown, un gestionnaire de tickets, un state.json sur disque)
10. Budget. Les plafonds stricts : itérations max, temps d'exécution max, tokens max, et un plafond en dollars si un identifiant peut dépenser de l'argent.
11. Passation. Quand est-ce que cela escalade vers un humain plutôt que de continuer ? (ambigu, à haut risque, ou le même échec deux fois sans nouvelle preuve)

Enregistrez les réponses dans templates/loop-contract.template.md. Si l'utilisateur ne peut pas répondre à la question #2 avec une vérification concrète, retournez à l'Étape 0.

Étape 2 : rédiger le contrat de boucle

Remplissez le modèle en un vrai loop-contract.md dans le dépôt de l'utilisateur. C'est l'artefact de conception à partir duquel la boucle est construite et contre lequel elle est revue. Gardez-le court et concret. Chaque champ doit nommer une commande, un chemin ou un nombre, pas une ambiance.

Étape 3 : choisir la plus petite forme qui correspond à l'outil

Cartographiez le contrat sur l'agent de l'utilisateur. Choisissez le mécanisme le plus simple qui le satisfait ; n'utilisez pas d'orchestration multi-agents quand un /goal suffit. Voir reference/tool-mapping.md pour les détails.

• Claude Code : /goal pour la condition d'arrêt vérifiée, sous-agents dans .claude/agents/ pour la séparation exécutant/vérificateur, hooks ou tâche planifiée pour le déclencheur, claude -p ... --output-format json pour les exécutions sans tête.
• Codex : l'onglet Automations pour le déclencheur, codex exec --json pour les exécutions sans tête, codex exec resume --last pour continuer, sous-agents pour le vérificateur.
• Greenfield / à partir de zéro : une boucle bash à la Ralph, while :; do cat PROMPT.md | agent; done, avec une tâche par tour et un fix_plan.md. Meilleur quand il n'y a pas encore de codebase à casser ; associez-la à une porte et à un budget pour qu'elle puisse s'arrêter. Voir reference/ralph.md.

Étape 4 : échafauder les fichiers

Générez des artefacts concrets et exécutables (adaptez les noms à la pile de l'utilisateur) :

• L'invite de l'exécutant avec les règles non négociables intégrées (voir les lois ci-dessous).
• Le vérificateur : soit une porte shell (la commande de test/lint exacte) soit une invite de vérificateur qui retourne RÉUSSITE/ÉCHEC plus des preuves et peut ESCALADER. Commencez à partir de reference/verifier-rubric.md.
• Le fichier mémoire (fix_plan.md ou state.json) qu'une exécution lit en premier et écrit en dernier.
• L'exécuteur : la boucle while, ligne cron, Action GitHub, ou automation qui la déclenche, incluant la porte (« si la build est déjà verte, ne fais rien ») et le plafond budgétaire.

Étape 5 : durcir avant de la laisser s'exécuter

Faites parcourir à l'utilisateur reference/hardening-checklist.md avant la première exécution non surveillée. Faites toujours une exécution à blanc une fois avec un budget serré et un identifiant en bac à sable avant de passer à l'échelle.

Les quatre conditions d'arrêt honnêtes

Chaque boucle doit pouvoir s'arrêter pour exactement l'une de ces raisons, et dire laquelle :

• objectif atteint : le vérificateur séparé confirme la condition d'achèvement.
• budget épuisé : un plafond d'itération, de token, de temps ou de dollar déclenché.
• bloqué : le même échec deux fois sans nouvelle preuve (arrêtez de vous agiter).
• a besoin d'un humain : à haut risque ou ambigu, donc cela escalade. C'est un état de succès, pas un échec.

Les lois non négociables

Intégrez les règles 1 à 5 dans les instructions de chaque exécutant. Les règles 6 et 7 ne peuvent pas être intégrées dans un exécutant — elles sont la propriété de l'ingénieur, assurez-vous donc que l'utilisateur les garde.

1. L'exécutant ne note jamais son propre travail. Un vérificateur séparé décide si c'est « terminé ». Le modèle qui a écrit le code est bien trop généreux en corrigeant ses propres devoirs.
2. N'affaiblissez ni ne supprimez jamais un test, et ne réduisez jamais une vérification, pour le faire passer. Corrigez la cause. Si le test est erroné, escaladez ; ne le modifiez pas en silence.
3. Une boucle qui ne peut pas s'arrêter est un bogue. Câblez les quatre conditions d'arrêt avant la première exécution.
4. La mémoire vit sur le disque, pas dans le contexte. Lisez-la en premier à chaque tour, écrivez-la en dernier. L'agent oublie entre les exécutions ; le dépôt, non.
5. Corrigez uniquement la cause ; n'élargissez pas le périmètre. Le plus petit changement qui pourrait être correct.
6. La vérification reste la responsabilité de l'ingénieur. « Terminé » est une affirmation, pas une preuve. Le vérificateur est l'actif que l'utilisateur possède ; l'exécutant est une marchandise qui s'améliore gratuitement avec chaque version de modèle.
7. La flotte évolue en fonction du taux de revue de l'utilisateur, pas du nombre de voies de l'outil. L'humain est le goulot d'étranglement en série. Généralement, le bon nombre d'agents parallèles est un petit chiffre unique.

Ce que la boucle ne fait jamais pour vous

Dites-le clairement à l'utilisateur pour qu'il conserve le bon rôle :

• Vérification. Une boucle qui s'exécute sans surveillance est aussi une boucle qui fait des erreurs sans surveillance. Le vérificateur séparé donne un sens à « terminé » ; il ne le rend pas certain.
• Compréhension. Plus la boucle livre vite, plus la dette de compréhension croît vite. Planifiez du temps pour lire ce qu'elle a construit.
• Intention. Pourquoi ce travail compte, et ce que « bon » signifie, doit venir d'un humain. La boucle ne fait pas la différence entre l'utiliser pour aller plus vite sur un travail que vous comprenez et l'utiliser pour éviter de comprendre le travail. C'est vous qui le faites.

Construisez la boucle. Mais construisez-la comme quelqu'un qui a l'intention de rester l'ingénieur, pas seulement la personne qui appuie sur le bouton.

Lectures complémentaires (optionnel)

Si l'utilisateur veut la théorie derrière ces étapes en profondeur — l'anatomie de la boucle et le contrat en 11 parties, /goal vs /loop, la mémoire, l'économie des tokens et la taxe d'orchestration, ainsi que les risques — dirigez-le vers le manuel Awesome Loop Engineering : https://github.com/invincible04/awesome-loop-engineering (lisible en ligne sur https://invincible04.github.io/awesome-loop-engineering/).