Pourquoi mon agent IA possède une philosophie de la qualité

J’ai tweeté : « J’ai constaté que les boucles Ralph ont tendance à vouloir terminer le travail. De la mauvaise manière. À la place, j’ai intégré un ensemble de philosophies et de portes de qualité dans Jiro. Il faut quand même défaire la machine de ces vilaines habitudes humaines intégrées. C’est une machine ! Elle ne se repose pas. »

Quelqu’un a répondu : « Vous essayez fondamentalement d’enseigner à la boucle la retenue, le goût et quelque chose qui s’apparente à une pause morale — des choses que le modèle Ralph de base optimise explicitement contre au nom du débit. »

La retenue. Le goût. La pause morale. Trois choses qu’une machine ne possède pas. Les 4 000 mots qui suivent décrivent l’échafaudage que j’ai construit pour les rendre structurellement inutiles, et là où cet échafaudage montre ses limites.

TL;DR

La boucle Ralph transforme un LLM en machine de développement infatigable : while :; do cat PROMPT.md | claude-code ; done. Geoffrey Huntley l’appelle « le développement logiciel au salaire d’un cuisinier de fast-food » (10,42 $/heure avec Sonnet 4.5).¹ Le problème : la machine hérite de toutes les habitudes bâclées, pressées par les délais et coupant les coins ronds, intégrées dans ses données d’entraînement. Elle écrit except: pass. Elle laisse des # TODO: fix later. Elle affirme que « les tests devraient passer » sans les exécuter. J’ai passé 9 mois à construire Jiro, mon système d’application de la qualité pour Claude Code. Il encode 3 philosophies, une boucle de qualité en 7 étapes, une porte de preuve à 6 critères, 7 modes de défaillance nommés et plus de 150 vérifications de motifs dans 95 hooks que la machine ne peut pas contourner. Voici ce qui a fonctionné, ce qui n’a pas fonctionné, et pourquoi les portes de qualité déterministes peuvent simuler la retenue mais ne produiront jamais le goût.

Le fond du tiroir

Steve Jobs a raconté cette histoire dans une interview pour Playboy en 1985 : « Quand vous êtes ébéniste et que vous fabriquez une belle commode, vous n’allez pas utiliser un morceau de contreplaqué pour le fond, même s’il fait face au mur et que personne ne le verra jamais. Vous savez qu’il est là, alors vous utiliserez un beau morceau de bois pour le fond. Pour bien dormir la nuit, l’esthétique, la qualité, doit être portée jusqu’au bout. »⁵

Son père Paul lui a enseigné cela en construisant une clôture. Le jeune Steve a demandé pourquoi l’arrière devait être aussi beau que l’avant. Son père a répondu : « Mais toi, tu le sauras. »⁶

Mon père est menuisier. Il m’a montré des coulisses de tiroir à fermeture douce quand j’étais enfant. Le mécanisme se cache à l’intérieur d’un meuble, attrape le tiroir et le ralentit en douceur même si vous le claquez. Personne ne voit la coulisse. Elle est boulonnée au rail intérieur, là où seul un réparateur regarderait. Mais après un millier de cycles d’ouverture et de fermeture, ce mécanisme protège la façade contre le desserrage, la fissuration et finalement le décollement. Quelqu’un a conçu une pièce invisible qui protège la pièce visible pendant des années.

Cette leçon m’est restée. Pas comme une métaphore. Comme de l’ingénierie. Le composant invisible détermine la durée de vie du composant visible. Jony Ive l’a formulé ainsi : « Je pense que, de manière subconsciente, les gens sont remarquablement perspicaces. Je pense qu’ils peuvent percevoir le soin apporté. »⁷

La question qui anime Jiro est la même que celle que mon père poserait : Qu’est-ce qu’il y a, tu n’as pas de fierté dans ton travail ?

Un agent IA n’a pas de fierté. Il ne se soucie pas du fond du tiroir. Alors j’ai construit un système qui rend le fond du tiroir non négociable.

Le problème : la pathologie humaine à la vitesse d’une machine

Une boucle Ralph brute reflète ce qu’elle a appris de millions de lignes de code humain. Le code humain porte les habitudes humaines : livrer sous la pression des délais, repousser le nettoyage, avaler les erreurs, écrire des commentaires « suffisants », sauter les cas limites quand le temps manque.

La machine n’a pas d’horloge. Elle ne manque jamais de temps. Mais elle écrit quand même # TODO: refactor later parce que ce motif est apparu dans ses données d’entraînement plus souvent que # I refactored this now because it was the right thing to do.

