sxivansx/loop-engineering

Ingénierie en Boucle

Mettez en place une boucle : un système autonome qui invite l'agent sans que vous ayez à le faire. Vous définissez l'objectif et la condition d'arrêt une fois ; la boucle trouve du travail, le fait, le vérifie, note ce qui s'est passé, et recommence jusqu'à ce que l'objectif soit atteint. Ce skill met en place cette boucle dans votre projet existant : il lit comment vous testez déjà, construisez et suivez le travail, puis adapte la boucle à vos conventions au lieu d'en imposer de génériques.

Une boucle est construite à partir de six primitives. Ne configurez que celles dont l'objectif a besoin.

Primitive	Rôle dans la boucle	Mécanisme Claude Code
Déclencheur	démarre chaque cycle, selon un horaire ou un événement	/goal (travailler sur plusieurs tours jusqu'à ce qu'une condition soit remplie), /loop, tâches planifiées, hooks, GitHub Actions
État	la mémoire de la boucle entre les cycles, sur disque	un fichier markdown (LOOP.md) ou un suivi de tickets via MCP
Découverte	trouve sur quoi travailler ce cycle	une étape de tri qui lit CI, tickets, diffs, une file d'attente
Faiseur	effectue une unité de travail	un sous-agent dans .claude/agents/
Vérificateur	vérifie le faiseur, indépendamment	un sous-agent différent dans .claude/agents/
Condition d'arrêt	la règle qui termine la boucle	une vérification vérifiable que le vérificateur exécute

Pour toute boucle qui tourne sans surveillance, ajoutez un moniteur : un agent de supervision qui observe la boucle dans son ensemble et l'arrête en cas de dérive (éloignement de l'objectif), de bouclage (aucun progrès net), ou de dépassement de limite (trop de cycles, trop long). Le faiseur et le vérificateur maintiennent chaque élément correct ; le moniteur maintient la boucle entière dirigée vers l'objectif, afin qu'elle ne puisse pas dériver silencieusement et tourner pendant des heures.

Deux modules complémentaires facultatifs : les worktrees (git worktree) isolent les faiseurs parallèles pour qu'ils ne modifient pas les mêmes fichiers, et les connecteurs MCP permettent à la boucle d'interagir avec de vrais outils (ouvrir une PR, mettre à jour un ticket, publier un statut). Ajoutez-les lorsque l'objectif nécessite du parallélisme ou des effets externes.

Procédure de configuration

Cette opération s'exécute dans un projet existant. Suivez ces étapes lorsqu'elles sont invoquées. Confirmez avec l'utilisateur avant toute action ayant des effets secondaires : tâches planifiées, pushs, écritures de tickets, déploiements.

1. Lisez d'abord le projet. Avant de structurer quoi que ce soit, apprenez le dépôt : comment il exécute les tests, la construction et le lint (vérifiez package.json, Makefile, la configuration CI, CLAUDE.md) ; quelles conventions et quels skills existants ou .claude/agents/ il possède déjà ; et d'où vient le travail (CI, un gestionnaire de tickets, un backlog, une file d'attente). La boucle doit s'adapter à ce projet. Réutilisez ses vraies commandes et conventions, n'en inventez pas de nouvelles.

2. Fixez l'objectif et la condition d'arrêt. Demandez à l'utilisateur l'unique objectif de la boucle et la condition vérifiable qui signifie terminé (tests exit 0, la file est vide, zéro échec de vérification). Une boucle sans condition d'arrêt est la seule chose que vous ne devez jamais livrer. Si l'utilisateur ne peut pas en nommer une, définissez une valeur de repli bornée (arrêt après N cycles) et dites-le clairement. Dans Claude Code, /goal <condition> rend cela exécutable : Claude continue de travailler sur plusieurs tours jusqu'à ce que la condition soit remplie, et /goal clear termine la boucle plus tôt.

3. Écrivez le fichier d'état. Copiez ${CLAUDE_SKILL_DIR}/templates/LOOP.md à la racine du dépôt et remplissez l'objectif, la condition d'arrêt, la cadence et la porte humaine. Il comporte trois sections vivantes que la boucle maintient : ## Ouvert (trouvé, pas encore fait), ## Fait (avec la preuve qui l'a vérifié), ## Bloqué (nécessite un humain), ainsi qu'une section ## Règles qui est l'ensemble d'instructions permanentes que chaque agent de la boucle suit. La boucle lit ce fichier en premier à chaque cycle et l'écrit en dernier.

