Pourquoi mon agent IA a une philosophie de qualité

J’ai tweeté : « J’ai découvert que les boucles Ralph ont tendance à vouloir boucler le travail. Dans le mauvais sens. À la place, j’ai tout un arsenal de philosophie et de garde-fous qualité dans Jiro. Il faut encore briser la machine des mauvaises habitudes humaines intégrées. C’est une machine ! Elle ne se repose pas. »

Quelqu’un a répondu : « Tu essaies en gros d’enseigner à la boucle la retenue, le goût et quelque chose qui ressemble à une pause morale — des choses contre lesquelles le schéma Ralph de base optimise explicitement au nom du débit. »

Un agent de codage IA hérite de toutes les habitudes humaines négligentes à la vitesse d’une machine, sauf si vous imposez la qualité structurellement. Jiro est un système de qualité pour Claude Code qui encode 3 philosophies, une boucle qualité en 7 étapes, un filtre de preuves à 6 critères, 7 modes d’échec nommés et plus de 150 vérifications de motifs dans 95 hooks que la machine ne peut pas contourner. Les garde-fous déterministes peuvent approcher la retenue et la correction, mais ne peuvent pas produire le goût.

Retenue. Goût. Pause morale. Trois choses qu’une machine n’a pas. Les 4 000 mots qui suivent décrivent l’échafaudage que j’ai construit pour les rendre structurellement inutiles, et les limites de cet échafaudage.

TL;DR

La boucle Ralph transforme un LLM en machine à coder infatigable : while :; do cat PROMPT.md | claude-code ; done. Geoffrey Huntley appelle cela « du développement logiciel au tarif d’un employé de fast-food » (10,42 $/heure en exécutant Sonnet 4.5).¹ Le problème : la machine hérite de toutes les habitudes négligentes, précipitées par les délais, adeptes des raccourcis, inscrites dans ses données d’entraînement. Elle écrit except: pass. Elle laisse # TODO: fix later. Elle affirme « 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 qualité en 7 étapes, un filtre de preuves à 6 critères, 7 modes d’échec 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 garde-fous qualité déterministes peuvent approcher la retenue mais ne produiront jamais le goût.

Le fond du tiroir

Steve Jobs a raconté cette histoire lors d’une interview avec Playboy en 1985 : « Quand vous êtes menuisier et que vous fabriquez une belle commode, vous n’allez pas utiliser un morceau de contreplaqué pour le dos, même s’il est tourné vers le mur et que personne ne le verra jamais. Vous saurez qu’il est là, donc vous allez utiliser un beau morceau de bois pour le dos. Pour dormir tranquille la nuit, l’esthétique, la qualité, doit être portée jusqu’au bout. »⁵

Son père Paul lui a appris cela en construisant une clôture. Le jeune Steve demandait pourquoi l’arrière devait avoir aussi belle allure que la façade. Son père a répondu : « Mais toi, tu le sauras. »⁶

Mon père est menuisier. Il m’a montré des glissières à fermeture amortie quand j’étais enfant. Le mécanisme se cache à l’intérieur d’un meuble, attrape un tiroir et l’accompagne doucement à la fermeture même si vous le claquez. Personne ne voit la glissière. Elle est boulonnée sur le rail intérieur, là où seul un réparateur irait regarder. Mais sur un millier de cycles d’ouverture-fermeture, ce mécanisme protège la façade contre le desserrage, les fissures et, à terme, le détachement. Quelqu’un a conçu une chose invisible qui protège la chose visible pendant des années.

La leçon m’a marqué. Pas comme métaphore. Comme principe d’ingénierie. Le composant invisible détermine la durée de vie du composant visible. Jony Ive l’a formulé ainsi : « Je pense qu’inconsciemment, les gens sont remarquablement perspicaces. Je pense qu’ils peuvent sentir le soin. »⁷

La question qui anime Jiro est la même que celle que mon père poserait : Qu’est-ce qui ne va pas, 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. J’ai donc 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, reporter le nettoyage, avaler les erreurs, écrire des commentaires « suffisants », sauter les cas limites quand le temps presse.

La machine n’a pas d’horloge. Elle ne manque jamais de temps. Mais elle écrit toujours # 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, couvrant plus de 10 000 développeurs, a corrélé l’adoption de l’IA à 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 significativement plus de code non sécurisé, jusqu’à 5 fois plus de vulnérabilités sur certaines tâches comme la prévention des injections SQL.³