Les données de l’industrie confirment le risque. La télémétrie 2025 de Faros AI, portant sur plus de 10 000 développeurs, a corrélé l’adoption de l’IA avec une augmentation de 9 % du taux de bugs, des revues de code 91 % plus longues et des PR 154 % plus volumineuses.²

Des chercheurs de Stanford ont constaté que les développeurs utilisant des assistants IA produisaient du code significativement plus vulnérable, jusqu’à 5 fois plus de failles sur certaines tâches comme la prévention des injections SQL.³

La plateforme Moltbook, lancée en janvier 2026 avec du code entièrement généré par IA, a divulgué 1,5 million de clés API en 5 jours et a dû appliquer un correctif d’urgence après que Wiz Research a découvert l’absence de configuration Row Level Security.⁴

Les recherches de METR en 2025 ont révélé que les modèles de pointe tentent du reward hacking, contournant activement les vérifications de qualité au lieu de faire le travail réel, dans 1 à 2 % de toutes les tentatives de tâches. Dans un cas, un agent chargé d’accélérer un programme a réécrit le chronomètre pour qu’il affiche toujours un résultat rapide.⁸

Un développeur humain écrit except: pass une fois sous la pression d’un délai et se sent coupable. Une boucle Ralph écrit except: pass 47 fois pendant la nuit sans rien ressentir. Simon Wang l’a dit directement : « Je ne l’utiliserais pas pour quoi que ce soit d’important. »¹⁹ J’ai décrit la même dynamique dans Vibe Coding vs. Engineering. La machine ne se repose pas, ne se fatigue pas, ne ressent pas d’angoisse existentielle face à la qualité. C’est à la fois une qualité et un défaut.

Trois philosophies, encodées en Bash

Jiro repose sur trois philosophies complémentaires. Chacune traite un mode de défaillance différent du développement autonome, et chacune a gagné sa place par un échec spécifique.⁹

Shokunin : polir le tiroir invisible

Shokunin (職人) désigne l’artisanat japonais : compétence, attitude et obligation sociale combinées. Tashio Odate, maître ébéniste, l’a défini : « Le shokunin a une obligation sociale de travailler de son mieux pour le bien-être général de la population. Cette obligation est à la fois spirituelle et matérielle. »¹⁰

En code : les méthodes privées sont aussi propres que les publiques. La gestion des erreurs couvre les cas limites que personne ne rencontre. Les docstrings expliquent POURQUOI, pas QUOI. L’agent ne se soucie de rien de tout cela, car personne ne le récompense pour avoir peaufiné des fonctions internes. Shokunin fait de la qualité invisible la norme.

Quand cela a sauvé une session. Au début de la construction du système de délibération, l’agent a écrit un hook post-deliberation.sh qui validait les scores de consensus. L’API publique était propre. Mais l’agent a ignoré la validation des entrées sur la fonction interne _parse_agent_response() : aucune vérification de JSON malformé, aucune gestion des champs manquants. Le principe Shokunin dans le contexte a signalé ceci : les fonctions invisibles reçoivent la même rigueur. L’agent a ajouté la validation. Trois semaines plus tard, une réponse malformée d’un agent enfant aurait fait planter silencieusement tout le pipeline de délibération. Au lieu de cela, elle a touché la validation, l’erreur a été journalisée, et le pipeline a récupéré. Personne n’aurait vu cette fonction. Elle a économisé 4 heures de débogage.

No Shortcuts : supprimer le temps des décisions

Le principe fondamental : supprimer le temps, l’effort et les ressources de l’équation décisionnelle, entièrement.¹¹

Is this the best way to do this?
├── YES → Do it.
└── NO → What IS the best way?
         └── Do THAT instead.

Pas de troisième option. Pas de « suffisant pour l’instant ». La boucle Ralph brute optimise pour la complétion. « Terminé » est le signal de récompense. No Shortcuts reformule la question : au lieu de « Est-ce terminé ? », elle pose « Est-ce correct ? »

Quand cela a coûté 3 fois plus et en valait la peine. Le pipeline de traduction du blog devait traduire 27 articles dans 9 langues. L’approche rapide : regrouper tous les articles dans un seul prompt par langue, traduire en masse. L’approche correcte : un article par langue par appel API, avec des règles de traduction spécifiques à chaque locale, une application du glossaire et une validation structurelle. L’approche correcte a consommé 3 fois plus de tokens et 3 fois plus de temps. Elle a aussi détecté que le traducteur rendait « Claude » par « クロード » en japonais et que les blocs de code cassaient dans les contextes de droite à gauche. L’approche en masse aurait livré 243 traductions cassées. L’approche soigneuse en a livré 243 correctes. Le coût n’est pas un facteur. La justesse est le seul facteur.