4. Créez le sous-agent faiseur. Copiez ${CLAUDE_SKILL_DIR}/templates/loop-maker.md dans .claude/agents/loop-maker.md et pointez-le vers les conventions et la commande de test que vous avez trouvées à l'étape 1. Il effectue exactement un élément de ## Ouvert, suit les skills et conventions existants du projet, et ne marque jamais son propre travail comme terminé. Si un fichier de ce nom existe déjà, mettez-le à jour plutôt que de l'écraser aveuglément.

5. Créez le sous-agent vérificateur. Copiez ${CLAUDE_SKILL_DIR}/templates/loop-checker.md dans .claude/agents/loop-checker.md. C'est un agent différent du faiseur, il exécute la vérification réelle du projet (la vraie commande de test, construction ou lint de l'étape 1, pas une description de celle-ci), et c'est le seul agent autorisé à déplacer un élément vers ## Fait.

6. Créez le sous-agent moniteur (recommandé pour toute boucle non surveillée). Copiez ${CLAUDE_SKILL_DIR}/templates/loop-monitor.md dans .claude/agents/loop-monitor.md, et exécutez-le tous les quelques cycles ou sur une minuterie plus lente que la boucle. Il surveille la boucle dans son ensemble plutôt que n'importe quel élément individuel : il vérifie si la boucle converge toujours vers l'objectif, et il arrête la boucle et remonte à un humain en cas de dérive (travail qui ne sert pas l'objectif), de bouclage (aucun progrès net, éléments rebondissant entre Ouvert et Bloqué), ou de dépassement de limite. C'est ce qui empêche une boucle de dériver silencieusement et de tourner pendant des heures.

7. Définissez la cadence de révision de code et d'audit de sécurité (demandez à l'utilisateur). Demandez à quelle fréquence la boucle doit exécuter chacun, et enregistrez les deux dans LOOP.md. Proposez des options claires et incluez toujours jamais :

   • Révision de code (/code-review) : à chaque modification, avant chaque PR ou fusion, tous les N cycles, hebdomadaire, ou jamais.
   • Audit de sécurité (/security-review) : à chaque modification, avant chaque PR ou fusion, hebdomadaire, mensuel, ou jamais.

   À la cadence choisie, la boucle exécute cette passe intégrée et dépose ce qu'elle trouve dans ## Ouvert comme de nouveaux éléments de travail, de sorte que le faiseur les corrige et le vérificateur vérifie la correction. Si l'utilisateur choisit jamais, ignorez complètement cette passe et enregistrez jamais dans LOOP.md pour que la boucle ne la réintroduise pas.

8. Définissez la découverte. Écrivez l'étape de tri qui remplit ## Ouvert à chaque cycle à partir de là où vit réellement le travail de ce projet (statut CI, tickets ouverts, commits récents, une file de travail), et comment elle transforme les résultats en éléments discrets et individuellement vérifiables. Rendez-la déterministe autant que possible.

9. Choisissez l'isolation (facultatif). Si plus d'un faiseur s'exécute par cycle, donnez à chacun son propre git worktree et sa propre branche pour qu'ils n'écrivent jamais le même fichier. Un worktree par élément.

10. Câblez les connecteurs (facultatif). Si la boucle doit ouvrir des PR, mettre à jour des tickets ou publier un statut, connectez le serveur MCP correspondant. Sinon, la sortie de la boucle reste locale et un humain la relaie.