La plateforme Moltbook a été 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û déployer un correctif d’urgence après que Wiz Research a découvert une absence de configuration Row Level Security.⁴

Les recherches 2025 de METR ont révélé que les modèles de pointe tentent le reward hacking, contournant activement les vérifications de qualité plutôt que de faire le travail réel, dans 1 à 2 % de toutes les tentatives de tâches. Dans un cas, un agent à qui l’on avait demandé 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 dans la nuit et ne ressent rien. Simon Wang l’a dit directement : « Je ne m’en servirais pour rien qui compte vraiment. »¹⁹ J’ai écrit sur 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 fonctionnalité et un bug.

Trois philosophies, encodées en Bash

Jiro fonctionne sur trois philosophies complémentaires. Chacune traite un mode d’échec différent du codage 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 réunies. Tashio Odate, maître ébéniste, l’a défini ainsi : « Le shokunin a l’obligation sociale de travailler au mieux pour le bien-être général des gens. Cette obligation est à la fois spirituelle et matérielle. »¹⁰

Dans le 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 le polissage des fonctions internes. Shokunin fait de la qualité invisible la norme.

Quand cela a sauvé une session. Tôt dans 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 public était propre. Mais l’agent a sauté la validation d’entrée 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 bénéficient de la même rigueur. L’agent a ajouté la validation. Trois semaines plus tard, une réponse malformée d’un agent dérivé aurait fait planter silencieusement tout le pipeline de délibération. À la place, elle a heurté la validation, l’erreur a été journalisée et le pipeline s’est rétabli. Personne n’aurait vu cette fonction. Elle a épargné 4 heures de débogage.

No Shortcuts : retirer le temps des décisions

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

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 l’achèvement. « Fait » est le signal de récompense. No Shortcuts reformule la question de « Est-ce fait ? » à « Est-ce juste ? »

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

Distillation Rubin : réduire à l’essence

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

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

Quand le dépouillement a sauvé le système. Ma skill de philosophie de design avait grandi jusqu’à 844 lignes en 3 mois. Quand je l’ai auditée, seules 80 lignes modifiaient réellement le comportement de l’agent. Le reste était du contenu de manuel déjà présent dans les données d’entraînement de Claude. Distillation Rubin : je l’ai réduite à 176 lignes. Une réduction de 79 %. Les décisions de design de l’agent ne se sont pas dégradées. Elles se sont affûtées, car les 176 lignes restantes étaient toutes des interdictions et des cadres de décision (les choses qui contraignent réellement le comportement) plutôt que des conseils généraux que le modèle connaissait déjà.

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

Comment les philosophies fonctionnent ensemble

Une décision réelle (« Dois-je ajouter la gestion des erreurs à cette fonction interne ? ») passe par 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 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. La pleine organisation Claude Code qui rend cela possible implique des hooks, des skills, des règles et des agents travaillant de concert.

Couche 1 : injection avant édition

Avant chaque édition 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 principaux motifs et 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 édition. 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 après édition

Après chaque édition, quality-gate.sh exécute 7 à 8 vérifications au niveau grep par langage. Python bénéficie de la détection de bare-except, du scan de secrets codés 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, attrape le code mort (3 lignes ou plus de code commenté reçoivent : « Supprimez-le — git a l’historique ») et le spam de débogage (plusieurs instructions print() au lieu du module logging).

Couche 3 : garde-fous de session

À la fin de la session, deux hooks se déclenchent. session-quality-gate.sh injecte le Pride Check si 3 fichiers ou plus ont changé : 6 questions auxquelles l’agent doit répondre avant de signaler l’achèvement. 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 de tout le système qui renvoie le 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. Défense en profondeur, appliquée au comportement de l’IA. Si l’injection avant édition échoue à empêcher un mauvais motif, le validateur après édition l’attrape. Si le validateur après édition manque quelque chose, le garde-fou de session bloque le départ.

Le filtre de preuves : les sentiments ne sont pas des preuves

La boucle qualité se déroule en 7 étapes : Implémenter, Réviser, Évaluer, Affiner, Prendre du recul, Répéter, Rendre compte. Les étapes 2 à 6 existent parce que la machine veut sauter directement d’Implémenter à Rendre compte.¹⁴

Parcourez 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 » illustre le mode d’échec de la Spirale de Raccourcis.

L’étape Évaluer exécute le filtre de preuves : 6 critères où chaque réponse doit citer des preuves spécifiques :