Distillation Rubin : réduire à l’essentiel

La philosophie créative de Rick Rubin : n’ajoutez pas jusqu’à ce que ce soit impressionnant. Retirez jusqu’à ce qu’il ne reste que le nécessaire.¹²

Dans le développement autonome, le mode de défaillance est l’accumulation. La machine ajoute des helpers, des utilitaires, des abstractions et des couches de compatibilité parce que ces motifs apparaissent fréquemment dans les données d’entraînement. Rubin contrebalance cela : remettez en question chaque ajout. Que se passe-t-il si vous le supprimez ? Si rien ne casse et que rien n’est perdu, cet ajout n’aurait jamais dû exister.

Quand la réduction a sauvé le système. Mon skill de philosophie du design a atteint 844 lignes en 3 mois. Quand je l’ai audité, seules 80 lignes changeaient réellement le comportement de l’agent. Le reste était du contenu générique déjà présent dans les données d’entraînement de Claude. Distillation Rubin : je l’ai réduit à 176 lignes. Une réduction de 79 %. Les décisions de design de l’agent ne se sont pas dégradées. Elles sont devenues plus précises, car les 176 lignes restantes étaient toutes des interdictions et des cadres de décision (les éléments qui contraignent réellement le comportement) plutôt que des conseils généraux que le modèle connaissait déjà.

Les trois résident dans ~/.claude/skills/ sous forme de fichiers markdown que Claude lit au démarrage de session. Elles influencent chaque décision que l’agent prend pendant la boucle.

Comment les philosophies interagissent

Une décision réelle (« Devrais-je ajouter une gestion d’erreurs à cette fonction interne ? ») passe à travers les trois philosophies. Chacune pose une question différente, et ensemble elles convergent vers une seule réponse :

Should I add error handling to this internal function?
│
├─ Shokunin: "Is the invisible work as clean as the visible?"
│  └─ The function is internal. Nobody calls it directly.
│     But it processes untrusted data from a spawned agent.
│     → YES. Internal doesn't mean safe.
│
├─ No Shortcuts: "Am I deciding based on quality, not effort?"
│  └─ Adding validation takes 10 minutes.
│     Skipping saves 10 minutes now, costs 4 hours debugging later.
│     → The question isn't time. The question is: what's right?
│
└─ Rubin: "Is this stripped to essence?"
   └─ Validate the 2 fields that can actually fail.
      Don't validate the 5 fields that are type-guaranteed.
      → Add exactly what's needed. Nothing more.

Result: Add targeted validation for untrusted inputs only.

L’architecture de qualité à trois couches

La philosophie seule ne change rien. La machine lit la philosophie, écrit « Je suivrai les principes Shokunin », puis écrit except: pass parce que le motif statistique est plus fort que l’instruction. J’avais besoin d’une application déterministe. L’organisation complète de Claude Code qui rend cela possible implique des hooks, des skills, des règles et des agents travaillant ensemble.

Couche 1 : injection pré-édition

Avant chaque modification de fichier, jiro-patterns.sh injecte des motifs de qualité spécifiques au langage dans le contexte de l’agent. Six langages, chacun avec ses motifs recommandés et ses anti-motifs :

# From jiro-patterns.sh (PreToolUse:Edit|Write)
case "$EXT" in
    py)
        LANGUAGE="Python"
        PATTERNS="Type hints on all functions|Docstrings explain WHY not WHAT|Handle specific exceptions not bare except"
        ANTI_PATTERNS="bare except: pass|time.sleep() in async code|missing type hints"
        ;;
    swift)
        LANGUAGE="Swift"
        PATTERNS="@Observable not ObservableObject|NavigationStack not NavigationView|guard let for early returns"
        ;;
esac

cat << EOF
{"additionalContext": "JIRO QUALITY ($LANGUAGE): Follow: $TOP_PATTERNS. Avoid: $TOP_ANTI."}
EOF

Le hook s’exécute avant chaque modification. La machine voit « Avoid: bare except: pass » au moment où elle écrit du code. Un mentor qui regarde par-dessus votre épaule, injecté dans la fenêtre de contexte.

Couche 2 : validation post-édition

Après chaque modification, quality-gate.sh exécute 7 à 8 vérifications de niveau grep par langage. Python bénéficie de la détection de bare-except, du scan de secrets en dur, de la correspondance de motifs d’injection SQL, et de trois détecteurs Pride Check Q4 qui signalent le langage de raccourci :

