Tout le monde parle des boucles. Presque personne ne parle de ce sur quoi la boucle s’exécute. 9 builders sur 10 font tourner Claude Code sur le harnais par défaut – sans règles, sans sous-agents, sans hooks, sans mémoire.
Puis ils se demandent pourquoi leur boucle produit de la daube. La vérité est simple : une boucle ne vaut que ce que vaut le harnais en dessous. Voici le plan en 14 étapes pour le harnais – d’un agent seul à un système qui s’améliore lui-même.
Suivez ma Substack pour avoir de l’alpha IA frais :
L’ingénierie de boucle – construire un système qui invite votre agent selon un calendrier – a accaparé toute l’attention ce mois-ci. Mais Addy Osmani, qui a écrit le long article sur les boucles, a pris soin de pointer ce qui se trouve en dessous :
« L’ingénierie de boucle se situe un étage au-dessus du harnais. Le harnais est l’environnement dans lequel un seul agent opère. La boucle, c’est le harnais, mais elle tourne sur un minuteur, génère des assistants et se nourrit elle-même. »
L’ingénierie du harnais, c’est concevoir cet environnement : le modèle, les outils, les permissions, le contexte, la mémoire.
C’est la couche sans glamour – et c’est elle qui détermine si tout ce qui est au-dessus fonctionne. Une super boucle sur un mauvais harnais est un moyen rapide de produire des déchets à grande échelle.
14 étapes. 3 niveaux. Les fondations sur lesquelles tout repose.
Partie 1 · Ce qu’est un harnais
01. Un harnais est l’environnement dans lequel un agent opère.
Enlevez le jargon et un harnais se résume à quatre choses : le modèle qui réfléchit, les outils qu’il peut utiliser, les permissions sur ces outils, et le contexte qu’il lit au début de chaque exécution.
C’est toute la surface. Tout le reste – sous-agents, hooks, mémoire – n’est qu’une manière de façonner l’un de ces quatre éléments.
La raison pour laquelle le harnais compte plus qu’on ne le croit : l’agent est une boucle while True qui choisit un outil, l’exécute, regarde le résultat et décide du prochain mouvement.
Le harnais définit quels outils existent, ce que l’agent est autorisé à faire et ce qu’il sait au démarrage. Même modèle, harnais différent, agent complètement différent.
02. Tout le harnais vit dans un seul dossier : .claude/
Tout ce qui façonne votre agent se trouve dans un seul répertoire à la racine de votre projet. Apprenez cette structure et vous pourrez lire le harnais de n’importe qui en un coup d’œil :
1.claude/2├─ CLAUDE.md # faits permanents — lu à chaque session3├─ settings.json # permissions, modèle, hooks4├─ .mcp.json # connexions aux outils externes5├─ rules/ # comportements par chemin6│ ├─ tests.md7│ └─ python-types.md8├─ agents/ # définitions des sous-agents (~30 lignes chacun)9│ ├─ reviewer.md10│ └─ eval-runner.md11├─ skills/ # workflows réutilisables12│ └─ pr-checklist/13│ └─ SKILL.md14└─ agent-memory/ # ce qui persiste entre les exécutions15 └─ STATE.md
Une règle qui distingue un bon harnais d’un fouillis : gardez-le assez petit pour pouvoir expliquer pourquoi chaque fichier existe. Si vous ne pouvez pas dire à quoi sert une règle, un hook ou un sous-agent, supprimez-le.
03. Harnais vs boucle vs système. Trois étages, ne les mélangez pas.
La plupart des problèmes de « mon setup d’agent est un bordel » viennent de la confusion entre les trois étages. Gardez-les distincts :
- Le harnais est l’environnement d’exécution d’un agent. Configuration statique : modèle, outils, permissions, contexte. Ce numéro.
- La boucle invite l’agent sur un minuteur, génère des assistants, se nourrit elle-même. Elle fonctionne au-dessus du harnais.
- Le système auto-améliorant est une boucle avec une mémoire qui cumule – chaque exécution rend la suivante plus précise.
La version pratique : mettez les faits permanents dans le contexte, l’application des règles dans les hooks, les procédures dans les skills, et l’isolation dans les sous-agents.
Mélanger tout ça – appliquer les règles dans CLAUDE.md, faire gonfler le contexte avec des procédures – est la cause première des agents incohérents et coûteux.
04. Le harnais par défaut. Ce que vous obtenez d’office.
Installez Claude Code, ouvrez un dossier, et vous avez déjà un harnais – juste un harnais vide. Le défaut vous donne un modèle performant, les outils intégrés (lire, écrire, bash, chercher), et des demandes d’approbation pour tout ce qui est risqué. Pas de contexte projet, pas de sous-agents personnalisés, pas de mémoire.
Pour une tâche ponctuelle, le défaut suffit. Pour tout ce que vous faites plus d’une fois, le défaut force l’agent à redécouvrir votre projet depuis zéro à chaque session, à demander la permission pour des opérations sûres, et à tout oublier quand vous fermez le terminal.
Les dix prochaines étapes consistent à combler cet écart.
05. CLAUDE.md : des faits permanents, concis.
CLAUDE.md est lu au début de chaque session. C’est la connaissance permanente de l’agent sur votre projet – conventions, architecture, le « on ne fait pas ça comme ça à cause de cet incident ».
L’erreur la plus courante : le laisser grossir en un énorme document de procédures qui alourdit chaque session.
La règle des praticiens qui l’utilisent quotidiennement : gardez le fichier mémoire principal sous ~500 tokens. Les faits permanents vont ici.
Les procédures en plusieurs étapes vont dans les skills (étape 8). Les comportements spécifiques à un chemin vont dans les fichiers rules/ limités à leur périmètre. Si une section de CLAUDE.md est devenue une procédure plutôt qu’un fait, elle a sa place ailleurs.
Lisez votre CLAUDE.md à voix haute. Chaque ligne devrait être un
fait
dont l’agent a besoin à chaque session (« on utilise pnpm, pas npm »). Si une ligne est une
procédure
(« pour ajouter une fonctionnalité, d’abord… »), déplacez-la dans un skill.
Si c’est une règle pour un dossier, déplacez-la dans rules/.
06. settings.json : permissions et modèle, définis une fois.
Le harnais par défaut demande avant chaque action risquée. C’est bien quand vous surveillez, et mal quand vous ne surveillez pas. settings.json est l’endroit où vous pré-approuvez ce qui est sûr, refusez ce qui est dangereux, et choisissez quel modèle utilisez.
1{2 "model": "claude-sonnet-4-6",3 "permissions": {4 "autoApprove": [5 "Read(*)", "Grep(*)",6 "Bash(npm test)", "Bash(git status)"7 ],8 "deny": [9 "Bash(rm -rf*)", "Bash(git push*)",10 "Edit(.env*)", "Edit(secrets/*)"11 ]12 }13}
Le test pour décider ce qui est auto-approuvé : si ça tourne mal, à quel point est-ce dur à annuler ? Peu coûteux à annuler → auto-approuver.
Coûteux à annuler (force-push, suppression de fichiers, toucher aux secrets) → toujours refuser ou demander. Le juste milieu peut être auto-approuvé si vous le loggez.
07. Sous-agents : contexte isolé pour le sale boulot.
Un sous-agent est une session Claude indépendante lancée depuis la session principale – sa propre fenêtre de contexte, sa propre liste d’outils. L’intérêt n’est pas le parallélisme pour lui-même. C’est garder le bruit hors du contexte principal.
Une tâche de recherche qui lit 40 fichiers, une passe de relecture qui nécessite un regard neuf, un test d’évaluation qui produit un mur de logs – tout ça va dans un sous-agent pour ne pas polluer le thread principal.
GIF
Le sous-agent le plus précieux dans tout harnais est celui qui vérifie le travail effectué par l’agent principal. Un modèle qui révise sa propre production est trop indulgent avec lui-même ;
Un relecteur séparé avec une fenêtre de contexte fraîche détecte ce que le rédacteur s’est laissé convaincre. C’est la séparation écrivain-vs-vérificateur qui rend chaque boucle au-dessus du harnais fiable.
08. Skills : des procédures que l’agent réutilise.
Un Skill est un fichier SKILL.md que l’agent exécute – soit quand vous l’appelez avec /skill-name, soit automatiquement quand la tâche correspond à sa description.
Contrairement à un sous-agent, il s’exécute dans la même fenêtre de contexte. Ce ne sont que des instructions réutilisables qui deviennent partie intégrante de la session.
Le déclencheur pour en créer un : vous remarquez que vous collez les mêmes instructions dans chaque nouvelle conversation. C’est un skill en devenir. Une checklist de PR, une procédure d’évaluation, un processus de release – écrit une fois, invoqué pour toujours.
Et comme les skills sont l’unité réutilisable, ce sont eux qui permettent au harnais de s’améliorer au fil du temps : chaque fois que la procédure échoue d’une nouvelle manière, vous ajoutez la leçon au skill, et la prochaine exécution en hérite.
09. Hooks : des règles déterministes que le modèle ne peut pas halluciner.
Tout ce qui précède dépend de la capacité du modèle à comprendre vos instructions. Les hooks, non.
Un hook est une commande shell qui se déclenche à un point fixe du cycle de vie de l’agent – avant qu’un outil ne s’exécute, après qu’un fichier a changé, à la fin de la session – et son code de sortie peut bloquer l’action. Les hooks sont de l’application des règles, CLAUDE.md est une suggestion.
Deux hooks méritent leur place dans presque tous les harnais :
- Un garde-fou PreToolUse qui bloque les commandes dangereuses de manière déterministe – rm -rf, lecture de .env, push sur main. Le code de sortie 2 arrête l’appel avant qu’il ne se produise. Le modèle ne peut pas contourner ça en discutant.
- Un formateur PostToolUse qui exécute votre linter ou formateur après chaque modification. L’agent n’envoie jamais de code non formaté parce que le harnais le formate automatiquement.
1"hooks": {2 "PreToolUse": [{3 "matcher": "Bash",4 "command": "./.claude/hooks/block-dangerous.sh"5 // sortir avec 2 = bloquer l'appel avant exécution6 }],7 "PostToolUse": [{8 "matcher": "Edit|Write",9 "command": "prettier --write \"$CLAUDE_FILE_PATH\""10 }]11}
Utilisez les hooks pour tout ce qui doit arriver ou ne doit jamais arriver – sécurité, formatage, journalisation d’audit.
Ne les utilisez pas pour des décisions subjectives ; c’est le rôle du modèle. Un bon harnais a un ou deux hooks bien ciblés, pas vingt.
Partie 3 · Faire en sorte que ça cumule
10. Ajoutez une boucle. Maintenant le harnais tourne sur un minuteur.
Un harnais configuré attend toujours que vous tapiez quelque chose. Une boucle le fait fonctionner tout seul. La version la plus simple est /loop dans Claude Code – une invite récurrente à une cadence donnée.
Associez-la à /goal et la boucle continue jusqu’à ce qu’une condition objective soit vraie, vérifiée par un évaluateur indépendant plutôt que par l’agent lui-même.
1> /loop 30m /goal Tous les tests passent et le lint est propre.2 Trier les nouveaux échecs, rédiger des correctifs dans les branches claude/.34▲ Claude utilise le harnais que vous avez construit :5 - rules/ pour les conventions6 - sous-agent relecteur pour vérifier chaque correctif7 - le hook PreToolUse bloque les push sur main8✓ Boucle en cours. L’évaluateur indépendant décide quand c’est « fait ».
Remarquez ce qui vient de se passer : la boucle n’a pas ajouté d’intelligence. Elle a réutilisé tout ce qui était dans le harnais – les règles, le sous-agent relecteur, le hook de sécurité. Un bon harnais rend la boucle triviale. C’est tout l’intérêt de construire les fondations d’abord.
11. Ajoutez des workflows dynamiques. Le harnais écrit sa propre orchestration.
Pour les tâches trop complexes pour une simple boucle – massivement parallèles, hautement structurées, adversariales – Claude peut écrire son propre harnais JavaScript à la volée.
C’est un workflow dynamique : agent() pour lancer, parallel() pour répartir, pipeline() pour flusher. Il compose les sous-agents définis par votre harnais en motifs comme fan-out-and-synthesize ou vérification adversariale.
Le lien avec l’ingénierie du harnais : un workflow dynamique ne vaut que ce que valent les sous-agents et les skills qu’il peut appeler.
Si votre harnais a un sous-agent relecteur affûté et un skill d’évaluation bien écrit, le workflow a de bonnes pièces à orchestrer. Si le harnais est vide, le workflow n’a rien avec quoi travailler.
Le workflow est le chef d’orchestre, votre harnais est l’orchestre.
12. Ajoutez de la mémoire. Ce que l’agent oublie, le harnais s’en souvient.
C’est l’étape qui transforme un harnais configuré en un système qui s’améliore réellement. L’agent oublie tout entre les exécutions. Le harnais n’est pas obligé de le faire.
Un fichier d’état – un fichier Markdown dans agent-memory/, ou un tableau Linear – enregistre ce qui a été tenté, ce qui a fonctionné, ce qui a échoué, quelles règles ont survécu.
Le modèle qui fait cumuler la mémoire, tiré de la façon dont les agents les plus performants l’utilisent :
- Écrivez avant de partir. Chaque exécution se termine en mettant à jour le fichier d’état – leçons apprises, faits vérifiés, suite.
- Lisez au début. Chaque exécution commence par lire le fichier d’état et les skills pertinents, pour reprendre au lieu de recommencer.
- Distillez dans les skills. Quand une leçon est générale (« Les runners Windows ont besoin de bash, pas de PowerShell »), elle passe du fichier d’état dans un skill, où elle s’applique à tous les futurs projets.
1# Mémoire du projet23## Faits vérifiés # arrêtez de supposer ces choses4- prc est en dollars, pas en cents (vérifié via SELECT MIN/MAX)5- ordre des middlewares d’auth : rate_limit -> jwt -> rbac67## Leçons apprises # distillez les générales dans des skills8- Les runners CI Windows échouent TLS 1.2 dans PowerShell — utilisez bash9- Les migrations sur des tables >1M lignes doivent être batchées par lots de 10k1011## Dernière session # reprenez, ne recommencez pas122026-06-11 · 3 correctifs mergés, 2 escaladés. Prochain : vérifier le correctif du rate-limit.
13. Bouclez la boucle. Sortie → leçon → skill → meilleure sortie.
C’est ici que les trois étages s’emboîtent en quelque chose qui s’améliore lui-même. Chaque exécution produit une sortie. Le sous-agent relecteur (étape 7) la vérifie.
Le résultat – ce qui a réussi, ce qui a échoué, ce qui a été appris – est écrit dans la mémoire (étape 12). Les leçons générales sont distillées dans les skills (étape 8).
La prochaine exécution hérite de skills plus affûtés et d’une mémoire plus riche.
Voilà toute la boucle auto-améliorante, et remarquez qu’elle est construite entièrement à partir d’éléments du harnais :
- Sous-agent évalue le travail – vérification objective, contexte frais.
- Mémoire enregistre le verdict – persiste entre les exécutions.
- Skills réutilisent les procédures.
- La boucle relance le tout – maintenant avec tout ce que la dernière exécution a appris.
Le modèle n’a jamais changé. Le harnais autour de lui est devenu plus précis. C’est ce que « auto-amélioration » signifie honnêtement – pas un modèle qui apprend, mais un harnais qui accumule.
14. Distribuez le harnais. Packaging. Partagez-le. Réutilisez-le.
Un harnais qui fonctionne sur un projet est un actif.
Regroupez les skills, les sous-agents et les règles dans un plugin et toute votre équipe installe la même configuration en une étape – mêmes conventions, mêmes hooks de sécurité, même relecteur.
Le harnais cesse d’être votre configuration personnelle et devient une infrastructure partagée.
L’ordre de construction, une dernière fois, parce que l’ordre est la leçon : obtenez d’abord une exécution manuelle fiable sur un harnais propre.
Ajoutez le contexte et les permissions. Ajoutez un sous-agent relecteur. Ajoutez de la mémoire. Ensuite et seulement ensuite, enveloppez le tout dans une boucle. Une boucle sur un bon harnais cumule. Une boucle sur un mauvais harnais ne fait que saigner plus vite.
§ Les erreurs de harnais qui empirent toutes les boucles
- Tourner sur le défaut. Pas de contexte, pas de règles, pas de mémoire – l’agent redécouvre votre projet à chaque session.
- Un CLAUDE.md boursouflé. Des procédures entassées dans le contexte permanent, alourdissant chaque exécution. Déplacez-les dans des skills.
- Application des règles dans CLAUDE.md au lieu des hooks. Le modèle peut ignorer une suggestion. Il ne peut pas ignorer un hook qui sort avec le code 2.
- Un seul agent qui écrit et évalue son propre travail. Ajoutez un sous-agent relecteur avec une fenêtre de contexte fraîche.
- Pas de mémoire. Chaque exécution repart de zéro. Le fichier d’état est ce qui permet de reprendre demain.
- Enrouler une boucle autour d’un mauvais harnais. La boucle ne fait que produire de la daube plus vite. Construisez d’abord les fondations.
- Vingt hooks. Un ou deux bien ciblés valent mieux qu’une montagne que personne ne comprend.
- Distribuer un harnais sans l’analyser. Des secrets divulgués et des permissions trop larges se propagent à tous ceux qui l’installent.
Conclusion :
La boucle a la gloire. Le harnais fait le travail.
L’ingénierie de boucle est la partie excitante – l’agent qui s’auto-invite, qui tourne pendant que vous dormez. Mais une boucle n’est qu’un harnais sur un minuteur.
Tout ce qui détermine si la sortie est bonne ou pourrie se trouve un étage plus bas, dans le modèle que vous avez choisi, les outils que vous avez autorisés, le contexte que vous avez écrit, le relecteur que vous avez ajouté, la mémoire que vous avez conservée.
Construisez bien cet étage et tout ce qui est au-dessus cumule : la boucle réutilise vos sous-agents, le workflow orchestre vos skills, la mémoire rend chaque exécution plus précise que la précédente.
L’auto-amélioration n’a jamais été une propriété du modèle. C’est une propriété du harnais que vous construisez autour de lui.
Choisissez une chose que vous ne faites pas – probablement un sous-agent relecteur, un hook de sécurité ou un fichier d’état – et ajoutez-la aujourd’hui. Gardez le harnais assez petit pour pouvoir l’expliquer. Ensuite, mettez une boucle par-dessus, et regardez les fondations faire le travail.
