L'enseignement de 60 jours, le ROI en trois axes

Trente-deux jours de production en solo sur un ERP, 118 808 lignes de TypeScript, six versions de doctrine, quatre relecteurs externes intégrés. J'ai compilé ce que j'ai appris en quatorze règles opérationnelles, installables en une commande : le Counterpart Toolkit v0.4.1. C'est à la fois l'enseignement matériel de soixante jours de codage solo avec Claude Code, et la cartographie des quatorze failure modes silencieux que j'ai vu se répéter — pour qui code seul avec une IA en production et n'a plus de PR review pour attraper la dérive.

Le ROI est chiffré sur trois axes, mesuré sur Rembrandt :

R4 *Falsify before fix* — cinq à dix minutes de protocole en amont du fix évitent trente à quatre-vingt-dix minutes de cycle fix-puis-rollback quand la première hypothèse plausible se révèle fausse. ROI 6 à 18× par incident. Sur soixante jours, j'ai cessé de perdre une heure deux à trois fois par semaine sur des fixes qui ne fixaient rien.

R2 *Filesystem over summary* couplée à R6 *Live/Snapshot/Cache* et aux sondes drift quotidiennes — le délai médian apparition→détection d'une divergence silencieuse passe d'invisible à 35,3 jours sur 90 jours glissants. M3 recalibrée publiquement à ≤ 30 jours dans le manifesto, parce que la cible originale (≤ 7 j) était une intuition que la pratique a refusée.

Un sub-agent challenger qui produit des objections au format imposé Tool / Question / Refutation criterion. Du désaccord matériel, pas du « are you sure? » émotionnel qui pousse à réviser sans fait nouveau.

Voici comment, en 1400 mots et une commande d'install.

Le diagnostic — l'incident qui a déclenché la doctrine

Coder seul avec une IA, c'est composer deux complaisances. Celle de l'agent, sycophant par construction parce que le reinforcement learning from human feedback l'a entraîné à plaire au prompteur. Et celle du solo, self-validating par humanité, qui valide son propre travail parce qu'il ne reste plus personne pour le contester. Mises bout à bout, ces deux complaisances produisent un drift que ni l'agent ni l'humain ne signale — et qui ne se voit qu'à l'audit, longtemps après.

C'est en préparant l'audit source unique de fin avril — ADR-0024, un travail de fond sur les divergences que je remettais à plus tard depuis trois mois — que je suis tombé sur l'écart, par hasard, en croisant deux requêtes que personne n'avait jamais croisées avant. Une fiche élève, initiale Y.B. : la colonne contacts.montant_total portait 1 159 € saisis à la main quelque part en 2024, jamais touchés depuis. La somme réelle des échéances, calculée à la volée, en faisait 2 262 €. Mille euros d'écart, sur une seule fiche, sans qu'aucune alarme n'ait jamais sonné. J'élargis le grep : cinq cent soixante contacts dans le même état, parfois à plusieurs milliers d'euros près. Et pourtant montant_total était lue chaque jour dans le dashboard trésorerie — une valeur dérivable qu'on stockait sans rafraîchisseur, traitée comme un fait passé immuable alors qu'elle aurait dû vivre à la volée. C'est exactement le piège que R6 Live/Snapshot/Cache veut empêcher, et R6 est sortie de ce moment-là.

R4 Falsify before fix, la seule règle exposée ici

Le toolkit énonce R4 en cinq étapes textuelles. Le skill falsify-before-fix en est l'invocable instance — la version que Claude Code charge dans sa session, et qu'il ne peut pas sauter quand il s'apprête à écrire du code de fix.

name: falsify-before-fix
description: Activate this skill before writing the fix code on a bug or
  incident. Triggers on "fix", "bug", "patch", "hotfix", "workaround",
  "doesn't work", "diagnose", "hypothesis", "root cause". Enforces a
  single-sentence causal hypothesis and three material probes designed
  to refute it before any line of fix code is committed.
  Operational instance of R4 of the Counterpart Toolkit.