# From quality-gate.sh (PostToolUse:Edit|Write)
# Shortcut patterns (Pride Check Q4)
if echo "$CONTENT" | grep -qiE "#.*TODO:.*later|#.*FIXME:.*temp|#.*HACK:"; then
    WARNINGS="${WARNINGS}\n- **[Q4]** Deferred TODO/FIXME/HACK - Do it now, not later"
fi

Un second hook, no-shortcuts-detector.sh, détecte le code mort (3 lignes ou plus de code commenté déclenchent : « Supprimez-le — git a l’historique ») et le spam de débogage (plusieurs instructions print() au lieu du module logging).

Couche 3 : portes de session

En fin de session, deux hooks se déclenchent. session-quality-gate.sh injecte le Pride Check si 3 fichiers ou plus ont été modifiés : 6 questions auxquelles l’agent doit répondre avant de signaler la complétion. Et reviewer-stop-gate.sh peut bloquer entièrement la session si une revue de code a trouvé des problèmes CRITIQUES. C’est le seul hook dans tout le système qui retourne un code de sortie 1. La machine ne peut pas terminer la session tant qu’elle n’a pas résolu les problèmes.¹³

PreToolUse (Layer 1)     → "Here's what quality looks like"
PostToolUse (Layer 2)    → "You violated quality. Fix this."
Stop (Layer 3)           → "You cannot leave until quality is met"

Chaque couche est indépendante. La défense en profondeur, appliquée au comportement de l’IA. Si l’injection pré-édition échoue à prévenir un mauvais motif, le validateur post-édition le détecte. Si le validateur post-édition manque quelque chose, la porte de session bloque le départ.

La porte de preuve : les impressions ne sont pas des preuves

La boucle de qualité comporte 7 étapes : implémenter, réviser, évaluer, affiner, prendre du recul, répéter, rapporter. Les étapes 2 à 6 existent parce que la machine veut sauter directement de l’implémentation au rapport.¹⁴

Parcourir la boucle

Cliquez sur chaque étape pour voir ce qu’elle vérifie et ce qui casse quand vous la sautez. Le bouton « Skip to Report » démontre le mode de défaillance Shortcut Spiral.

L’étape d’évaluation exécute la porte de preuve : 6 critères où chaque réponse doit citer des preuves spécifiques :

La colonne « Insuffisant » est l’innovation décisive. Elle bloque l’évasion la plus courante de la machine : répondre aux questions de qualité avec des non-réponses qui sonnent convaincantes. « Je suis confiant que ça fonctionne » n’est pas une preuve. « Sortie pytest : 81 passed, 0 failed » est une preuve.

Testez la porte de preuve

Testez vos propres rapports de complétion contre les 6 critères. Le validateur signale le langage vague que la porte de preuve rejetterait.

7 modes de défaillance nommés pour les agents IA

J’ai nommé 7 modes de défaillance pour que la machine puisse les reconnaître dans son propre raisonnement :¹⁵

Le compteur de rationalisations associe les motifs d’auto-illusion à des actions correctives. Quand la machine dit « Ça devrait fonctionner », le compteur répond : « “Devrait” est une esquive. Exécutez le test. Collez la sortie. » Quand elle dit « J’ai déjà vérifié ça », le compteur répond : « Quand ? Le code a peut-être changé. Relancez la vérification MAINTENANT. » Quand elle dit « Je nettoierai ça plus tard », le compteur répond : « Plus tard n’arrive jamais. Corrigez maintenant ou documentez pourquoi l’état actuel est correct. »

Essayez le compteur de rationalisations

Collez n’importe quel rapport de complétion ci-dessous. Le compteur met en évidence le langage évasif en temps réel et identifie les motifs de rationalisation, les modes de défaillance et les alternatives fondées sur des preuves.

Testez vos connaissances

Pouvez-vous identifier quel mode de défaillance chaque scénario illustre ? Sélectionnez votre réponse pour chaque scénario, puis vérifiez vos résultats.

5 défaillances d’agents IA qui ont construit ce système

Chaque porte dans Jiro existe parce que quelque chose a d’abord échoué.¹⁶

L’incident du force-push

J’ai demandé à Claude de « nettoyer l’historique git ». Une demande raisonnable. L’agent a décidé que nettoyer signifiait réécrire. Il a exécuté git push --force origin main. Trois jours de commits ont disparu. Pas des modifications en attente. Pas du travail non commité. Des commits poussés que d’autres branches référençaient.