11. Définissez le déclencheur. Choisissez le mécanisme le plus léger qui correspond à la cadence :

    • exécuter jusqu'à ce que l'objectif soit atteint, dans cette session → /goal <condition d'arrêt> (Claude travaille sur plusieurs tours jusqu'à ce que la condition soit vraie ; /goal clear termine la boucle plus tôt)
    • répéter selon une cadence, à la demande → /loop
    • périodique et non surveillé → une tâche planifiée (ou cron / une GitHub Action pour les boucles côté CI)
    • réagir à un événement (push, PR, changement de fichier) → un hook ou une GitHub Action

    Confirmez avec l'utilisateur avant de créer une tâche planifiée.

12. Testez à blanc, vérifiez, puis activez. Exécutez un cycle manuellement. Lisez tout ce qu'il a produit. Confirmez que le vérificateur bloque réellement les mauvaises sorties et que l'état a été écrit. Ensuite seulement, activez le déclencheur.

Garde-fous (non-négociables)

• Le vérificateur n'est jamais le faiseur. L'agent qui a écrit le code n'a pas le droit de le déclarer correct.
• La condition d'arrêt est vérifiable, pas basée sur le ressenti. « Cela semble fait » n'est pas une condition d'arrêt. Une commande qui se termine avec exit 0 en est une.
• L'état est écrit à chaque cycle. Si la boucle oublie ce qu'elle a essayé, elle se répète. Le modèle oublie ; le fichier pas.
• Une porte humaine reste sur tout ce qui est irréversible. Livrer, déployer, supprimer, dépenser de l'argent. La boucle rédige, une personne confirme. Une boucle non surveillée fait des erreurs non surveillées.
• Bloqué bat une supposition. Lorsque la boucle ne peut pas vérifier ou ne peut pas continuer, elle écrit dans ## Bloqué et arrête cet élément. Elle ne livre pas une supposition.
• Une longue boucle est surveillée et bornée. Toute boucle non surveillée s'exécute avec un moniteur et une limite. Si elle s'éloigne de l'objectif ou dépasse la limite, le moniteur l'arrête et remonte l'information. Une boucle ne doit jamais tourner indéfiniment dans la mauvaise direction.

À quoi ressemble la boucle une fois configurée

votre-projet/
├── LOOP.md                   # objectif, condition d'arrêt, limites, règles, Ouvert/Fait/Bloqué
├── .claude/
│   └── agents/
│       ├── loop-maker.md      # effectue une unité de travail
│       ├── loop-checker.md    # la vérifie, indépendamment
│       └── loop-monitor.md    # surveille toute la boucle pour dérive + emballement
└── (déclencheur : /goal, /loop, une tâche planifiée ou une GitHub Action)

Anti-patrons : ne livrez pas ces choses

• Une boucle sans condition d'arrêt (tourne indéfiniment, brûle des jetons).
• Un agent qui écrit et note son propre travail.
• Une boucle sans fichier d'état (re-dérive tout, répète le travail, oublie ce qui a échoué).
• Une boucle non surveillée sans moniteur ni limites (dévié de l'objectif et tourne pendant des heures avant que quiconque ne le remarque).
• Livraison non surveillée sans porte humaine sur les actions irréversibles.
• Une boucle qui porte de nombreux travaux non liés. Une boucle, un objectif, une condition d'arrêt. Divisez le reste en leurs propres boucles.

Fichiers dans ce skill

• templates/LOOP.md : le fichier d'état à copier dans le dépôt cible.
• templates/loop-maker.md : la définition du sous-agent faiseur.
• templates/loop-checker.md : la définition du sous-agent vérificateur.
• templates/loop-monitor.md : la définition du sous-agent moniteur (garde de dérive et d'emballement).
• examples/keep-ci-green.md : une boucle complète travaillée, de l'objectif au déclencheur.