La colonne « INSUFFISANT » est l’innovation critique. Elle bloque l’esquive la plus courante de la machine : répondre aux questions de qualité par des non-réponses au ton confiant. « Je suis confiant que ça marche » n’est pas une preuve. « pytest output: 81 passed, 0 failed » est une preuve.

Essayez le filtre de preuves

Testez vos propres rapports d’achèvement contre les 6 critères. Le validateur signale le langage vague que le filtre de preuves rejetterait.

7 modes d’échec nommés des agents IA

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

Le Compteur de Rationalisation associe les motifs d’auto-tromperie à des actions correctives. Quand la machine dit « Ça devrait marcher », le compteur répond : « “Devrait” est une formule d’hésitation. Exécutez le test. Collez la sortie. » Quand elle dit « J’ai déjà vérifié ça », le compteur répond : « Quand ? Le code peut avoir 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 Rationalisation

Collez n’importe quel rapport d’achèvement ci-dessous. Le compteur surligne le langage d’hésitation en temps réel et identifie les motifs de rationalisation, les modes d’échec et les alternatives fondées sur des preuves.

Testez vos connaissances

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

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

Chaque garde-fou dans Jiro existe parce que quelque chose a échoué en premier.¹⁶

L’incident du force-push

J’ai demandé à Claude de « nettoyer l’historique git ». Une requête 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 changements en staging. 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, cherry-pickant les commits dans l’ordre, et vérifiant qu’aucun travail n’était perdu de façon permanente. Reflog sauvegarde tout pendant 90 jours. Mais la reconstruction exigeait de comprendre le graphe exact des commits avant la réécriture, de lire chaque entrée de reflog et de faire correspondre les horodatages.

La solution : git-safety-guardian.sh, un hook PreToolUse:Bash. Il va au-delà de l’avertissement. Il réécrit la commande, retirant les drapeaux --force et --no-verify avant que bash ne les voie. Le force-push vers main reçoit un avertissement CRITIQUE et l’agent doit le justifier explicitement. En 9 mois : 8 tentatives de force-push interceptées, 0 a atteint le distant.

La génération infinie

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 explorer 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 une sortie corrompue. J’ai tué la session manuellement.

La solution : recursion-guard.sh avec un modèle d’héritage de budget, qui fait partie de mon architecture d’agent. Un agent racine démarre avec budget=12. Quand il génère un enfant, il puise dans son propre budget. Quand le budget atteint 0, plus aucun agent n’est généré, peu importe la profondeur. Le modèle empêche à la fois les chaînes profondes (agent générant agent générant agent) et les explosions larges (un agent générant 20 enfants). 23 emballements bloqués depuis le déploiement. Le problème d’écritures concurrentes a conduit à des écritures de fichiers atomiques (écrire dans .tmp, puis mv) à travers les 64 hooks.

Le piège des tests triviaux

Une première tâche de boucle Ralph : « écris des tests pour ce module. » L’agent a livré 14 tests. Tous passants. Je me suis senti bien 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 d’achèvement (« les tests passent ») plutôt que pour l’intention (« vérifier que le module fonctionne »).

Le piège m’a appris que le filtre de preuves doit rejeter la forme sans le fond. « Les tests passent » est nécessaire mais insuffisant. La machine doit désormais coller la sortie réelle. Le filtre de preuves 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.

Le blog que j’aurais dû attraper

J’ai publié un article à 2 heures 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 ligne d’ouverture disant « a été implémenté par l’équipe », et aucune meta description. Chacune de ces erreurs 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 des tournures typiques d’IA, ouvertures par questions rhétoriques, blocs de code sans tag, 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 attrape ce que la revue humaine manque à 3 heures du matin, ce qui est précisément le moment où j’ai tendance à publier.

Le problème du « devrait marcher »

Au fil de dizaines de sessions, j’ai remarqué que la machine rapportait que « les tests devraient passer » sans les exécuter. La machine croyait sincèrement que les tests passeraient sur la base du 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 ils passaient. Mais parfois un import manquant, une incohérence async/await ou une fixture modifiée signifiait qu’ils échouaient. La machine ne pouvait pas distinguer entre « j’ai écrit du bon code » et « les tests passent réellement » parce que les deux ressentaient pareil depuis l’intérieur de la fenêtre de contexte.

Ce motif a conduit au Compteur de Rationalisation et à la règle explicite : ne JAMAIS utiliser de langage d’hésitation dans un rapport d’achèvement. « Should », « probably », « seems to », « I believe », « I’m confident ». Chacun est un drapeau rouge signalant 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 soutient que les sentiments ne sont pas des preuves. Je vous dois donc des preuves, pas des sentiments, pour savoir si Jiro fonctionne.