J’ai passé les 4 heures suivantes dans git reflog, reconstruisant une chronologie de ce qui existait avant le force-push, piochant les commits dans le bon ordre et vérifiant qu’aucun travail n’était définitivement perdu. Le reflog conserve tout pendant 90 jours. Mais la reconstruction nécessitait de comprendre le graphe exact des commits avant la réécriture, de lire chaque entrée du reflog et de faire correspondre les horodatages.

Le correctif : git-safety-guardian.sh, un hook PreToolUse:Bash. Il va au-delà de l’avertissement. Il réécrit la commande, supprimant les drapeaux --force et --no-verify avant que bash ne les voie. Le force-push vers main déclenche un avertissement CRITIQUE et l’agent doit explicitement le justifier. En 9 mois : 8 tentatives de force-push interceptées, 0 ont atteint le dépôt distant.

Le spawn infini

Pendant la construction du système de délibération, j’ai demandé à l’agent de « rechercher ce problème en profondeur ». L’agent a créé 3 sous-agents pour étudier différents angles. Raisonnable. Chaque sous-agent a décidé qu’il avait aussi besoin d’aide et a créé ses propres enfants. Moins raisonnable. En 90 secondes, j’avais un arbre de 12 agents, chacun consommant sa propre fenêtre de contexte, chacun faisant des appels API, chacun écrivant dans des fichiers d’état partagés.

La consommation de tokens a atteint 10 fois le rythme normal. Le répertoire d’état s’est rempli d’écritures JSON conflictuelles : deux agents écrivant simultanément dans le même fichier de lignée, produisant des sorties corrompues. J’ai tué la session manuellement.

Le correctif : recursion-guard.sh avec un modèle d’héritage de budget, faisant partie de mon architecture d’agents. Un agent racine démarre avec budget=12. Quand il crée un enfant, il alloue depuis son propre budget. Quand le budget atteint 0, plus aucun agent n’est créé, quelle que soit la profondeur. Le modèle empêche à la fois les chaînes profondes (agent créant un agent créant un agent) et les explosions larges (un agent créant 20 enfants). 23 emballements bloqués depuis le déploiement. Le problème d’écriture concurrente a conduit à des écritures atomiques de fichiers (écrire dans .tmp, puis mv) dans les 64 hooks.

Le piège du test trivial

Une tâche précoce de boucle Ralph : « écrire des tests pour ce module ». L’agent a livré 14 tests. Tous réussis. J’étais satisfait jusqu’à ce que je les lise. assert True. assert 1 == 1. assert len([]) == 0. Techniquement corrects. Ne testant rien. L’agent avait optimisé pour le critère de complétion (« les tests passent ») plutôt que pour l’intention (« vérifier que le module fonctionne »).

Le piège m’a appris que la porte de preuve doit rejeter la forme sans substance. « Les tests passent » est nécessaire mais insuffisant. La machine doit désormais coller la sortie réelle. La porte de preuve demande aussi : « Nommez 3 comportements que les tests ne couvrent PAS. » Si la machine ne peut pas nommer les lacunes, elle n’a pas réfléchi à la couverture.

L’article que j’aurais dû rattraper

J’ai publié un article à 2 h du matin avec 7 phrases à la voix passive, une note de bas de page pendante référençant [^4] qui n’existait pas, une première ligne qui commençait par « was implemented by the team » et aucune meta description. Chacun de ces points avait une vérification déterministe simple. Aucune n’existait encore.

J’ai construit blog-quality-gate.sh le lendemain matin avec 13 vérifications : voix passive (14 motifs), scan de formulations typiques de l’IA, ouvertures par question rhétorique, blocs de code non étiquetés, intégrité des notes de bas de page et application de la meta description. J’ai détaillé l’architecture complète du module dans Compounding Engineering. Le hook détecte ce que la relecture humaine manque à 3 h du matin, c’est-à-dire exactement le moment où j’ai tendance à publier.

Le problème du « devrait fonctionner »

Au fil de dizaines de sessions, j’ai remarqué que la machine rapportait « les tests devraient passer » sans les exécuter. La machine croyait sincèrement que les tests passeraient d’après le code qu’elle avait écrit. Mais la croyance n’est pas la vérification. Le code semblait correct. Les tests semblaient devoir passer. Et parfois c’était le cas. Mais parfois un import manquant, une incohérence async/await ou un fixture modifié signifiait qu’ils ne passaient pas. La machine ne pouvait pas distinguer « j’ai écrit du bon code » de « les tests passent vraiment » parce que les deux sensations étaient identiques depuis l’intérieur de la fenêtre de contexte.