Le protocole tient en cinq étapes : (1) formuler une hypothèse causale en une phrase (pas un symptôme — « le compteur lit depuis l'ancienne table après la migration du 12 mai » vaut mieux que « le compteur est faux ») ; (2) lister trois sondes conçues pour réfuter, pas pour confirmer, parce qu'une sonde de confirmation trouve toujours ce qu'elle cherche, par sélection ; chaque sonde porte ses trois champs Tool / Question / Refutation criterion ; (3) exécuter et reporter la sortie brute, jamais paraphrasée ; (4) brancher — aucune sonde ne réfute → on écrit le fix ; une sonde réfute → on repart d'une nouvelle hypothèse ; sondes ambiguës → quatrième sonde plus tranchante avant tout code ; (5) sortir hypothèse retenue, sondes exécutées, diff, et critère d'observation post-fix.

Pourquoi un skill et pas la règle textuelle qui vivait déjà en CLAUDE.md ? Parce que la règle textuelle n'avait pas tenu sous pression. Le 6 mai, en début d'après-midi, un bug Sentry remonte que le compteur d'inscriptions du jour affiche zéro alors qu'on en a saisi trois en matinée. Mon réflexe arrive avant le protocole, et la main est déjà sur le clavier — « le cache n'est pas invalidé », je commit, je déploie. Trente minutes plus tard, rollback : le bug est toujours là. La cause réelle, qu'une sonde grep de quatre-vingt-dix secondes aurait remontée, c'est qu'aucun appel à cache_invalidate n'existait dans le pipeline d'inscription — pas un cache obsolète, un cache absent. R4 était dans CLAUDE.md depuis trois semaines. Je ne l'ai simplement pas suivie ce jour-là, parce qu'aucun dispositif n'interrompait ma course entre le bug et le commit.

C'est la différence qui fait tout. Une règle textuelle dans CLAUDE.md, l'agent la lit au début de la session, et rien ne l'oblige à la convoquer au moment exact où il en aurait besoin. Un skill, c'est un mécanisme matériel : il se charge automatiquement sur des mots-clés (« fix », « bug », « doesn't work ») et impose son protocole dans la session active — pas un rappel à se faire, un interrupteur que la session a déjà actionné. Dix jours après l'incident du 6 mai, le skill falsify-before-fix est commit. L'enseignement de l'échec devient un dispositif. C'est la seule des 14 règles exposée dans cet article, et les 13 autres sont dans le repo, toutes construites sur le même principe : matérialiser ce qui resterait pieux en textuel seul.

Le toolkit s'applique à lui-même, chiffres et rétractations

Six versions en 32 jours, chacune ancrée dans un fait nouveau documenté. v0.3 → v0.3.1 sur un premier relecteur externe (apparat théorique disproportionné, rétracté). v0.3.1 → v0.3.2 sur un second (sept recommandations, deux work-items ouverts). v0.3.3 instrumentation M1-M5 publiée. v0.4 séparation toolkit/manifesto sur un troisième. v0.4 → v0.4.1 sur un quatrième relecteur externe (Claude.ai web), un commit consolidé intégrant trois refactors plus la LOC mesurée.

LOC corrigé 118 808 lignes mesurées par find + wc -l sur TS/TSX/JS/JSX (exclusions explicites), contre 35 k cité dans les versions antérieures — la doctrine elle-même avait péché contre R2, Cache sans rafraîchisseur projeté sur sa propre description. M3 recalibrée ≤ 7 j → ≤ 30 j avec justification publique : la cible originale était une intuition non honorée par les 35,3 jours mesurés en pratique. M1 et M5 documentés comme échecs d'instrumentation, pas comme succès : M1 sur-sensible à 12,33 vs ≤ 1 cible, M5 classe 90 % des briefs en unknown.

Four external readers across six versions. The last two audited v0.3.3 then v0.4.1 — their objections are integrated in the release notes (manifesto §From v0.4 to v0.4.1). One reviewer called the falsify-before-fix skill "the best artifact of the doctrine among the ones I read". v0.5 prévue 15 juillet 2026.

Steal three things in 20 minutes

Trois règles à essayer avant d'installer le reste.

R4 *Falsify before fix* — empêche le cycle fix → rollback déclenché par la première hypothèse plausible mais fausse. Détaillée ci-dessus.

R6 *Live / Snapshot / Cache* — empêche qu'une valeur dérivée stockée diverge silencieusement de sa source. Toute colonne dérivable déclare sa catégorie dans le commit qui la crée, ou le commit est rejeté.

R10 *Silent failure forbidden* — empêche que catch {}, await sans destructuration { error }, 2>/dev/null et autres mécanismes d'avalement mentent à votre observabilité jusqu'à ce que la production craque sur une dépendance en aval.

Le repo : github.com/michelfaure/doctrine-counterpart. La commande d'install :

git clone https://github.com/michelfaure/doctrine-counterpart.git && \
  cd doctrine-counterpart && \
  ./install.sh --yes /path/to/your/project

Licence CC-BY-4.0. Le manifesto promet une citation nominative dans la v0.5 pour qui propose un retour exploitable — quelle règle manque pour votre stack ? Les commentaires DEV.to sont inputs directs pour la prochaine version. R14 *spike escape hatch* couvre le code prototype destiné à disparaître sous sept jours, exempté de R6/R7/R8 : l'adoption ne force pas la même friction au spike qu'au code de production.

Coda

Un agent qui ne vous contredit pas n'est pas un counterpart, c'est une dactylo plus rapide. Ces 14 règles restaurent le désaccord — matériellement, pas mentalement. Elles ne demandent pas à l'agent d'être moins sycophant, ni au solo d'être plus vigilant ; elles posent les dispositifs (skills invocables, hooks bloquants, sub-agent challenger) qui interrompent la course productive là où la complaisance se compose. Le toolkit est la prothèse qu'il reste au solo quand le PR review a disparu et qu'il refuse de coder à l'oreille. Si une seule des 14 vous évite un cycle fix-rollback la semaine prochaine, elle s'est déjà remboursée.

Counterpart Toolkit v0.4.1, fourteen operational rules in ~200 lines, six iterations in 32 days, four external reviews integrated. Tested on 60+ days of solo ERP (118 808 lines, 65+ ADRs). Licence CC-BY-4.0 : github.com/michelfaure/doctrine-counterpart