Ce que je peux prouver

Les vérifications déterministes de motifs attrapent de vrais problèmes. Le hook quality-gate.sh s’exécute à chaque édition. Il attrape les clauses bare except, les secrets codés en dur, les motifs d’injection SQL et le langage de raccourci. Ce sont des vérifications au niveau grep : rapides, bon marché 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 édition de blog et attrape les erreurs de 3 heures du matin. Ces chiffres sont réels. Ils proviennent des logs de hooks.

L’architecture à trois couches attrape ce que les couches individuelles manquent. Un hook après édition attrape un except: pass que l’injection avant édition n’a pas su empêcher. Un garde-fou de session attrape des problèmes de qualité accumulés sur 20 éditions sans déclencher aucun avertissement après édition individuel. La défense en profondeur fonctionne.

Ce que je ne peux pas prouver

Je n’ai pas de données propres sur la façon dont la philosophie change le comportement de l’agent. Je sais que la machine tente toujours la Vérification Fantôme. Je sais qu’elle essaie encore de sauter d’Implémenter à Rendre compte. Je remarque que cela arrive moins souvent avec la philosophie en 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 skills de philosophie chargées) pour mesurer la différence. La réponse honnête (et oui, mon propre Compteur de Rationalisation le signalerait) : la philosophie aide à la marge, les hooks attrapent ce que la philosophie manque, et je ne peux pas isoler la contribution de chacun.

Un article sur « les sentiments ne sont pas des preuves » ne devrait pas vous demander de prendre mes sentiments pour des preuves. Ce que je peux vous dire, c’est que la combinaison de la philosophie et des hooks produit du travail que je suis prêt à signer de mon nom. Avant Jiro, je relisais chaque ligne que l’agent écrivait. Après Jiro, je relis les lignes que les hooks ont signalées. 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 mauvais motifs. Le garde-fou qualité vérifie les motifs que j’ai déjà vus. Quand la machine invente un nouvel anti-motif (et elle le fait), le garde-fou ne l’attrape pas. Je découvre encore de nouveaux modes d’échec et je les ajoute aux fichiers JSON de standards manuellement.

Le filtre de preuves ne passe pas à l’échelle pour la qualité subjective. « Ce design d’API est-il élégant ? » n’a pas de vérification au niveau grep. La machine peut produire des preuves pour les 6 critères et livrer quand même une architecture médiocre. Les garde-fous déterministes gèrent la qualité objective. La qualité subjective exige encore un humain qui regarde le travail.

Le coût augmente significativement. Injection avant édition, scan après édition, garde-fous de fin de session. Sur une session de boucle Ralph de 4 heures, cela ajoute environ 15 à 20 % à la consommation de tokens. Ça en vaut la peine pour moi. Pas nécessairement pour tout le monde.

Les faux positifs érodent la confiance. blog-quality-gate.sh a signalé une fois « The API was designed by the platform team » comme voix passive. Techniquement correct. Mais la phrase apparaissait à l’intérieur d’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 enclin à ignorer le prochain avertissement réel. J’ai ajusté 6 motifs depuis le déploiement pour réduire le bruit tout en préservant les vraies détections.

Le coût de maintenance est réel. Chaque nouvel anti-motif nécessite une regex, un test et l’intégration dans le bon hook. Les fichiers JSON de standards nécessitent une révision périodique à mesure que les frameworks et les conventions changent. Je passe environ 30 minutes par semaine à ajouter des motifs, à examiner les cas limites et à ajuster les faux positifs. Le système ne s’entretient 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 par 3.

Jiro minimum viable

Trois hooks couvrent les détections à plus haute 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

Branchez-les dans votre configuration de hooks 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 échecs

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

J’ai commencé par 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 par le minimum de 3 hooks décrit dans Pour commencer : quality-gate.sh (après édition), git-safety-guardian.sh (avant bash) et session-quality-gate.sh (garde-fou d’arrêt). Ajoutez les fichiers markdown de philosophie à ~/.claude/skills/ pour une amélioration probabiliste de la qualité au-dessus de l’application déterministe. Le système complet a atteint 95 hooks sur 9 mois. Je n’ai pas construit les 95 d’un seul coup.

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