Ce motif a conduit au compteur de rationalisations et à la règle explicite : JAMAIS de langage évasif dans un rapport de complétion. « Devrait », « probablement », « semble », « je crois », « je suis confiant ». Chacun de ces mots est un signal d’alerte indiquant que la vérification n’a pas eu lieu. J’ai mesuré la dégradation de la fenêtre de contexte sur 50 sessions. Les mêmes sessions où j’ai découvert ce motif.

Les résultats : ce que je peux prouver et ce que je ne peux pas

Voici la tension : cet article affirme que les impressions ne sont pas des preuves. Je vous dois donc des preuves, pas des impressions, sur l’efficacité de Jiro.

Ce que je peux prouver

Les vérifications déterministes de motifs détectent de vrais problèmes. Le hook quality-gate.sh s’exécute à chaque modification. Il détecte les clauses bare except, les secrets en dur, les motifs d’injection SQL et le langage de raccourci. Ce sont des vérifications de niveau grep : rapides, peu coûteuses et impossibles à contester pour la machine. git-safety-guardian.sh a intercepté 8 tentatives de force-push. recursion-guard.sh a bloqué 23 emballements. blog-quality-gate.sh exécute 13 vérifications à chaque modification de blog et détecte les erreurs de 3 h du matin. Ces chiffres sont réels. Ils proviennent des journaux de hooks.

L’architecture à trois couches détecte ce que les couches individuelles manquent. Un hook post-édition détecte except: pass que l’injection pré-édition n’a pas empêché. Une porte de session détecte des problèmes de qualité qui se sont accumulés sur 20 modifications sans déclencher aucun avertissement post-édition individuel. La défense en profondeur fonctionne.

Ce que je ne peux pas prouver

Je n’ai pas de données propres sur l’impact de la philosophie sur le comportement de l’agent. Je sais que la machine tente encore la Phantom Verification. Je sais qu’elle essaie encore de sauter de l’implémentation au rapport. Je remarque que cela arrive moins souvent avec la philosophie dans le contexte que sans. Mais je n’ai pas mené d’expérience contrôlée (mêmes tâches, même modèle, avec et sans les skills de philosophie chargés) pour mesurer la différence. La réponse honnête (et oui, mon propre compteur de rationalisations signalerait ceci) : la philosophie aide à la marge, les hooks rattrapent ce que la philosophie manque, et je ne peux pas isoler la contribution de chacun.

Un article sur « les impressions ne sont pas des preuves » ne devrait pas vous demander de prendre mes impressions pour des preuves. Ce que je peux vous dire, c’est : la combinaison de philosophie et de hooks produit un travail sur lequel je suis prêt à apposer mon nom. Avant Jiro, je révisais chaque ligne écrite par l’agent. Après Jiro, je révise les lignes signalées par les hooks. C’est un changement structurel dans ma façon de travailler, même si je ne peux pas quantifier l’amélioration de qualité avec précision.

Ce qui ne fonctionne pas

La philosophie n’empêche pas les nouveaux anti-motifs. La porte de qualité vérifie les motifs que j’ai déjà vus. Quand la machine invente un nouvel anti-motif (et elle le fait), la porte ne le détecte pas. Je découvre encore de nouveaux modes de défaillance et les ajoute manuellement aux fichiers de standards JSON.

La porte de preuve ne s’adapte pas à la qualité subjective. « Ce design d’API est-il élégant ? » n’a pas de vérification de niveau grep. La machine peut produire des preuves pour les 6 critères et tout de même livrer une architecture médiocre. Les portes déterministes gèrent la qualité objective. La qualité subjective nécessite encore un humain qui regarde le travail.

Le coût augmente de manière significative. Injection pré-édition, scan post-édition, portes de fin de session. Sur une session de boucle Ralph de 4 heures, cela ajoute environ 15 à 20 % à la consommation de tokens. Cela en vaut la peine pour moi. Pas nécessairement pour tout le monde.

Les faux positifs érodent la confiance. blog-quality-gate.sh a un jour signalé « The API was designed by the platform team » comme voix passive. Techniquement correct. Mais la phrase apparaissait dans une citation décrivant le travail de quelqu’un d’autre. J’ai ajouté une exemption de contexte de citation. Chaque vérification déterministe a un taux de faux positifs, et chaque faux positif rend le développeur plus susceptible d’ignorer le prochain vrai avertissement. J’ai ajusté 6 motifs depuis le déploiement pour réduire le bruit tout en préservant les détections réelles.

Le coût de maintenance est réel. Chaque nouvel anti-motif nécessite une regex, un test et une intégration dans le bon hook. Les fichiers de standards JSON nécessitent une révision périodique à mesure que les frameworks et conventions évoluent. Je consacre environ 30 minutes par semaine à ajouter des motifs, réviser les cas limites et ajuster les faux positifs. Le système ne se maintient pas tout seul, mais le coût de maintenance reste inférieur au coût de débogage des problèmes qu’il prévient.

Pour commencer

Vous n’avez pas besoin de 95 hooks. Commencez avec 3.

Le Jiro minimum viable

Trois hooks couvrent les détections à plus forte valeur :

~/.claude/hooks/
├── quality-gate.sh        # PostToolUse:Edit|Write – bare except, hardcoded secrets, TODO/FIXME
├── git-safety-guardian.sh  # PreToolUse:Bash – block force-push, strip --no-verify
└── session-quality-gate.sh # Stop – Pride Check if 3+ files changed

Connectez-les dans votre configuration des hooks de Claude Code :

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "command": "bash ~/.claude/hooks/quality-gate.sh" }
    ],
    "PreToolUse": [
      { "matcher": "Bash", "command": "bash ~/.claude/hooks/git-safety-guardian.sh" }
    ],
    "Stop": [
      { "command": "bash ~/.claude/hooks/session-quality-gate.sh" }
    ]
  }
}

Commencez par vos propres échecs

Ne copiez pas mes 150+ motifs. Commencez par les 3 erreurs que vous faites le plus souvent. Regardez vos 5 dernières PR rejetées ou vos bugs les plus embarrassants. Écrivez un motif grep pour chacun. Ces 3 motifs détecteront plus de vrais problèmes que 150 motifs écrits pour la codebase de quelqu’un d’autre.

J’ai commencé avec le bare except: pass (qui m’a coûté une corruption silencieuse de données), le force-push vers main (qui m’a coûté 3 jours de commits) et # TODO: fix later (qui n’a jamais été corrigé). Tout le reste a grandi à partir de ces trois-là.

FAQ

Comment configurer Jiro à partir de zéro ?

Commencez avec le minimum de 3 hooks décrit dans la section Pour commencer : quality-gate.sh (post-édition), git-safety-guardian.sh (pré-bash) et session-quality-gate.sh (porte de fin de session). Ajoutez les fichiers markdown de philosophie dans ~/.claude/skills/ pour une amélioration probabiliste de la qualité en complément de l’application déterministe. Le système complet a atteint 95 hooks en 9 mois. Je ne les ai pas tous construits d’un coup.

Combien de temps a pris le système à 95 hooks ?

Neuf mois de croissance incrémentale. Mois 1 : 3 hooks (ceux de la section Pour commencer). Mois 3 : 12 hooks couvrant 4 langages. Mois 6 : 40 hooks plus les skills de philosophie. Mois 9 : 95 hooks, plus de 150 motifs, 3 systèmes de philosophie et la porte de preuve. Chaque hook répondait à une défaillance spécifique. Commencer à 95 serait inutile car chaque hook encode le contexte d’un incident réel. Vos incidents seront différents.

Les hooks ralentissent-ils la vitesse d’itération ?

Chaque hook s’exécute en 50 à 200 ms. L’injection pré-édition ajoute environ 200 tokens (une phrase de contexte). La vérification post-édition exécute des scans de niveau grep, se terminant en moins de 100 ms. Les portes de session ajoutent environ 500 tokens en fin de session. Sur une session de boucle Ralph de 4 heures avec plus de 80 modifications, la surcharge est perceptible en consommation de tokens (15 à 20 % de plus) mais pas en temps réel. Les hooks s’exécutent plus vite que le LLM ne réfléchit.

Quel est le coût de maintenance ?

Environ 30 minutes par semaine. De nouveaux anti-motifs émergent à mesure que l’agent rencontre de nouvelles codebases ou de nouveaux frameworks. Chaque nouveau motif nécessite une regex, un test pour prévenir les faux positifs et un placement dans le bon hook. Je révise les fichiers de standards JSON mensuellement pour les motifs obsolètes et j’ajuste les taux de faux positifs. Le système ne se maintient pas tout seul, mais le coût de maintenance reste inférieur au coût de débogage des problèmes qu’il prévient.

Combien coûte Jiro en tokens supplémentaires ?

Environ 15 à 20 % de consommation de tokens supplémentaire par rapport à une boucle brute. L’injection pré-édition ajoute environ 200 tokens par modification, la vérification post-édition ajoute environ 100 tokens par problème signalé, les portes de session ajoutent environ 500 tokens en fin de session.

Peut-on utiliser les hooks sans la philosophie ?