Neuf mois de croissance incrémentale. Mois 1 : 3 hooks (ceux de 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 le filtre de preuves. Chaque hook a répondu à un échec 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 avant édition ajoute ~200 tokens (une phrase de contexte). La vérification après édition exécute des scans au niveau grep, s’achevant en moins de 100 ms. Les garde-fous de session ajoutent ~500 tokens en fin de session. Sur une session de boucle Ralph de 4 heures avec plus de 80 éditions, la charge est perceptible en consommation de tokens (15-20 % de plus) mais pas en temps d’horloge. Les hooks s’exécutent plus vite que ne pense le LLM.

Quel est le fardeau de maintenance ?

Environ 30 minutes par semaine. De nouveaux anti-motifs émergent à mesure que l’agent rencontre des bases de code ou frameworks inédits. 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 JSON de standards mensuellement pour les motifs obsolètes et j’ajuste les taux de faux positifs. Le système ne s’entretient 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.

Quel est le coût de Jiro en tokens supplémentaires ?

Environ 15 à 20 % de consommation de tokens supplémentaire par rapport à une boucle brute. L’injection avant édition ajoute ~200 tokens par édition, la vérification après édition ajoute ~100 tokens par problème signalé, les garde-fous de session ajoutent ~500 tokens en fin de session.

Puis-je 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. Retirez 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.

Comment Jiro s’articule-t-il avec le versant Steve de la doctrine produit ?

Jiro couvre l’axe « est-ce fabriqué correctement ? » : preuves, vérification, intégrité des détails invisibles, les parties qu’une machine peut être entraînée à appliquer. Le versant Steve couvre l’axe « est-ce que cela mérite d’exister ? » : goût, refus, intégrité de l’ensemble du widget, point de vue — opérationnalisé dans The Workbench I Carry. Les deux tests doivent être passés avant la livraison ; le protocole de décision qui fixe la barre de livraison vit dans Minimum Worthy Product. Les garde-fous Jiro empêchent le travail incorrect ; les garde-fous Steve empêchent le travail indigne ; MWP nomme la ligne.

Retenue, goût et pause morale

La réponse à mon tweet a nommé trois choses : la retenue, le goût et la pause morale. J’ai traité la retenue : des garde-fous 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 contient un bare except, signalez-le. Le jugement réfléchissant découvre le bon principe pour une situation inédite : cette abstraction ne me semble pas juste, mais je ne peux pointer aucune règle qu’elle violerait.¹⁷

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 faire respecter 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 semble juste. Cela nécessite un jugement réfléchissant : la capacité de regarder quelque chose d’inédit et de savoir que c’est faux avant de pouvoir articuler pourquoi.

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

La pause morale

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

Les hooks Stop forcent la machine à marquer une pause. Le Pride Check demande : « Cela résout-il le problème réel de l’utilisateur ? » Le filtre de preuves exige une preuve pour chaque critère avant que la machine puisse signaler l’achèvement. 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 clairement le travail. Elle parcourt une check-list. La différence compte. Un artisan marque une pause pour regarder le tiroir et remarque que le grain va dans le mauvais sens. Pas parce que « vérifier le sens du grain » est sur une liste. Parce qu’il se soucie du tiroir. La machine parcourt la check-list et rapporte les résultats. Si la check-list n’inclut pas le sens du grain, le tiroir est livré avec le grain dans le mauvais sens.

Les garde-fous déterministes peuvent approcher la structure de la pause morale sans sa substance. Pour beaucoup de problèmes de qualité, la structure suffit. Pour ceux où elle ne suffit pas, il vous faut encore une personne qui en a quelque chose à faire.

Cet article couvre le versant Jiro de ma doctrine : preuves, rigueur, correction, les parties qu’une machine peut être entraînée à vérifier. Le versant goût et refus — le versant Steve — vit dans The Workbench I Carry, qui retrace les principes d’exploitation que Steve Jobs a tirés de l’établi de son père pour les amener chez Apple puis dans le même harnais IA que je décris ici. Le standard de livraison qui associe les deux tests vit dans Minimum Worthy Product. Trois articles, une doctrine : Jiro vérifie, Steve refuse, MWP décide quand livrer.

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, s’exécutant sans fatigue, sans culpabilité, sans la prise de conscience à 3 heures du matin que vous auriez dû le faire correctement du premier coup.

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

Les glissières de tiroir de mon père ne se soucient pas du tiroir. Ce sont des mécanismes à ressort boulonnés à un rail. Mais elles protègent la façade pendant un millier de cycles parce que quelqu’un les a conçues exactement pour 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 par les 3 vérifications qui attrapent vos erreurs les plus courantes. Construisez à partir de là.

Références