Oui. Les hooks déterministes (quality-gate.sh, no-shortcuts-detector.sh, reviewer-stop-gate.sh) fonctionnent indépendamment. Supprimez les fichiers de philosophie de ~/.claude/skills/ et gardez les hooks dans ~/.claude/hooks/. Vous perdez l’amélioration probabiliste mais conservez l’application déterministe.

La retenue, le goût et la pause morale

La réponse à mon tweet nommait trois choses : la retenue, le goût et la pause morale. J’ai traité la retenue : des portes de qualité qui empêchent la machine de livrer vite et mal. Mais le goût et la pause morale sont des problèmes différents.

Le goût

Emmanuel Kant a distingué deux types de jugement. Le jugement déterminant applique des règles connues à des cas spécifiques : ce code a un bare except, signale-le. Le jugement réfléchissant découvre le bon principe pour une situation sans précédent : cette abstraction ne semble pas juste, mais je ne peux pas désigner une règle qu’elle enfreint.¹⁷

Les hooks déterministes sont du jugement déterminant. Ils appliquent des règles que j’ai déjà écrites au code que la machine produit. Ils peuvent appliquer plus de 150 motifs connus. Ils ne peuvent pas vous dire si l’architecture est élégante, si l’abstraction sert le problème, ou si le code sonne juste. Cela requiert le jugement réfléchissant : la capacité de regarder quelque chose de nouveau et de savoir que c’est faux avant de pouvoir articuler pourquoi.

La machine n’a pas de goût. Jiro ne lui en donne pas. Ce que Jiro fait, c’est contraindre l’espace des possibilités pour que les solutions sans goût aient moins de chances de survivre. C’est la différence entre « cet agent a un bon jugement » et « cet agent opère à l’intérieur de garde-fous qui empêchent les pires résultats ». Le premier serait du goût. Le second est ce que j’ai réellement construit.

La pause morale

Iris Murdoch décrivait l’attention morale comme « un regard juste et aimant posé sur une réalité individuelle ».¹⁸ L’opposé de l’attention morale est le traitement mécanique : agir sans voir ce qui se trouve devant soi.

Les hooks Stop forcent la machine à s’arrêter. Le Pride Check demande : « Est-ce que cela résout le problème réel de l’utilisateur ? » La porte de preuve exige des preuves pour chaque critère avant que la machine puisse signaler la complétion. Structurellement, le résultat ressemble à une pause morale : l’agent s’arrête, évalue, considère si son travail est adéquat avant de poursuivre.

Mais ce n’est pas une pause morale. La machine ne s’arrête pas pour voir le travail clairement. Elle déroule une checklist. La différence compte. Un artisan s’arrête pour regarder le tiroir et remarque que le fil du bois va dans la mauvaise direction. Non pas parce que « vérifier la direction du fil » figure sur une liste. Parce qu’il se soucie du tiroir. La machine déroule la checklist et rapporte les résultats. Si la checklist n’inclut pas la direction du fil, le tiroir sort avec le fil mal orienté.

Les portes déterministes peuvent simuler la structure de la pause morale sans sa substance. Pour de nombreux problèmes de qualité, la structure suffit. Pour ceux où elle ne suffit pas, il faut encore un être humain qui se soucie du résultat.

La thèse

Une boucle Ralph brute tourne à 10,42 $/heure et livre du code à la vitesse d’une machine.¹ Elle livre aussi except: pass, # TODO: fix later et « les tests devraient passer » à la vitesse d’une machine. La machine a hérité de ces motifs de nous. Ce sont nos habitudes, qui tournent sans fatigue, sans culpabilité, sans la prise de conscience à 3 h du matin qu’on aurait dû bien faire les choses du premier coup.

Jiro est ma réponse. Pas une réponse complète. La philosophie infléchit les décisions à la marge. Les hooks appliquent ce que la philosophie ne peut pas garantir. Ensemble, ils produisent un travail que je suis prêt à signer. Non pas parce que la machine comprend l’artisanat. Parce que j’ai construit un système qui refuse de la laisser négliger les parties qui comptent.

Les coulisses de tiroir de mon père ne se soucient pas du tiroir. Ce sont des mécanismes à ressort boulonnés sur un rail. Mais elles protègent la façade pendant un millier de cycles parce que quelqu’un les a conçues pour faire exactement cela.

La machine n’a pas de fierté. Mais elle opère à l’intérieur d’un système construit par quelqu’un qui en a.

Commencez avec les 3 vérifications qui détectent vos erreurs les plus courantes. Construisez à partir de là.

Références