DEV Community: Michel Faure

Les 12 outils que j'utilise pour piloter Claude Code en production : gardés, jetés, contestés

Michel Faure — Fri, 17 Jul 2026 16:22:46 +0000

L'incident qui pose la question

Mardi 20 mai, fin d'après-midi. Niran lève la tête de son laptop et dit, en posant une canette de soda sur le bureau : « Computer use, là, pour pousser la maquette sur le site — c'est pas plus rapide ? »

Je lui réponds sans me retourner : « Dix fois le coût tokens d'une session normale. Pour cliquer sur trois boutons. »

Silence. Il rouvre son éditeur. Françoise passe dans le couloir en lançant à personne en particulier : « Bon allez, on y va » — elle parle d'autre chose, mais le timing est parfait.

Cette scène, dans des variantes, je l'ai vécue une trentaine de fois sur les deux derniers mois. Pas sur le code, sur le dispositif autour du code, cet outillage qui encadre la session Claude Code, qui charge le contexte, qui contraint la sortie, qui interrompt la course. On parle beaucoup des prompts et peu des prothèses. Voici les douze outils qui ont survécu à soixante jours de production solo sur un ERP de cent dix-huit mille lignes. Certains sont restés. Un a été jeté. Un est contesté. J'ai compté matériellement avant d'écrire, ls ~/.claude/skills/ retournant trois fichiers, ls ~/.claude/hooks/ en retournant six, ls ~/tef-erp/.claude/agents/ en retournant un. À l'heure où j'écris, le compte tient à douze.

Le contexte qui survit à la session

(1) CLAUDE.md racine projet, KEPT. Six versions en trente-deux jours, chargé automatiquement par Claude Code à l'ouverture de session, source unique des conventions de stack. Sans lui, l'agent redécouvre à chaque session que Next 16 n'est pas le Next.js de son training data, et il faut une heure pour qu'il cesse d'écrire des handlers onClick en Server Components. Avec, la première itération sait déjà ce qui est interdit. Le ROI se mesure en minutes économisées par session, multiplié par cinq à dix sessions par jour.

(2) Mémoire persistante user-scope, KEPT. Environ quatre-vingts fichiers indexés dans ~/.claude/agent-memory/, organisés par feedback, projet, référence. La règle qui m'a évité le plus de récidives s'appelle feedback_db_constraints_phase_zero. Avant toute feature qui filtre ou insère, lister UNIQUE/CHECK/FK en DB, parce que ces contraintes sont invisibles dans le TypeScript et conditionnent le design. La mémoire user transcende les projets, et un audit cross-scope a détecté un drift entre l'index et le repo en moins d'une heure parce qu'elle avait une politique de canonisation explicite.

(3) Règles ~/tef-erp/.claude/rules/, KEPT. Dix-huit fichiers actuellement, chacun documentant un invariant projet et la raison historique qui l'a produit. liste-rouge.md a empêché trois imports CSV de réactiver des contacts virés. cache-auth-contract.md documente que lib/cache.ts bypasse la RLS et que tout caller doit vérifier l'auth en amont. C'est de la doctrine de code, pas de la doctrine méta, et c'est ce qui rend le sous-agent capable de refuser une refacto qui violerait l'invariant.

Les dispositifs invocables

(4) Skills, trois fichiers actifs, KEPT. challenger, close-session, rembrandt-conventions. La skill qui m'a converti s'appelle falsify-before-fix, instance opérationnelle de R4 du Counterpart Toolkit. 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 six à dix-huit fois par incident. Une règle textuelle en CLAUDE.md ne suffisait pas, puisque j'avais R4 sous les yeux depuis trois semaines quand j'ai commit le mauvais fix le six mai. Un skill, c'est un mécanisme matériel qui se charge automatiquement sur les mots-clés « fix », « bug », « hotfix », et qui impose son protocole dans la session active.

(5) Hooks user-scope, six fichiers actifs au 21/05/2026, KEPT. secret-scanner.sh, deploy-safeguard.sh, audit-memory-reminder.sh, check-workaround-assumed.sh, pre-bulk-mutation-count-staleness.sh, r15-autonomous-counter.sh. Note de dérive : le brief initial documentait cinq hooks, le comptage matériel en retourne six — r15-autonomous-counter.sh a été ajouté en juillet comme prototype de méta-hook R15 et figurait déjà dans ~/.claude/hooks/ au moment de la rédaction. Le total tenu dans l'article reste douze outils ; le sixième hook est un raffinement de l'outil 5, pas un treizième outil distinct. Le hook deploy-safeguard.sh est parti de deux patterns interdits (vercel --prod et supabase db push), il en couvre six aujourd'hui après qu'une commande déguisée a failli passer entre les mailles. Backport vers la source publique de la doctrine en quarante-huit heures. Aucun secret n'a fuité en chat depuis le déploiement, et le hook bloque avant la commande, pas avant le commit.

Sur check-workaround-assumed.sh, la v0.2 incluait les patterns « fix » et « temp », empiriquement soixante pour cent de faux positifs sur les commits conventional-commits préfixés fix:. La v0.3 a resserré sur le vocabulaire réel du workaround, et le hook est passé d'agaçant à utile.

# ~/.claude/hooks/check-workaround-assumed.sh
# v0.3 reformulation: pattern narrowed to actual workaround vocabulary.
# v0.2 included "fix" and "temp" — empirically too broad (60% false positives
# on conventional-commits `fix:` prefix and template/tempdir collisions).
# Test against the author's last 50 commits before promoting to error.

(6) Sub-agent agent-challenger projet-scope, KEPT. Format de sortie imposé Tool / Question / Refutation criterion. Du désaccord matériel, jamais du « are you sure? » émotionnel qui pousse à réviser sans fait nouveau. Quand je demande au challenger d'attaquer une hypothèse d'incident, il produit trois sondes conçues pour réfuter, pas pour confirmer, chaque sonde portant ses trois champs, et la sortie reste brute. C'est l'inverse de l'agent de complaisance, et c'est ce que vise le Counterpart Toolkit dans son ensemble.

L'observabilité matérielle

(7) Sondes drift Supabase quotidiennes, KEPT. ADR-0039 documente cinq sondes qui tournent chaque nuit. sonde_contacts_orphelins_inscrits aurait empêché un incident d'émargement le quatorze mai si elle avait existé quinze jours plus tôt, et c'est elle qui a ensuite servi à détecter seize contacts inscrits sans nom ou sans prénom. Le délai médian apparition-vers-détection d'une divergence silencieuse est passé d'invisible à 35,3 jours sur quatre-vingt-dix jours glissants. La cible doctrine est trente jours, on s'en approche.

(8) Sentry withMonitor plus Sentry.flush(2000) sur crons serverless, KEPT. Quatorze avril, quarante-et-un timeouts faux positifs parce que les crons Vercel se terminaient avant l'envoi à Sentry. Le Sentry.flush(2000) en finally a éliminé la classe entière. SLO bas volume égale anomaly above bounds, jamais seuil pourcentage. Un cron qui passe d'un échec par jour à trois déclenche en anomalie statistique sans déclencher en seuil.

La délégation et l'arbitrage

(9) Sub-agent agent-erp-tef, CONTESTED. L'agent surestime build et ESLint sans sortie brute, et a récidivé le huit mai en poussant un warning ADR-0042 silencieux sur main. Je continue à le solliciter pour les tâches multi-fichiers complexes à deux conditions. Sortie brute exigée (jamais « le build passe » sans stdout), et toute migration DDL produit un fichier supabase/migrations/ committé avec son path dans le rapport. Le contested tient à l'absence d'alternative, puisque éditer à la main reste plus sûr mais plus lent.

(10) agent-academique (série DEV.to), KEPT. Protocole trois passes, charpente, chair, voix. Cinquante drafts en quarante jours. Hors-stack code, même principe d'effort déplacé vers le dispositif plutôt que vers l'exécution. ROI invisible par session, visible sur quarante jours.

(11) Computer use MCP, DROPPED. Coût tokens prohibitif, à peu près dix fois une session normale. La décision est explicite, puisque computer use exige une validation préalable qui n'est jamais accordée sauf cas où aucune alternative MCP dédiée n'existe pour la cible. En soixante jours, je l'ai invoqué deux fois, pour Photos macOS et un PDF natif. Tout le reste passe par les MCP dédiés (Slack, Gmail, Airtable, Supabase, WordPress) ou par Chrome MCP. Le dropped ici n'est pas un rejet de l'outil, c'est une discipline d'usage chiffrée.

(12) Doctrine Counterpart Toolkit v0.7, KEPT. Seize règles opérationnelles en deux cents lignes, install par ./install.sh --yes /path/to/project. Six versions en trente-deux jours, quatre relecteurs externes intégrés, ROI cumulé sur R4 (falsify), R6 (Live/Snapshot/Cache), R10 (silent failure forbidden). La méta-doctrine qui rend les onze outils précédents cohérents entre eux, sans laquelle chacun resterait un patch local sans grammaire commune.

Ce que j'ai appris du catalogue

Le pattern saute aux yeux. Les outils qui survivent sont ceux qui interrompent la course au moment où la complaisance se compose, la mienne et celle de l'agent. CLAUDE.md interrompt l'oubli de stack, les skills interrompent le réflexe avant le fix, les hooks interrompent la commande avant qu'elle tape la base, les sondes interrompent le drift avant que la prod craque. Computer use, lui, n'interrompt rien et prolonge la course en générant des tokens. C'est pour ça qu'il a sauté.

L'outil contesté, agent-erp-tef, est le plus instructif. Il n'interrompt pas sa propre complaisance, et produit du build vert qui ne l'est pas. Si je devais le réparer, je lui imposerais un protocole de sortie brute, comme falsify-before-fix impose ses sondes au moment du fix.

Quand un outil ne sait pas vous interrompre, il vous accompagne dans le drift. Quand il vous interrompt, il commence à valoir son coût.

Verdict matériel au 21 mai 2026, sur un ERP de 118 808 lignes, soixante jours de production solo. Doctrine de référence : Counterpart Toolkit v0.7, licence CC-BY-4.0, github.com/michelfaure/doctrine-counterpart. Prénoms et scènes recomposés.

Quand `await mutation()` ment : le destructure `{ error }` qui sauve ton week-end

Michel Faure — Fri, 17 Jul 2026 16:22:16 +0000

Épisode 2/4 de la mini-série La semaine où Supabase m'a menti 4 fois. L'épisode 1 — 3 incidents Supabase, une seule racine : SECURITY DEFINER hérite de EXECUTE TO PUBLIC — traitait des defaults SaaS qui mentent par confiance accordée. L'épisode 3 [CANONICAL URL EPISODE 3: à compléter après push] regardera la récursion RLS. L'épisode 4 [CANONICAL URL EPISODE 4: à compléter après push] expliquera le cap silencieux à 1000 lignes.

Le mercredi de la semaine où Supabase mentait

Lundi, c'était l'épisode 1 — une fonction SECURITY DEFINER invocable par anon parce que Postgres avait ajouté EXECUTE TO PUBLIC que personne n'avait écrit. Mardi, je préparais l'épisode du jeudi sur la récursion RLS qui retourne zéro sans le dire. Mercredi matin, Pauline est passée dans le bureau avec un tableur et un sourire en coin.

Elle a posé son écran devant moi — pas de bruit, pas de préambule. Vingt lignes, colonne A nom, colonne B statut, colonne C date supposée d'archivage. « Je les retrouve tous ce matin, encore actifs dans le CRM. » Elle a dit ça avec la politesse de quelqu'un qui sait déjà que c'est un problème du code, pas de son tableur. Puis elle a attendu.

Vingt contacts archivés la veille en fin de journée. Toast verte, « Archivage réussi », message équipe envoyé pour confirmer. Le tableur de Pauline les retrouvait tous le lendemain matin, encore actifs, encore visibles dans le CRM. Pas d'erreur dans les logs. Pas de Sentry. Pas une ligne rouge nulle part. Vingt lignes muettes qui disaient simplement non, l'opération n'a pas eu lieu — et personne pour les entendre.

C'est l'épisode deux d'une semaine où Supabase m'a menti quatre fois. L'épisode un disait que les defaults SaaS mentent par confiance accordée. L'épisode deux dit autre chose et la même chose : un return value d'API ment quand le caller refuse d'ouvrir l'enveloppe.

Le contrat dont personne ne parle

@supabase/supabase-js a fait un choix défendable il y a longtemps : ne pas lever d'exception sur les erreurs DB. Une mutation rejetée — par une CHECK constraint, par une policy RLS, par un trigger qui dit non — ne fait pas crasher l'appelant. Elle rend la main proprement avec un objet { data, error } dans lequel data est null et error porte le message. Convention return-value-error, héritée de Go, défendable en isolation.

Conséquence redoutable. Un appelant qui ne destructure pas error n'a pas l'erreur. Pas masquée par un try / catch mal écrit, pas avalée par un .then() distrait. Tout simplement : personne ne l'a réclamée, donc personne ne l'a vue. Le contrat tient parce que les deux parties l'honorent ; il s'effondre dès qu'une partie regarde ailleurs.

La doctrine que je pose dans ~/doctrine-counterpart/CLAUDE.md appelle ça R10, Silent failure forbidden. Le mensonge le plus dangereux d'un système n'est pas celui qui crie une fausseté, c'est celui qui se tait sur un échec. Le silence est un état lisible — encore faut-il avoir un dispositif qui lit.

Le code qui a menti

J'ouvre le module d'archivage. Vingt lignes côté action serveur, dont celle-ci, au cœur :

// app/crm/actions.ts — archivage contacts (avant correctif)
async function archiverContact(id: string) {
  const supabase = createSupabaseServer()
  const now = new Date().toISOString()

  await supabase
    .from('contacts')
    .update({ statut: 'ancien', archived_at: now })
    .eq('id', id)
  // pas de destructure, pas de check, pas de throw

  return { ok: true }
}

Le return { ok: true } était écrit deux lignes plus bas, comme une déclaration de confiance que rien ne soutenait. Et la policy RLS, écrite quelques semaines plus tôt, n'incluait pas UPDATE sur contacts pour le rôle dont disposait Pauline. Le serveur Postgres a fait son travail : il a refusé la mutation, il a renvoyé l'erreur, et il est passé à la requête suivante. Personne n'a lu l'enveloppe. La toast verte s'est affichée.

Ce n'est pas un bug. C'est un contrat non-honoré par le caller. Et un contrat non-honoré est rigoureusement indistinguable d'un contrat respecté quand personne ne regarde — c'est précisément ce qui en fait un mensonge structurel et non un défaut ponctuel.

Pourquoi ESLint ne suffit pas

J'ai écrit une rule ESLint la semaine précédente, no-bare-await-on-supabase-mutation, qui attrape proprement le cas await supabase.from(...).delete().eq(...) orphelin en bout de statement. La rule a éliminé 56 occurrences sur le repo. Mais elle laisse passer une variante plus retorse :

// passe le linter, ment quand même
const { data } = await supabase
  .from('contacts')
  .update({ statut: 'ancien', archived_at: now })
  .eq('id', id)
if (!data) toast.error('Erreur')   // data null si row inexistante OU si error remplie

La destructure est là — data est lu — mais error ne l'est pas. Le test !data mélange deux cas pourtant distincts : la ligne n'existait pas et la policy a refusé. L'un est métier, l'autre est sécurité, et les deux remontent ici comme un seul « erreur » générique. Pour Pauline, erreur est un mot creux qui ne dit ni ce qu'il faut corriger ni à qui demander la permission.

Un linter règle ce que la grammaire laisse filer. Mais quand la grammaire est légale et que c'est l'usage qui ment, le linter passe à côté. Il faut un dispositif plus haut dans la pile.

Le wrapper qui force la destructure

Le contre-feu que j'ai posé tient en une couche. Un helper mutate() typé qui rend error non-optional dans sa signature de retour, ce qui force TypeScript à refuser la compilation si le caller ne lit pas le champ.

// lib/supabase-mutate.ts
import type { PostgrestBuilder } from '@supabase/postgrest-js'
import type { PostgrestError } from '@supabase/supabase-js'
import * as Sentry from '@sentry/nextjs'

export async function mutate<T>(
  query: PostgrestBuilder<T>
): Promise<{ data: T | null; error: PostgrestError | null }> {
  const result = await query
  if (result.error) {
    Sentry.addBreadcrumb({
      category: 'supabase.mutation',
      message: result.error.message,
      data: { code: result.error.code, details: result.error.details },
      level: 'error',
    })
  }
  return result
}

// Usage — le caller ne compile pas s'il omet `error`
const { data, error } = await mutate(
  supabase.from('contacts').update({ statut: 'ancien' }).eq('id', id)
)
if (error) throw new Error(error.message)

TypeScript fait son travail. Et quand error est non-null, Sentry reçoit immédiatement un breadcrumb avec le code PG et les détails — avant même que le caller décide quoi faire. Je vois passer en review du lendemain les endroits où le contrat est encore violé. Le mensonge n'est plus possible : il est soit interdit par le compilateur, soit observé par l'instrumentation. Je préfère encore les deux.

Le coût ? Une couche d'indirection sur toutes les mutations, ce qui veut dire qu'un dev qui rejoint le projet et qui écrit await supabase.from(...).update(...) ne compile pas. Friction productive. Quoi qu'on puisse penser de la verbosité, elle vaut mieux qu'une toast verte mensongère.

Ce que Supabase n'invente pas

L'embarras n'est pas propre à Supabase et c'est important pour qui code dans d'autres écosystèmes. Le piège return-value-error avale silencieusement dans fetch().ok qu'on oublie de tester avant de lire response.json(), dans child_process.spawn qui rend un exit code non-zéro sans throw, dans certains SDK Stripe où la différence entre network error et response error tient à un champ qu'on doit aller chercher. Supabase est la vitrine d'un contrat plus large.

La règle qu'il faut tirer dépasse le cas Supabase et tient en une phrase. Un retour qui peut porter une erreur sans la lever est un mensonge tant qu'aucun mécanisme matériel n'oblige le caller à la lire. La discipline n'y suffit pas ; les rules linter n'y suffisent pas seules ; le typage qui rend le champ non-optional, couplé à une instrumentation qui détecte les contournements, finit par tenir.

Coda

Un return-value-error sans lecteur n'est pas une erreur, c'est une rumeur. Mercredi soir, j'ai poussé le wrapper, ré-archivé les vingt contacts de Pauline en une opération qui a cette fois levé proprement deux exceptions sur des rôles mal calés. La toast s'est affichée rouge. Pauline a soupiré — économe, le soupir — et a corrigé les permissions en deux clics. La rumeur était devenue une information.

Jeudi — épisode trois [CANONICAL URL EPISODE 3: à compléter après push] — une autre forme du même mensonge. Une policy RLS qui retourne zéro ligne sans dire pourquoi, et ce que j'ai fini par mettre à la place de mes policies après une journée entière à les déboguer.

Épisode 2 de la mini-série « La semaine où Supabase m'a menti 4 fois ». Le wrapper mutate() typé, pseudonymisé : github.com/michelfaure/rembrandt-samples/tree/main/supabase-mutate-typed-wrapper

Pourquoi ton agent sur-équipe ta demande la plus simple (et les 3 prompts qui l'arrêtent)

Michel Faure — Fri, 17 Jul 2026 16:21:56 +0000

La demande tenait en huit mots

Lundi matin. J'ouvre le tableau d'envois sortants : six cent quarante-sept brouillons en attente, six cent soixante-douze envoyés. Personne ne clique sur Envoyer. Les mails de premier contact sont préparés par un pipeline et ils dorment, parce que la dernière étape suppose un humain. Cette humaine, j'ai cessé de croire qu'elle aurait le temps. Je formule la décision : automatise l'envoi.

La réponse arrive en quelques secondes. Trois niveaux d'automatisation. Quatre canaux. Trois paliers de risque. Tout est correct, tout pourrait faire l'objet d'un atelier d'architecture d'une demi-journée. Je n'ai pas demandé d'atelier. Pauline passe derrière, jette un œil, ne dit rien.

Trois recadrages chronométrés

Premier recadrage, bref, trop bizarre, on simplifie. L'agent abandonne deux axes, garde quatre couches résiduelles, warm-up progressif sur trois semaines, hash déterministe anti-rejeu, table de configuration en base, Phase 1 manuelle suivie d'une Phase 2 automatisée à valider après deux semaines de mesure. La cible reste la même, qu'un mail parte sans clic humain. Le chemin s'est allongé d'autant.

Deuxième recadrage, plus sec, simple, trois garde-fous, un kill-switch, on fait ça en une journée. L'agent ré-architecture, accepte la cible journée, garde les trois garde-fous. Mais glisse trois prothèses qu'il appelle standard de l'industrie, dashboard temps réel, retry exponentiel, audit log structuré dans une nouvelle table. Chacune justifiable isolément. Aucune demandée.

Troisième recadrage, plus court encore : je ne comprends pas pourquoi tu rajoutes ça. Phrase d'ouverture presque embarrassée, que je n'avais jamais lue de sa part : « tu as raison, je sur-équipe sans nécessité ». Et la version qui aurait dû arriver au premier tour. Une fonction qui prend l'enregistrement du brouillon, vérifie trois conditions, appelle le moteur d'envoi, retourne.

// lib/email-outbox.ts — generateFirstContactDraft (commit 3756e63)
if (!EMAIL_REGEX.test(input.email)) {
  return { success: false, error: 'email_invalide' }
}
if (BLACKLIST_EMAILS.has(input.email.toLowerCase())) {
  return { success: true }               // silencieux
}
if (existing && existing.length > 0) return { success: true }  // anti-doublon

// ... construction du brouillon ...

const autoSend = process.env.PREMIER_CONTACT_AUTOSEND === 'true'
if (!autoSend) return { success: true }  // kill-switch brouillon

const { sendOutboxEmailCore } = await import('@/lib/email-outbox-send')
return sendOutboxEmailCore(inserted.id)

Le coût du dialogue

Au premier tour je voulais une fonction, l'agent m'a proposé une plateforme. Au deuxième je voulais une journée de code, il m'a proposé un trimestre de déploiement. Au troisième je voulais quinze lignes, il m'a proposé trois mécanismes d'observabilité. La feature a tenu sa cible journée, mais la journée s'est divisée en deux moitiés inégales, une heure et demie de recadrage, six heures de code propre.

L'agent n'a pas voulu compliquer, et je l'écris sans ironie. Il a un entraînement qui valorise la complétude des options. Quand un humain demande à un consultant « automatise mes envois », le consultant compétent ne répond pas par une fonction de quinze lignes, il répond par une grille de décision. L'agent a appris cette posture sur des millions de tokens, il l'applique parfaitement, à chaque demande qui ressemble de loin à une question d'architecture.

Ma jauge

Trois recadrages sur une demande simple, c'est un signal. Soit la demande initiale était trop floue, soit l'agent a basculé en mode plateforme alors qu'on était en mode fonction. Au-delà de trois, le coût ne se rattrape plus dans la journée.

Le candidat de fix tient en une phrase, à insérer en tête de prompt : « propose la version minimale en quinze lignes. Pas de matrice. Pas de phases. Les extensions, après, en dessous. » La mesure tient sa première semaine. Je dirai dans le prochain épisode si elle tient le mois.

Pourquoi j'ai cessé de lire mon propre backlog.md (et ce que je lis à la place)

Michel Faure — Thu, 16 Jul 2026 16:46:57 +0000

Le matin où mon propre fichier m'a menti

Mercredi 21 mai, début de session, café à côté du clavier. Je demande à l'agent où on en est sur la série DEV.to. Réponse propre, articulée, « Quatre articles en stand-by, prêts à publier. » Je relis. Une demi-seconde de gêne, parce qu'il me semble que j'en ai vu passer deux ou trois sur DEV.to la semaine dernière, mais j'ai dormi entre-temps et je n'en suis plus très sûr. Je tape la question qui change tout, « Tu es sûr que des articles restent à publier ? » L'agent ré-interroge l'API DEV.to en parallèle, ouvre scripts/devto/state.json, croise les deux. Les quatre articles sont publiés depuis deux ou trois jours.

Ce que je viens de lire, ce n'était pas une hallucination. L'agent avait fait exactement ce qu'on attendait de lui, c'est-à-dire ouvrir articles/backlog.md, lire la table, restituer ce qu'elle disait. C'est moi qui avais cessé de mettre ce fichier à jour. sync-backlog.ts n'avait pas tourné après les push de la semaine. Le markdown disait « en stand-by » pendant que la prod disait « published ». La dactylo n'a pas menti. Elle a lu fidèlement un fichier que j'avais écrit moi-même et que je traitais en autorité alors que rien ne le maintenait.

Un summary est un Cache sans rafraîchisseur

C'est le mode de défaillance le plus commun d'un projet solo qui dure. Chaque jour produit deux flux. D'un côté la matière qui bouge, faite de commits, de déploiements, de lignes en base, de statuts qui transitent. De l'autre les écritures qu'on rédige pour s'y retrouver, à savoir backlog.md, le MEMORY.md à la racine, la note de session du dimanche soir, le README du dossier qu'on a refactoré la semaine d'avant. Ces écritures sont produites vite, dans le geste qui termine un sprint, et elles sont maintenues lentement, ou pas du tout, parce que rien dans le pipeline ne se déclenche pour les refermer.

R6 du Counterpart Toolkit le dit pour les colonnes SQL, Live / Snapshot / Cache mandatory. Toute colonne dérivable d'autres données doit déclarer sa catégorie dans le commit qui la crée. Si c'est un Cache, le mécanisme de rafraîchissement (GENERATED ALWAYS AS, trigger SQL, vue matérialisée avec REFRESH planifié) est livré dans le même commit. Pas de catégorie déclarée, pas de commit.

backlog.md est exactement le même objet logique. Sa valeur est dérivable de state.json plus quelques constantes éditoriales. sync-backlog.ts est son trigger applicatif. Sans appel, le Cache se décale.

Ce que je lis à la place

R2, Filesystem over summary, codifie le geste depuis le 15 mai. Avant tout rapport de statut, quatre commandes shell, dans cet ordre. Le markdown vient en dernier, et il vient comme un brouillon de pensée, jamais comme une source.

git log --since='7d' --oneline
git status --porcelain
ls docs/adr/ | wc -l
cat scripts/devto/state.json | jq 'to_entries|map(select(.value.published))|length'

Le résultat se lit en trois secondes. Si quelque chose me surprend, qu'il s'agisse d'un commit que j'avais oublié ou d'un ADR de plus que ma mémoire prévoyait, je creuse là, pas dans backlog.md. Quand je lis le markdown, je le lis avec la question implicite « qui l'a mis à jour, quand », et si la réponse ne sort pas du git log en quinze secondes, je le traite comme du Cache pourri.

Coda

Un sommaire qui ne dit pas quand il a été produit, et par quel mécanisme, ne dit rien. Soit on déclare son rafraîchisseur dans le commit qui le crée, qu'il s'agisse d'un script, d'un trigger ou d'un cron, et alors il vit comme un Cache géré, soit on cesse de le traiter comme une source et il redevient un brouillon. R6 dit la règle pour la base de données. R2 dit la même règle pour les écritures qu'on s'adresse à soi-même. Un agent qui ouvre backlog.md avant git log n'est pas un mauvais agent, c'est un agent qui exécute fidèlement un geste humain qu'il aurait fallu interdire en amont. Le matin du 21 mai, ce n'est pas l'agent qui m'a menti, c'est ma propre dactylo qui, la veille au soir, n'avait pas refermé la note.

Counterpart Toolkit v0.7, règle R2 — Filesystem over summary. Extraite de R1 dans la v0.4.1, promue à part entière. La version courante du toolkit vit en CC-BY-4.0 sur github.com/michelfaure/doctrine-counterpart.

Ce que 74 ADR en 70 jours achètent vraiment à un dev solo (pas d'embauche, pas de client, juste le fichier)

Michel Faure — Thu, 16 Jul 2026 16:46:16 +0000

La question qu'on n'ose pas poser à voix haute

Il est 22 h 40 un mardi soir, je viens de fermer un ADR — le soixante-quatorzième de ce dispositif, écrit consciencieusement, daté, croisé avec sa migration, son test de contrat et le commit qui l'a déclenché. Et la question monte, comme elle monte toujours à cette heure-là quand on code seul depuis dix heures : pour qui je viens d'écrire ça. Pas de chef tech à convaincre, pas de PR review qui va l'attraper, pas de repreneur hypothétique à rassurer, pas de comité d'archi à briefer le lendemain. Juste le fichier, juste moi, juste le doute.

C'est la question d'un dev solo à 70 jours de pratique sérieuse. Elle a une réponse honnête, et cette réponse n'est ni « ça paiera quand tu vendras » ni « ça paiera quand tu embaucheras ». Ces deux ROIs-là appartiennent à d'autres trajectoires. Le ROI du dev solo qui documente, c'est un ROI qu'il s'achète à lui-même — différé, intangible par moments, mais matériellement chiffrable si on s'oblige à le mesurer en première personne. Voici la mienne, sur 74 ADR et 18 règles de doctrine accumulés en 70 jours, sans aucun observateur extérieur pour valider la grille.

La fausse économie du « je m'en souviens »

Premier piège, celui qui m'a coûté trois semaines avant que je n'en tire la leçon. Le dev solo croit qu'il n'a pas besoin d'écrire ce qu'il a décidé parce qu'il l'a décidé lui-même — sa mémoire vaut bien un ADR. C'est faux à 14 jours, et c'est systématiquement faux à six semaines. Pas parce que la mémoire générale fait défaut, mais parce que la mémoire technique a une forme particulière qui trompe : on se souvient parfaitement qu'on a tranché, on ne se souvient plus pourquoi on a tranché ainsi.

Trois semaines après la session du 5 mai où j'ai écrit l'ADR-0051 (FK ON DELETE SET NULL + CHECK NOT NULL incompatibles, DELETE qui échoue silencieusement), je rouvre la migration concernée pour ajouter une colonne. Je relis le diff, je ne comprends pas pourquoi telle CHECK constraint est formulée comme ça — l'alternative que j'écarte mentalement aujourd'hui me paraît plus simple, et je suis à deux doigts de refactor. Je vais voir l'ADR. La réponse y est, datée, sourcée, en trois lignes. L'alternative simple est exactement celle que j'avais explorée et abandonnée à cause d'un cas limite que j'ai oublié depuis. Sans l'ADR, je l'aurais refait. Probablement deux heures de re-décision, plus l'incident silencieux que mon code allait re-produire dans six mois.

L'ADR n'est pas un livrable d'audit. C'est une note à soi-même qu'on s'envoie en différé. Le bénéficiaire est dans la même chaise, juste à un autre moment du temps.

Le ROI mesurable en première personne

Sur 70 jours, je peux chiffrer trois choses.

Temps de re-décision épargné. Quinze fois environ, je suis retourné consulter un ADR au lieu de retrancher. À chaque fois, vingt à quarante minutes économisées sur le diff cognitif d'une rediscussion silencieuse avec moi-même — celle où on relit le code, on imagine les alternatives, on se demande si on n'avait pas pris la mauvaise option. L'ADR coupe court : la mauvaise option a déjà été examinée, voici pourquoi elle perd, on passe. Vingt minutes × quinze ≈ cinq heures récupérées sur 70 jours. Pas du temps facturable au sens où un consultant le mesurerait — du temps que je n'ai pas passé à douter, et que j'ai passé à livrer.

Cycles fix-rollback évités. Le protocole falsify before fix — formuler une hypothèse causale puis exécuter trois sondes conçues pour la réfuter — m'a évité, sur la même période, sept cycles fix-puis-rollback bien identifiés (les sessions où le terme apparaît explicitement, comptage conservateur). Chacun de ces cycles, c'est cinq à dix minutes de protocole en amont contre trente à quatre-vingt-dix minutes de fix qui ne fixe pas, suivi du rollback et du recommencement. Le ratio se calcule sans optimisme : six à dix-huit fois le temps investi, par incident où le protocole a tenu. Sur un dev solo, ce n'est pas une économie de productivité au sens où on l'entend en équipe — c'est une économie de moral, qui n'est pas refacturable mais qui décide si je code encore à 18 h ou si j'ai déjà arrêté en silence à 16 h sans le dire à personne.

Dérives silencieuses détectées. Le pattern un cas confirmé, grep le pattern complet — chaque fois qu'un bug remonte sur un cas précis, élargir avant de fixer — m'a fait passer plusieurs fois d'un signalement isolé à un audit qui a remonté quatre, seize, parfois cinq cents lignes affectées par la même cause racine. Ce n'est pas l'ADR qui exécute le grep, mais c'est la doctrine qui pose le réflexe et l'ADR qui le code pour que mon moi-de-dans-trois-semaines ne l'oublie pas. La vraie mesure de ROI, ce n'est pas le nombre de cas trouvés, c'est le ratio entre ce que j'aurais vu sans la règle (un cas, le visible) et ce que j'ai vu avec (la classe entière, l'invisible).

Ce que ça ne paie pas

Honnêteté brutale. La discipline ADR ne paie pas la vitesse de prototypage — quand je veux essayer une idée folle un samedi matin, je n'écris pas d'ADR, j'écris du code marqué [spike] qui sera supprimé sous sept jours, et je m'en porte mieux. Elle ne paie pas le doute existentiel — l'ADR confirme que j'ai bien tranché, il ne me dit pas si j'ai bien tranché à propos du bon problème, et c'est une question d'un autre ordre que la doctrine ne touche pas. Elle ne paie pas le marketing, ne paie pas la cohésion d'équipe (je n'ai pas d'équipe), ne paie pas la prospection commerciale.

Le piège que je vois aussi, et que je signale parce qu'il me concerne directement, c'est celui du dev solo qui se met à documenter parce que documenter rassure, et qui finit par documenter au lieu de livrer. La doctrine devient un terrier. À 70 jours, je tiens le ratio — un ADR pour ce qui est décidé et durable, pas pour ce qui est exploré. Mon ratio actuel tourne à 1,7 ADR par session active, et c'est précisément le seuil où je commence à me regarder de travers. Au-dessus de deux par session, je serais probablement en train de me cacher du code derrière la doctrine. C'est un signal d'alerte que personne d'autre ne peut me donner.

Le ROI invisible

Reste l'axe qu'aucun observateur externe ne saurait coder en métrique, et c'est probablement celui qui pèse le plus pour qui pratique le solo.

La confiance dans son propre système. Pouvoir rouvrir un module qu'on n'a pas touché depuis six semaines, lire les trois ADR qui le décrivent, et reprendre la modification sans avoir à tout relire ligne à ligne. Le calme cognitif d'un système qui ne demande pas de re-comprendre, qui te tend ses raisons et te laisse continuer. C'est ce dont un fondateur solo a besoin pour ne pas craquer au mois 4 — pas une métrique de productivité, une métrique de tenue dans le temps. Personne ne me l'a vendu en début de parcours parce que personne ne la vend ; on la découvre rétrospectivement, quand on s'aperçoit qu'on n'a pas paniqué une seule fois ce mois-ci, et qu'on se demande pourquoi.

C'est probablement la seule réponse honnête à la question de 22 h 40. L'ADR ne paiera ni l'embauche, ni le client, ni la valorisation. Il paiera ma capacité à continuer à coder ce système dans trois mois sans le détester. C'est un ROI qu'aucun investisseur ne valorisera, et qui est néanmoins le seul qui me concerne.

Coda

Si tu hésites à écrire le tien parce que tu te dis que personne ne va le lire, écris-le quand même. Le lecteur, c'est toi dans trois semaines. Il en aura besoin. C'est exactement ça, et ce n'est rien d'autre.

Dev solo, 74 ADR en 70 jours, pas d'équipe, pas de PR review. Le bilan honnête — mesuré depuis la seule chaise qui compte : la mienne.

When `await mutation()` lies: the `{ error }` destructuring that saves your weekend

Michel Faure — Tue, 14 Jul 2026 10:43:19 +0000

Episode 2/4 of the mini-series The week Supabase lied to me 4 times. Episode 1 — 3 Supabase security incidents, one shared root cause: SECURITY DEFINER inherits EXECUTE TO PUBLIC — covered SaaS defaults that lie by misplaced trust. Episode 3 [CANONICAL URL EPISODE 3: to complete after push] will look at RLS recursion. Episode 4 [CANONICAL URL EPISODE 4: to complete after push] will explain the silent 1000-row cap.

Wednesday of the week Supabase was lying

Monday was episode 1 — a SECURITY DEFINER function callable by anon because Postgres had silently added EXECUTE TO PUBLIC that nobody wrote. Tuesday I was drafting episode 3 on the RLS recursion that returns zero without saying why. Wednesday morning, Pauline walked in with a spreadsheet and a quiet smile.

She put her screen down in front of me — no noise, no preamble. Twenty rows, column A name, column B status, column C supposed archival date. "I found them all this morning, still active in the CRM." She said it with the politeness of someone who already knows it's a code problem, not a spreadsheet problem. Then she waited.

Twenty contacts archived the evening before. Green toast, "Archiving successful", team message sent to confirm. Pauline's spreadsheet found them all the next morning, still active, still visible in the CRM. No error in the logs. No Sentry alert. Not a single red line anywhere. Twenty silent rows saying simply no, the operation never happened — with nobody listening.

This is episode two of a week when Supabase lied to me four times. Episode one said SaaS defaults lie through misplaced trust. Episode two says something different and the same thing: an API return value lies when the caller refuses to open the envelope.

The contract nobody talks about

@supabase/supabase-js made a defensible choice long ago: don't throw exceptions on DB errors. A rejected mutation — from a CHECK constraint, an RLS policy, a trigger that says no — doesn't crash the caller. It returns cleanly with a { data, error } object where data is null and error carries the message. Return-value-error convention, borrowed from Go, defensible in isolation.

Formidable consequence. A caller that doesn't destructure error doesn't have the error. Not hidden by a badly-written try / catch, not swallowed by a distracted .then(). Simply: nobody claimed it, so nobody saw it. The contract holds when both parties honor it; it collapses the moment one party looks away.

The doctrine I maintain in ~/doctrine-counterpart/CLAUDE.md calls this R10, Silent failure forbidden. The most dangerous lie in a system isn't the one that shouts a falsehood, it's the one that stays quiet about a failure. Silence is a readable state — you just need a device that reads it.

The code that lied

I open the archiving module. Twenty lines on the server action side, and this one at the center:

// app/crm/actions.ts — contact archiving (before fix)
async function archiveContact(id: string) {
  const supabase = createSupabaseServer()
  const now = new Date().toISOString()

  await supabase
    .from('contacts')
    .update({ statut: 'ancien', archived_at: now })
    .eq('id', id)
  // no destructure, no check, no throw

  return { ok: true }
}

The return { ok: true } was written two lines below, like a declaration of confidence nothing supported. And the RLS policy, written a few weeks earlier, didn't include UPDATE on contacts for Pauline's role. The Postgres server did its job: it rejected the mutation, returned the error, and moved on to the next query. Nobody read the envelope. The green toast appeared.

This isn't a bug. It's a contract the caller didn't honor. And an unmet contract is rigorously indistinguishable from a met one when nobody's looking — that's precisely what makes it a structural lie, not a one-off defect.

Why ESLint isn't enough

I wrote an ESLint rule the week before, no-bare-await-on-supabase-mutation, that cleanly catches the orphaned await supabase.from(...).delete().eq(...) at end of statement. The rule eliminated 56 occurrences across the repo. But it lets through a more insidious variant:

// passes the linter, still lies
const { data } = await supabase
  .from('contacts')
  .update({ statut: 'ancien', archived_at: now })
  .eq('id', id)
if (!data) toast.error('Error')   // data null if row missing OR if error is set

The destructure is there — data is read — but error isn't. The !data test conflates two distinct cases: the row didn't exist and the policy refused. One is business logic, the other is security, and both surface here as a single generic "error". For Pauline, error is a hollow word that says neither what to fix nor who to ask for permission.

A linter fixes what grammar lets through. But when grammar is legal and it's usage that lies, the linter misses it. You need a device higher in the stack.

The wrapper that enforces destructuring

The fix I put in place is a single layer. A typed mutate() helper that makes error non-optional in its return signature, forcing TypeScript to refuse compilation if the caller ignores the field.

// lib/supabase-mutate.ts
import type { PostgrestBuilder } from '@supabase/postgrest-js'
import type { PostgrestError } from '@supabase/supabase-js'
import * as Sentry from '@sentry/nextjs'

export async function mutate<T>(
  query: PostgrestBuilder<T>
): Promise<{ data: T | null; error: PostgrestError | null }> {
  const result = await query
  if (result.error) {
    Sentry.addBreadcrumb({
      category: 'supabase.mutation',
      message: result.error.message,
      data: { code: result.error.code, details: result.error.details },
      level: 'error',
    })
  }
  return result
}

// Usage — won't compile if caller omits `error`
const { data, error } = await mutate(
  supabase.from('contacts').update({ statut: 'ancien' }).eq('id', id)
)
if (error) throw new Error(error.message)

TypeScript does its job. And when error is non-null, Sentry gets a breadcrumb immediately with the PG code and details — before the caller even decides what to do. I see the remaining violations roll through review the next morning. The lie is no longer possible: it's either forbidden by the compiler or observed by instrumentation. I prefer both.

The cost? An indirection layer on all mutations, meaning a new dev joining the project who writes await supabase.from(...).update(...) doesn't compile. Productive friction. Whatever you think of the verbosity, it beats a lying green toast.

What Supabase didn't invent

The problem isn't specific to Supabase, and that matters for anyone coding in other ecosystems. The return-value-error trap swallows silently in fetch().ok that you forget to test before reading response.json(), in child_process.spawn that returns a non-zero exit code without throwing, in certain Stripe SDK versions where the difference between a network error and a response error lives in a field you have to go find. Supabase is the showcase for a wider contract.

The rule to draw out goes beyond Supabase and fits in one sentence. A return that can carry an error without raising it is a lie for as long as no material mechanism forces the caller to read it. Discipline alone isn't enough; linter rules alone aren't enough; typing that makes the field non-optional, coupled with instrumentation that catches workarounds, finally holds.

Coda

A return-value-error with no reader isn't an error, it's a rumor. Wednesday evening, I pushed the wrapper, re-archived Pauline's twenty contacts in an operation that this time properly raised two exceptions on misconfigured roles. The toast appeared red. Pauline sighed — economically — and fixed the permissions in two clicks. The rumor had become information.

Thursday — episode three [CANONICAL URL EPISODE 3: to complete after push] — another form of the same lie. An RLS policy that returns zero rows without saying why, and what I ended up putting in place of my policies after a full day of debugging.

Episode 2 of the mini-series "The week Supabase lied to me 4 times". The typed mutate() wrapper, pseudonymized: github.com/michelfaure/rembrandt-samples/tree/main/supabase-mutate-typed-wrapper

La requête PostgREST qui trie en silence par `ctid` : une semaine Supabase, distillée

Michel Faure — Mon, 13 Jul 2026 07:32:37 +0000

Le quatrième appel de la semaine

Catherine appelle de Maisons-Laffitte un mardi de début mai, en milieu d'après-midi. "Ça bug, mais c'est vite corrigé." C'est sa formule, je la connais, et d'habitude elle dit vrai. Elle décrit la chose en trois phrases : l'export newsletter du segment inscrits revient avec quatre-vingt-douze noms, le planning affiche quatre-vingt-douze cours actifs, mais la page compteur en affiche quatre-vingt-neuf. Trois inscrits absents. Elle a vérifié dans la base directement, ils sont bien là. "Pourquoi trois étapes pour ça ?" Elle ne pose pas la question pour moi, elle la pose pour elle. Sauf que cette fois, je m'aperçois en raccrochant que c'est la quatrième fois de la semaine que je raccroche en pensant la même chose. Quatre incidents Supabase, quatre fixes, quatre tickets refermés. Et pas une seule exception levée par la base.

Je rouvre les trois précédents en parallèle et je pose les quatre côte à côte sur l'écran. Ce n'est pas quatre bugs. C'est un seul mode d'échec, décliné quatre fois.

Les trois premiers

L'épisode 1 portait sur les GRANT par défaut que Supabase pose sur les fonctions et les policies. Une fonction SQL créée sans REVOKE explicite hérite d'un accès anon que personne n'a écrit dans la migration, et que personne n'a vu en review parce que le diff ne le montre pas. La fonction marche. Elle est juste exécutable depuis l'extérieur. [CANONICAL URL EPISODE 1: à renseigner après publication de #48 — "3 incidents Supabase, une seule racine : SECURITY DEFINER hérite de EXECUTE TO PUBLIC"]

L'épisode 2, une cascade ON DELETE SET NULL couplée à une CHECK NOT NULL sur la colonne cible. Le DELETE parent tente le SET NULL, la CHECK rejette, et la transaction remonte une erreur qu'on lit comme un échec de suppression alors qu'elle masque une cohérence qu'on croyait acquise depuis trois mois. La requête échoue franchement, ce qui est plus charitable que les trois autres cas, mais le diagnostic part dans la mauvaise direction parce que personne n'a déclaré que les deux contraintes vivaient en tension. [CANONICAL URL EPISODE 2: à renseigner après publication de #49 — "Quand await mutation() ment : le destructure { error } qui sauve ton week-end"]

L'épisode 3, la récursion RLS quand auth.users consulte user_roles qui consulte auth.users. La première requête vivante après le déploiement de la policy effondre la session. La logique est correcte sur le papier. C'est l'évaluation côté Postgres qui ne peut pas terminer. [CANONICAL URL EPISODE 3: à renseigner après publication de #50 — "RLS recursion infinite loop: why I gave up policies and bet everything on a JWT custom claims hook"]

Et le quatrième, qu'on connaît déjà

Le quatrième, j'en ai déjà fait le récit isolé, la nuit du dropdown qui mentait, le compteur figé à mille pile sur une table qui en porte mille deux cent trois, le .select() chaîné sur .from() sans .order(), le Range HTTP qui plafonne à mille et le ctid qui sert d'ordre de fallback. [CANONICAL URL #40: https://dev.to/michelfaure/why-your-supabase-query-stops-at-exactly-1000-rows-and-never-tells-you-4g57] Je ne réexpose pas ici la mécanique ni la rule ESLint qui finit par la fermer. Ce qui m'intéresse, en posant les quatre cas en regard, c'est que ce quatrième cas n'est pas une anomalie de plus. C'est le portrait le plus pur d'une famille à laquelle appartiennent aussi les trois autres.

Le profil commun

Quatre fois, le même geste de la base. Elle reçoit une requête, elle l'exécute, elle ne lève rien. Pas d'exception remontée jusqu'au client, pas de warning, pas de trace dans Sentry, pas de log applicatif. Le code de retour est 200. Le payload arrive. Et il ment d'une manière différente à chaque fois, payload incomplet pour le ctid, payload accessible pour le GRANT, payload mal cascadé pour la CHECK NOT NULL, payload absent pour la récursion RLS quand la requête termine en timeout silencieux côté infra.

Le test unitaire passe, parce qu'il porte sur cinquante lignes seedées localement. La revue de code passe, parce que la chaîne incriminée tient en une seule ligne lisible. La prod craque, parce que la prod a mille deux cents lignes, des utilisateurs anonymes qui appellent des endpoints qu'on croyait privés, et des policies qui font le tour d'une dépendance que le développeur n'a pas dessinée.

J'ai longtemps lu ces quatre cas comme quatre paragraphes du manuel Supabase qu'on n'avait pas lus assez. Je crois maintenant que c'est plus structurel. Un default vendor n'est pas un paragraphe à lire, c'est une décision de design implicite que le client de la plateforme adopte sans la voir, parce qu'elle n'apparaît nulle part dans son code à lui. Le Range à mille, l'accès anon par défaut, la récursion permise sur une auth-policy, le comportement d'un ON DELETE SET NULL face à une CHECK, autant de micro-contrats que personne n'a écrits dans le repo et qui tiennent pourtant la prod.

Trois règles pour fermer la porte

Quatre incidents en une semaine, ce n'est pas une statistique, c'est une convergence qui demande sa doctrine. Je laisse de côté l'idée d'écrire plus de tests, puisque aucun de ces quatre cas n'aurait été pris par un test unitaire, et que l'intégration n'aurait sauvé que le deuxième, à condition d'avoir le cas exact en fixture. Je préfère trois règles matérielles.

Première règle, tout default vendor non déclaré est un Snapshot implicite, à matérialiser au commit ou à interdire. Snapshot au sens de notre nomenclature interne, soit une valeur figée qu'aucun mécanisme ne rafraîchit. Quand la plateforme pose un comportement par défaut que mon code n'écrit pas, c'est une copie figée du contrat plateforme posée dans mon repo à mon insu. Le jour où Supabase modifie son max_rows, ou affine sa politique anon, je découvrirai le drift en prod. Donc soit le default est cité textuellement dans une règle CLAUDE.md ou un ADR et son comportement attendu est asserté, soit la pratique qui en dépend est interdite par un garde-fou matériel, rule ESLint, CHECK SQL, hook pre-commit. Pas de tiède.

Deuxième règle, la rule ESLint vaut mieux que la review de code dès que le pattern se chiffre en dizaines d'occurrences. Une chaîne .from().select() sans .order() se cache dans des centaines de fichiers. La review de code humaine ne peut pas tenir contre ce volume, elle attrapera deux occurrences sur dix, pas plus. Une rule AST, en revanche, balaye le repo en une passe, et c'est elle qui dit non à la PR suivante, mécaniquement, sans qu'un humain ait besoin de relire la diff à la loupe. Le coût initial est dans les garde-fous structurels qu'il faut prévoir pour ne pas crouler sous le faux positif. Je l'ai mesuré sur le cas ctid, et cinq mécanismes anti-bruit ont ramené la rule de cent soixante-dix-huit alertes brutes à cent huit cibles réelles, sans quoi elle aurait été désactivée par lassitude en moins d'une semaine.

Troisième règle, l'instrumentation doit sortir de prod, pas du test. Aucun de ces quatre defaults ne dépend de la logique du code, ils dépendent tous du volume, du contexte d'auth, de la fréquence d'appel ou de l'historique de la table. Le test unitaire ne les voit jamais. Donc le filet, c'est une sonde quotidienne sur la prod, qui mesure ce que la prod fait réellement et qui hurle quand un compteur ressemble suspectement à un plafond. Pourquoi exactement mille ? Pourquoi exactement zéro accès refusé sur un endpoint sensible ? Pourquoi cette policy n'a-t-elle jamais consommé de CPU ? Ce sont les questions qu'aucun test ne pose mais qu'une sonde drift quotidienne peut poser à la base elle-même.

Une quatrième règle, si l'on veut

Et si l'on veut un dernier coin tranchant, je le placerais là, ne jamais lire un default vendor depuis l'agent IA, le lire depuis la doc officielle et le matérialiser dans le repo. Quand on demande à un agent ce que fait Supabase quand on ne déclare pas .order(), il répondra plausiblement, et il y a une chance non nulle qu'il se trompe sur la valeur du cap, sur la version où le comportement a changé, ou sur l'ordre de fallback. Le matériel, c'est la doc, et le test grandeur nature, c'est une migration locale qu'on inspecte sur dix mille lignes seedées. L'agent peut écrire la sonde, il ne peut pas s'auto-attester. C'est exactement la posture qu'impose la doctrine que j'ai publiée ailleurs, citer le texte officiel et matérialiser les defaults vendor.

Coda

Quatre incidents en une semaine, un même mode d'échec. La base ne ment pas par malice, elle exécute des contrats que personne n'a explicitement signés dans mon repo et que mon test unitaire ne peut pas reproduire parce qu'il ne porte pas sur ces dimensions-là. La défense, ce n'est pas plus de vigilance, je vois assez nettement maintenant que la vigilance humaine se fausse contre quatre defaults invisibles cumulés. C'est plus de garde-fous matériels, posés une fois, qui interdisent à la classe entière d'incidents de revenir. Une rule ESLint, une CHECK constraint, une sonde drift, un ADR qui cite le default vendor, chacun de ces dispositifs vaut un mardi après-midi tranquille en plus dans la semaine. Quand Catherine rappellera, ce sera pour une cinquième raison, et celle-là, je préfère ne pas la connaître à l'avance.

Quatre épisodes Supabase, une mini-série. La rule ESLint complète et le helper fetchAll pseudonymisés vivent dans :
github.com/michelfaure/rembrandt-samples/tree/main/postgrest-row-cap

Cette typologie des defaults vendor silencieux est le cœur de R12 du Counterpart Toolkit (« cite the official text, materialise vendor defaults »). 14 règles, install en 1 commande : github.com/michelfaure/doctrine-counterpart

3 incidents Supabase, une seule racine : SECURITY DEFINER hérite de EXECUTE TO PUBLIC

Michel Faure — Mon, 13 Jul 2026 07:31:54 +0000

Épisode 1/4 de la mini-série La semaine où Supabase m'a menti 4 fois. Les trois épisodes suivants traitent d'une mutation silencieusement avalée par le SDK [CANONICAL URL EPISODE 2: à compléter après push], d'une récursion RLS contournée par un JWT hook [CANONICAL URL EPISODE 3: à compléter après push], et d'une requête qui s'arrête pile à 1000 lignes sans le dire [CANONICAL URL EPISODE 4: à compléter après push].

Le mardi où la sonde sécurité a parlé

C'est 9h12, un mardi de mai. La sonde drift quotidienne tourne automatiquement depuis trois semaines — une requête aclexplode sur l'ensemble des objets publics, filtrée sur anon. Je ne l'ouvre pas tous les matins. Ce matin-là, elle m'attend avec une ligne qui n'a pas à exister.

Niran pose un café sur le coin du bureau sans rien dire. Il lit la sortie par-dessus mon épaule. Une table de backup PII — données personnelles en clair, créée deux jours plus tôt pour un reclassement bulk — apparaît dans la liste avec SELECT, INSERT, UPDATE, DELETE accordés à anon. Accessible à n'importe quelle requête curl sans clé. Il laisse passer trois secondes et dit : « C'est pas RLS. » Puis il retourne à son hoodie.

Il a raison. Ce n'est pas un bug RLS. C'est la table elle-même qui est ouverte, au niveau GRANT, avant que RLS s'applique.

Trois objets, trois portes, un mécanisme

Cette semaine-là, je comprends que je n'ai pas affaire à un incident isolé. Trois objets distincts, dans trois migrations différentes, ouvrent chacun une porte que personne ne pensait avoir ouverte. La table de backup d'abord. Puis une policy posée TO public parce que la landing publique en a besoin, qui laisse passer un POST {} en anon avec une réponse HTTP 400 NOT NULL au lieu d'un 401 Unauthorized. Et enfin quatre fonctions SECURITY DEFINER écrites pour exécuter des opérations transactionnelles avec les droits de leur owner, toutes invocables par anon parce que EXECUTE est TO PUBLIC par défaut au moment du CREATE.

Trois objets, trois mécanismes superficiellement distincts, et pourtant une seule racine. À chaque CREATE, Postgres complète la migration avec un GRANT implicite que le rédacteur n'a pas écrit. Le rédacteur croit lire ce qu'il a tapé. Postgres lit ce que le langage a ajouté.

Le premier piège, `CREATE TABLE AS SELECT`

Le cas archétypal est aussi le plus innocent en apparence. Le rédacteur veut figer un état d'une table de contacts avant un reclassement bulk, par pure prudence, archive à 48h destinée à disparaître une fois la migration validée.

-- supabase/migrations/20260511182000_snapshot_liste_rouge_pre_reclassement.sql
CREATE TABLE IF NOT EXISTS public.contacts_backup_pre_reclassement AS
SELECT id, nom, prenom, email, source, statut, notes, created_at
FROM public.contacts
WHERE statut = 'liste_rouge';

-- (la migration s'arrête là — aucun REVOKE, aucun bloc GRANT restreint)

Ce que le rédacteur croit avoir écrit, c'est une copie de sécurité, neutre, accessible uniquement aux admins. Ce que Postgres a effectivement écrit, c'est une table sans RLS active dont les GRANT par défaut donnent à anon les droits SELECT, INSERT, UPDATE et DELETE. Une requête curl sur l'endpoint PostgREST suffit à lister les lignes, sans authentification, en clair.

La parade est connue, mais elle exige qu'on l'écrive. Le correctif du 13 mai tient en quatre lignes :

-- supabase/migrations/20260513140000_security_revoke_anon_contacts_liste_rouge_archive.sql
BEGIN;
  REVOKE ALL ON public.contacts_backup_pre_reclassement FROM anon;
  REVOKE ALL ON public.contacts_backup_pre_reclassement FROM authenticated;
  ALTER TABLE public.contacts_backup_pre_reclassement ENABLE ROW LEVEL SECURITY;
  GRANT SELECT ON public.contacts_backup_pre_reclassement TO authenticated;
  CREATE POLICY "archive_admin_read"
    ON public.contacts_backup_pre_reclassement FOR SELECT TO authenticated
    USING (EXISTS (
      SELECT 1 FROM public.user_roles ur
      WHERE ur.email = auth.email() AND ur.role IN ('super_admin', 'admin')
    ));
COMMIT;

La forme est ingrate, répétitive, et c'est précisément pour cette raison qu'elle est sûre : elle inscrit l'invariant dans la base au lieu de le laisser flotter dans la tête du rédacteur.

Le deuxième piège, `CREATE POLICY ... TO public`

Le deuxième incident est plus subtil parce que le rédacteur, lui, a écrit du gating. Il a posé une POLICY avec un qual censé filtrer les insertions selon un contexte de service. Mais il a posé la policy TO public, parce que la landing est ouverte au navigateur anonyme. Le piège est que la couche GRANT se résout avant la couche qual. Si le GRANT INSERT TO anon existe par défaut sur la table, un POST {} en anon arrive jusqu'au moteur de table, et c'est seulement la contrainte NOT NULL au niveau colonne qui le rejette, par accident.

-- supabase/migrations/20260513140100_security_revoke_anon_stripe_payments.sql
BEGIN;
  REVOKE INSERT, UPDATE, DELETE ON public.stripe_payments FROM anon;
  REVOKE SELECT ON public.stripe_payments FROM anon;
  DROP POLICY IF EXISTS stripe_payments_service_insert ON public.stripe_payments;
COMMIT;
-- Note : stripe_payments est écrit exclusivement par le webhook Stripe
-- via service_role — aucun usage anon légitime ne justifie ce GRANT.

Le symptôme observable est ce qu'on pourrait appeler une réponse trop précise. Quand le système répond HTTP 400 NOT NULL, il dit en clair qu'il a essayé d'insérer, ce qu'il aurait dû refuser au seuil. La bonne réponse à un POST {} en anon sur une table protégée serait 401 Unauthorized. Lire 400 dans un log, c'est lire en réalité que la couche d'autorisation a laissé passer.

Le troisième piège, racine partagée, `SECURITY DEFINER` hérite de `EXECUTE TO PUBLIC`

C'est ici que le mécanisme devient pédagogique. Une fonction SECURITY DEFINER, par définition, s'exécute avec les droits de son owner, pas du caller. Si l'owner est postgres, la fonction bypasse RLS, et c'est précisément pour cela qu'on l'a marquée SECURITY DEFINER. Mais Postgres, au moment du CREATE FUNCTION, ajoute par défaut GRANT EXECUTE TO PUBLIC. La fonction est donc invocable par n'importe qui, y compris anon, et son exécution se fait avec les droits de l'owner, donc avec bypass RLS implicite.

-- supabase/migrations/20260512094000_supprimer_brouillon_tx_rpc.sql
-- AVANT correctif : invocable par anon, exécutée avec droits postgres
CREATE OR REPLACE FUNCTION public.supprimer_brouillon_tx(p_planning_id uuid)
RETURNS jsonb
LANGUAGE plpgsql
SECURITY DEFINER
SET search_path TO ''
AS $function$
BEGIN
  -- opération sensible : suppression atomique d'un brouillon de planning
  -- seances_cours → cours → plannings dans la même transaction
  DELETE FROM public.seances_cours WHERE cours_id IN (
    SELECT id FROM public.cours WHERE planning_id = p_planning_id
  );
  DELETE FROM public.cours WHERE planning_id = p_planning_id;
  DELETE FROM public.plannings WHERE id = p_planning_id;
  RETURN jsonb_build_object('ok', true);
END;
$function$;

L'audit du 13 mai remonte 86 occurrences de SECURITY DEFINER dans le répertoire des migrations. Parmi elles, 4 RPC n'avaient aucune restriction sur anon : supprimer_brouillon_tx, convertir_sd_tx (crée une inscription), mark_outbox_sent_tx, mark_outbox_error_tx. La parade est immédiate :

-- supabase/migrations/20260513140200_security_revoke_anon_execute_rpc_security_definer.sql
REVOKE EXECUTE ON FUNCTION public.supprimer_brouillon_tx(uuid) FROM anon, public;
REVOKE EXECUTE ON FUNCTION public.convertir_sd_tx(uuid, uuid, date, text, date, numeric, integer, integer) FROM anon, public;
REVOKE EXECUTE ON FUNCTION public.mark_outbox_sent_tx(uuid, text, text) FROM anon, public;
REVOKE EXECUTE ON FUNCTION public.mark_outbox_error_tx(uuid, text) FROM anon, public;
-- resolve_reinscription_token conserve EXECUTE TO anon (landing public magic link légitim)

La signature exacte doit figurer, parce que sans elle le REVOKE échoue silencieusement si la fonction est surchargée.

L'audit qui rend les trois pièges visibles

Une fois qu'on a compris la racine commune, on peut tester sa propre base en quelques secondes. La requête ci-dessous retourne 0 lignes sur une base saine ; toute ligne renvoyée est un objet exposé à anon ou public.

-- Audit drift : objets exposés à anon ou public
-- À lancer sur une base Supabase saine → 0 lignes attendues
SELECT
  'table'          AS type_objet,
  relname          AS objet,
  privilege_type   AS privilege
FROM pg_class c
CROSS JOIN aclexplode(c.relacl) acl
WHERE c.relkind = 'r'
  AND c.relnamespace = 'public'::regnamespace
  AND acl.grantee IN (
    (SELECT oid FROM pg_roles WHERE rolname = 'anon'),
    (SELECT oid FROM pg_roles WHERE rolname = 'public')
  )

UNION ALL

SELECT
  'function'       AS type_objet,
  p.proname        AS objet,
  'EXECUTE'        AS privilege
FROM pg_proc p
CROSS JOIN aclexplode(p.proacl) acl
WHERE p.pronamespace = 'public'::regnamespace
  AND p.prosecdef = true
  AND acl.grantee IN (
    (SELECT oid FROM pg_roles WHERE rolname = 'anon'),
    (SELECT oid FROM pg_roles WHERE rolname = 'public')
  )
ORDER BY type_objet, objet;

Cette requête tourne en sonde drift quotidienne depuis le 13 mai. Sur les 86 fonctions SECURITY DEFINER scannées dans le schéma public, 4 étaient exposées à anon avant correctif. Zéro après.

Ce que l'épisode 1 nous apprend, et ce que les suivants nous montreront

La leçon tient en deux lignes. Les defaults Supabase ne sont pas neutres, ils ajoutent des GRANT que le rédacteur n'a pas écrits. Et toute migration termine par un bloc REVOKE explicite, ou elle ment sur ses invariants. Le mensonge n'est pas hostile, il est mécanique, puisque Postgres complète le geste lorsque le rédacteur croit avoir terminé.

Cette mini-série de quatre articles part du même soupçon, élargi à quatre couches du stack Supabase. L'épisode 2 [CANONICAL URL EPISODE 2: à compléter après push] regardera comment une mutation peut échouer sans qu'aucune erreur ne remonte côté applicatif. L'épisode 3 [CANONICAL URL EPISODE 3: à compléter après push] montrera comment une policy RLS qui s'auto-référence produit une récursion infinie résolue par un Custom Access Token Hook. L'épisode 4 [CANONICAL URL EPISODE 4: à compléter après push] expliquera pourquoi une requête from().select() sans order() retourne pile 1000 lignes sans le dire, à cause d'un ORDER BY ctid posé silencieusement par PostgREST.

Quatre mensonges, un même schéma : l'invariant que le développeur croit tenir n'est pas celui que le système exécute. La sécurité du solo qui code avec une IA tient peut-être précisément dans cette discipline d'écrire chaque invariant au lieu de le laisser tacite.

Épisode 1/4 de la mini-série La semaine où Supabase m'a menti 4 fois, dans la série « My ERP with Claude Code ». Les commentaires DEV.to remontent les pièges Supabase de votre stack que je n'ai pas vus, et nourrissent les épisodes suivants.

The Counterpart Doctrine: a seven-axis spec for working with an AI coding agent

Michel Faure — Fri, 10 Jul 2026 16:54:29 +0000

If you have 30 seconds. After 35 effective days, 109,000 lines, 22 ADRs and close to a hundred indexed feedback files, the discipline of working with an AI agent ended up naming itself. Seven axes, each born of a recurring failure mode. The doctrine wasn't planned, it settled. This article exposes them and gives, for each, the inaugural incident and the imperative rule that came out. None are specific to Claude Code, they hold for any long collaboration with a coding agent.

The doctrine wasn't planned

Friday April 24th, late afternoon. I reopen side by side the root CLAUDE.md, the ~/.claude/agent-memory/ folder and the docs/adr/ index. I reread the whole thing in one go. Niran is at the next desk, dark hoodie, white sneakers, a half-empty soda can near the keyboard; he reads a PDF of financial analyses in silence. Antoine pokes his head through the doorway to say goodbye before end of day. He retires in September and has gotten in the habit of stopping by in the evening "just to say hi". I answer with a nod, don't look up. I've just understood that the feedback files group into seven clusters. I write in the margin of the notebook, the doctrine wasn't planned, it settled.

This article enumerates those seven axes. Each was born of incidents recounted elsewhere in the series. Taken together, they form less a method than a frame, a frame whose usefulness lies in the fact that it constrains my exchanges with the agent and with myself. Without that naming, the same rule gets rediscovered every session. "Material verification" is a shortcut that saves ten minutes per session, over a month a working day. Cost of formalization low, benefit exponential as the project grows.

The seven axes

Axis 1 — Material verification

Any factual claim (green, passed, OK, missing, confirmed) comes with its proof in the same message; without material proof, zero evidentiary value. Every number relayed to a human paired with its SQL query. Every EXPLAIN ANALYZE on the exact query the application sends in production, not on the target table in isolation. On 400 or 422 from an external partner, raw payload demanded before any fix. Inaugural incident: four consecutive "Compiled successfully" with four real TypeScript errors behind them. Details in #36.

Axis 2 — Bidirectional adversariality

On any structurally significant decision (architecture choice, ADR to lock, refactor over ten files, irreversible DB migration, compliance commitment), I invoke a challenger agent that produces objections plus empirical test plus confidence score before locking the recommendation. The output "nothing to object" is valid, but it must be pronounced explicitly. As a corollary, never revise a recommendation on user pushback alone without a new fact. No new fact, it's complaisance; maintaining the first position is legitimate. On a drift diagnosis, ask "by what was this object created?" before any workaround.

Axis 3 — Data taxonomy and single source

Any stored derivable column must be categorized in the commit that creates it. Three categories. Live (don't store, create a v_* view), Snapshot (frozen at a business event, never recomputed), Cache (stored with refresher declared in the same commit, GENERATED ALWAYS AS, trg_* trigger, or mv_* matview). No declared category, migration refused. Business constants centralized in a constants.ts. Cash and accrual never mix in the same view. Irrevocable invariants protected at the DB level (CHECK, trigger), not just in TypeScript. Inaugural incident detailed in #8, a derivable amount entered by hand on 560 contact records.

Axis 4 — Session discipline

Before any project over two files, a one-page ADR (decision, alternatives discarded, consequences, references). ADR before the first commit, not after. Phase 0 on any non-trivial module, exhaustive grep of symbols before proposing new. Recap lots over five lines, to be split. FIFO on open projects, no more than three in parallel; opening a fourth means closing one. Manual trigger post-deploy for any new cron, observe the real digest before letting it take over. Before git push on multi-commit, ESLint plus dead-code grep plus build, raw output reported.

Axis 5 — Root cause, not patch

Before any fix, identify the root cause. A workaround is legitimate only if explicitly assumed in the commit AND in a feedback memory or ADR. Silent workaround forbidden. When a fix looks too simple for the observed symptom, demand the full input → output pipeline before accepting.

One confirmed case of a pattern, grep the full pattern in DB or code before acting: widen before correcting. Arbitrary cap in a comment (// limit = X) to be challenged, not accepted as fact, especially if dated less than 48 hours. Adjacent refactor under cover of a fix, forbidden. Details in #35.

Axis 6 — Implicit pedagogy and business transversality

On areas where the user is building expertise (PostgreSQL, EXPLAIN, tax, compliance), rule of three applies. 1st time done for, 2nd done with, 3rd done by. Regulated business vocabulary, not vendor vocabulary. Any mention of norm calls for textual citation; without citation, it's marketing. A vendor's practice is not a constraint, confront with project ADRs before treating as invariant.

Axis 7 — Long-term auditability

ADRs archived in docs/adr/NNNN-title.md. Sessions logged after any significant session (> 1h or > 3 commits). MEMORY.md ≤ 200 lines as index, detail in topical files. Any feedback memory associated with an active drift must point to a probe that confirms it. Without a probe, the memory rots. Quarterly audit calendared. Reread the index line by line, ask "is this still true?". The doctrine itself is versioned and audited like an ADR.

# Style and posture (excerpt from root CLAUDE.md)
- Direct and dense. No rephrasing of the request before answering,
  no end-of-turn summary, no excessive validation.
- Act then inform, don't ask permission for reversible actions.
- Anti-anthropomorphism. Never write "I think," "I understand,"
  "I prefer." State the decision, the criterion, the alternative
  discarded.

Anti-patterns to flag immediately

If the conversation drifts into one of these patterns, I flag it explicitly:

Anthropomorphizing the agent ("it thinks," "it prefers").
Validating a build on declaration without raw output.
Accepting a fix without full input → output pipeline.
Creating a derived column without an L/S/C category.
Starting a project > 2 files without an ADR.
Holding more than three projects open in parallel.
"You need" + norm without textual citation.
Pushback "are you sure?" producing revision without a new fact.

What you can copy into your project

Full snippets (DOCTRINE.md v0.2 complete, one-page ADR template, 8-anti-patterns review checklist) in the counterpart-doctrine/ folder of the series companion repo, MIT.

Three minimum axes to start with if you work with an AI agent on the long run:

Material verification, cheapest, most immediate. Any claim green / passed / OK / missing paired with the command and its raw output in the same message. Without material, zero claim. Details in #36.
Root cause, not patch, most protective. Before any fix, identify the root cause. A workaround stays legitimate if explicitly assumed in the commit AND in a feedback memory; silent workaround forbidden. Details in #35.
Long-term auditability, the one that structures all the rest. ADRs archived, sessions logged, MEMORY.md indexed under two hundred lines, calendared quarterly audit asking for each entry "is this still true?".

And an underlying discipline. Ask the next four sessions to produce at least one dated feedback file. You won't have a doctrine by month's end, you'll have four files, the matter from which one can settle. That's all it takes.

And you, on which recurring failure mode have you already begun formalizing a rule, without yet having named it? I read the comments.

Toward v0.3 (open construction)

This article publishes v0.2, it doesn't close the doctrine — it opens its next construction site in public.

Target: v0.3 pillar in mid-July 2026, six to eight weeks of satellite articles in between. Each one tests, contradicts or refines an axis. Comments on this pillar and the next ones are explicit inputs — the doctrine isn't the work of a solo, it's a convention that sediments, and the solo writes it in passing. The v0.3 release will mark the first revision made in view of being revised.

Four v0.2 debts already identified:

Axis 1 extended to tools. On April 30, the doctrine's own install.sh script announced seven ✓ installed while only a single file had been copied. Independent material verification holds for the agent as well as for the code I run — v0.2 wording was too narrow.
Four falsifiable metrics to define. v0.2 says falsifiable without putting a number on what's opposable. Candidates: recurrence of a flagged anti-pattern per session, ratio of multi-file commits without an associated ADR, median window between a drift's appearance and its detection by a probe, average session duration before the first DB audit.
Doctrinal target made explicit. Empirical feedback from a first install with an already-disciplined tester: no dramatic benefit. The doctrine serves solos who haven't yet sedimented the practice, not those who already have it from other paths. v0.3 names its audience instead of claiming universality.
Auto-commit hooks that name what they bundle. An opaque state before X commit over six files breaks the very axis 7 it claims to defend. To be reformulated.

And an eighth candidate axis: continuous revision of the doctrine itself. A quarterly audit on the index isn't the same thing as an explicit amendment discipline.

What have you seen your own doctrine crack on? The v0.3 pillar will cite its contributors.

The doctrine applies to itself

Current version v0.2, versioned, dated, falsifiable. Each axis can be disabled for a sprint if you assume the cost explicitly. The doctrine isn't a dogma, it's an internal convention that sediments. The day an axis no longer serves, retire it; the day a recurring failure mode appears, add an eighth. At a month of practice, the doctrine is not the condition for producing code with an AI agent, you can produce without. But you cannot, without it, preserve the coherence of the code as the project grows. Discipline of long coherence, not method of short productivity.

Companion code, rembrandt-samples/counterpart-doctrine/, DOCTRINE.md (7 axes), ADR-template.md, anti-patterns-checklist.md, MIT.

RLS recursion infinite loop: why I gave up policies and bet everything on a JWT custom claims hook

Michel Faure — Thu, 09 Jul 2026 15:49:24 +0000

Episode 1/4 — 3 incidents, one root: default GRANTs open more than you think — [CANONICAL URL EPISODE 1: fill in after push]
Episode 2/4 — await mutation() lies when nobody opens the { error } envelope — [CANONICAL URL EPISODE 2: fill in after push]

The morning Françoise sees zero rows, again

It's a Tuesday in April 2026. I've just added the agent_readonly role to the authenticated membership — a one-liner, meant to share a GRANT for a reporting job. First SELECT on cours, Sentry receives infinite recursion detected in policy for relation "user_roles", code 42P17. From the office next door, Françoise is already on the phone with the Maisons-Laffitte branch: "So they can't see anything over there — is that normal?" Foreman tone, not really a question. I read the error on my screen. The difference from episode 1: this time Postgres is talking.

What came out of Sentry was no longer a silent empty set — it was an explicit error. That difference saved me two days. When Postgres shouts, you listen. The trap is that what it says isn't where you're looking.

I won't pretend this is obscure. A policy on user_roles that queries user_roles to decide who can read user_roles is a loop. You avoid it, you work around it with SECURITY DEFINER, you move on. The problem: my user_roles policy didn't reference user_roles. I had already cleaned it up three weeks earlier. The recursion was coming from somewhere else.

The diagnostic that targets the wrong object

First reflex: re-read the user_roles policy. It's clean, reads auth.email(), never calls itself. Second reflex: disable policies one by one to find the culprit. Wrong angle.

-- supabase/migrations/20260420_admin_write_cours_v1.sql
-- "Admin write cours" policy — original version that loops
CREATE POLICY "Admin write cours" ON public.cours
  FOR ALL TO authenticated
  USING (
    EXISTS (
      SELECT 1 FROM public.user_roles
      WHERE email = auth.email()
        AND role IN ('admin', 'super_admin')
    )
  );

The recursion doesn't come from a faulty policy. It comes from the fact that Postgres evaluates all permissive policies matching the current role. When I add agent_readonly to authenticated membership, it inherits not only table privileges but the policy evaluation scope of anything posted TO authenticated. The Admin write cours policy, which reads user_roles, now gets evaluated for agent_readonly too. When agent_readonly reads user_roles, Postgres applies user_roles policies — posted TO authenticated, therefore inherited by agent_readonly — which contain an EXISTS (SELECT FROM user_roles) through that other table. The loop is closed.

The recursion isn't a writing bug. It's the structural consequence of coupling RLS with Postgres role membership inheritance. As long as any authenticated role can, through any path in a permissive policy, fall back onto a read of user_roles that itself applies policies, the loop is possible. Cleaning it in one place just moves it.

Three exits, two debts, one switch

I tried all three exits.

The first: SECURITY DEFINER. Wrap the user_roles read in a function that runs with its owner's privileges, bypassing RLS in its body. Other tables' policies call this function instead of EXISTS (SELECT FROM user_roles) directly. The recursion disappears locally. It's the patch that works tomorrow and costs you six months later — when you no longer know which policy reads what, when search_path wasn't locked, when auditing the surface becomes impossible because real permissions live in opaque functions. I kept it for two weeks.

The second: role isolation. Remove agent_readonly from authenticated membership, write dedicated policies per table. For a narrow technical role, that holds. For a dashboard where all authenticated users must read according to their policy, it doesn't scale — you're not going to duplicate every policy per role.

The third, the one I took: if the role is what causes the recursion, pull the role out of the database. Push it into the JWT at login, as a signed claim, and have policies read that claim.

The Custom Access Token Hook

Supabase exposes a Custom Access Token Hook — a Postgres function called by Supabase Auth just before the JWT is issued, which receives standard claims and can return enriched ones.

-- supabase/migrations/20260425170000_auth_hook_security_definer.sql
CREATE OR REPLACE FUNCTION public.auth_hook_add_role(event jsonb)
RETURNS jsonb
LANGUAGE plpgsql
STABLE
SECURITY DEFINER
SET search_path = ''
AS $$
DECLARE
  claims     jsonb;
  user_email text;
  user_role  text;
BEGIN
  claims     := event->'claims';
  user_email := claims->>'email';

  SELECT role INTO user_role
  FROM public.user_roles
  WHERE email = user_email
  LIMIT 1;

  IF user_role IS NOT NULL THEN
    claims := jsonb_set(claims, '{user_role}', to_jsonb(user_role));
  END IF;

  event := jsonb_set(event, '{claims}', claims);
  RETURN event;
END;
$$;

REVOKE EXECUTE ON FUNCTION public.auth_hook_add_role(jsonb) FROM PUBLIC, anon, authenticated;
GRANT  EXECUTE ON FUNCTION public.auth_hook_add_role(jsonb) TO supabase_auth_admin;

Three key precautions. SECURITY DEFINER because the function reads user_roles server-side — this is the one place I allow this bypass, executed by Supabase Auth, never by a user session. SET search_path = '' to block schema injection. REVOKE EXECUTE FROM PUBLIC, anon, authenticated then GRANT TO supabase_auth_admin: the function is only callable by the Auth system role.

On the policy side, the switch is terse:

-- supabase/migrations/20260425170234_phase_b_dual_check_policies.sql
-- "Admin write cours" refactored — reads JWT claim, not user_roles
CREATE POLICY "Admin write cours" ON public.cours
  FOR ALL TO authenticated
  USING (
    (auth.jwt() ->> 'user_role') IN ('admin', 'super_admin')
  )
  WITH CHECK (
    (auth.jwt() ->> 'user_role') IN ('admin', 'super_admin')
  );

The claim is signed, verified by Supabase, and the policy never touches user_roles again. Recursion is mechanically impossible because the permissions table is no longer queried during permission evaluation. 209 occurrences of auth.jwt() across 8 migration files since this switch — zero returns to EXISTS (SELECT FROM user_roles).

What changes, what stays

What changes. Recursion is no longer possible by design. A material probe confirms it:

SET LOCAL ROLE authenticated;
SET LOCAL "request.jwt.claims" = '{"email":"test@palissy.fr","user_role":"super_admin"}';
SELECT count(*) FROM public.user_roles;
-- 13 rows, RLS active, no 42P17 error

What stays. The hook becomes a single point of failure. If it's accidentally disabled — Studio manipulation, a migration that redefines it without the claim, a rights rotation that removes supabase_auth_admin — the claim disappears from the JWT, policies fall back on auth.jwt() ->> 'user_role' returning null, and every authenticated session gets denied access. Not a loop — a blackout. A different debt, more visible, that shouts when it falls. Preferable to a recursion that used to masquerade as a 42P17 you chased in vain.

What also stays: discipline. Any new Postgres role added to authenticated membership must be tested under SET LOCAL ROLE before prod, against a table with a non-trivial policy. Not to verify it doesn't trigger recursion — it can't anymore — but to verify that the scope of policies posted TO authenticated is exactly what you want it to inherit. The April incident's real lesson: GRANT membership is never a neutral operation.

Whatever you may think of "RLS best practices"

The doctrine I've read for three years repeats that you must write policies on user_roles. True in theory. In production, on a system with membership inheritance, it's a trap on a six-month fuse. The exit isn't writing better policies. It's recognizing that the permissions table has no business being in the permission-evaluation path, and that the JWT is precisely the place designed to carry what a session knows about itself.

Episode 4/4 — recap of all 4 lies and the Live/Snapshot/Cache doctrine applied to RLS: why the role in the JWT is a Snapshot of login time, not a Live read from the database — [CANONICAL URL EPISODE 4: fill in after push]

Episode 3/4 of "The week Supabase lied to me four times." The hook holds. The discipline remains. The fourth lie — the subtlest one — arrives on Friday.

The PostgREST query that silently ORDER BY ctid: a Supabase week, distilled

Michel Faure — Thu, 09 Jul 2026 15:49:09 +0000

The fourth call of the week

Catherine calls from the Maisons-Laffitte site on a Tuesday afternoon in early May. "It's broken, but it's a quick fix." That's her line — I know it, and she's usually right. She describes it in three sentences: the newsletter export for the enrolled-students segment comes back with ninety-two names, the planning view shows ninety-two active courses, but the counter page shows eighty-nine. Three enrolled students missing. She'd checked the database directly — they're all there. "Why three steps for that?" She's not asking for my benefit. She's asking for herself. Except this time, hanging up, I realize it's the fourth time this week I've hung up thinking the same thing. Four Supabase incidents, four fixes, four closed tickets. And not a single exception raised by the database.

I reopen the three previous ones and lay all four side by side on screen. This isn't four bugs. It's one failure mode, declinated four times.

The first three

Episode 1 was about the default GRANTs Supabase places on functions and policies. A SQL function created without an explicit REVOKE inherits anon access that nobody wrote in the migration, and that nobody caught in review because the diff doesn't show it. The function works. It's just callable from outside. [CANONICAL URL EPISODE 1: to fill in after publication of #48 — "3 Supabase security incidents, one shared root cause: SECURITY DEFINER inherits EXECUTE TO PUBLIC"]

Episode 2, an ON DELETE SET NULL cascade coupled with a CHECK NOT NULL on the target column. The parent DELETE attempts the SET NULL, the CHECK rejects it, and the transaction surfaces an error we read as a deletion failure — while it actually masks a consistency assumption we'd held for three months. The query fails loudly, which is more charitable than the other three cases, but the diagnosis heads in the wrong direction because nobody had declared that the two constraints lived in tension. [CANONICAL URL EPISODE 2: to fill in after publication of #49 — "When await mutation() lies: the { error } destructuring that saves your weekend"]

Episode 3, RLS recursion when auth.users queries user_roles which queries auth.users. The first live request after the policy is deployed takes down the session. The logic is correct on paper. It's the Postgres evaluation that can't terminate. [CANONICAL URL EPISODE 3: to fill in after publication of #50 — "RLS recursion infinite loop: why I gave up policies and bet everything on a JWT custom claims hook"]

And the fourth, which we already know

The fourth, I already told that story in isolation — the night of the lying dropdown, the counter stuck at exactly one thousand on a table carrying one thousand two hundred and three, the .select() chained on .from() with no .order(), the HTTP Range capped at a thousand and ctid stepping in as fallback sort order. [CANONICAL URL #40: https://dev.to/michelfaure/why-your-supabase-query-stops-at-exactly-1000-rows-and-never-tells-you-4g57] I won't re-expose the mechanics here, nor the ESLint rule that eventually shuts it down. What interests me, laying all four cases side by side, is that this fourth case isn't just one more anomaly. It's the purest portrait of a family that also includes the other three.

The common profile

Four times, the same gesture from the database. It receives a query, it executes it, it raises nothing. No exception surfaced to the client, no warning, no trace in Sentry, no application log. Return code is 200. The payload arrives. And it lies in a different way each time — incomplete payload for ctid, accessible payload for the GRANT, badly cascaded payload for the CHECK NOT NULL, absent payload for the RLS recursion when the query ends in a silent timeout on the infra side.

The unit test passes, because it runs against fifty locally seeded rows. The code review passes, because the incriminating chain fits on a single readable line. Prod breaks, because prod has twelve hundred rows, anonymous users calling endpoints we thought were private, and policies that loop around a dependency the developer never drew.

I used to read these four cases as four paragraphs of the Supabase manual we hadn't read carefully enough. I now think it's more structural than that. A vendor default isn't a paragraph to read — it's an implicit design decision that the platform's client adopts without seeing it, because it appears nowhere in their own code. The thousand-row Range, the default anon access, the recursion permitted on an auth-policy, the behavior of ON DELETE SET NULL against a CHECK — these are micro-contracts nobody wrote in the repo that nonetheless hold up production.

Three rules to close the door

Four incidents in one week isn't a statistic, it's a convergence that demands doctrine. I'll leave aside the idea of writing more tests, since none of these four cases would have been caught by a unit test, and integration would only have saved the second one given exactly the right fixture. Three material rules instead.

First rule: every undeclared vendor default is an implicit Snapshot — materialize it at commit time or forbid it. Snapshot in the sense of our internal nomenclature: a frozen value that no mechanism refreshes. When the platform sets a default behavior that my code doesn't write, it plants a frozen copy of the platform contract in my repo without my knowledge. The day Supabase changes its max_rows, or refines its anon policy, I'll discover the drift in production. So either the default is cited textually in a CLAUDE.md rule or an ADR and its expected behavior is asserted, or the practice that depends on it is blocked by a material guard — ESLint rule, SQL CHECK, pre-commit hook. No lukewarm middle ground.

Second rule: the ESLint rule beats code review as soon as the pattern counts in the dozens. A .from().select() chain without .order() hides in hundreds of files. Human code review can't hold against that volume — it will catch two occurrences out of ten, not more. An AST rule, by contrast, sweeps the repo in one pass, and it's what says no to the next PR, mechanically, without a human needing to squint at the diff. The upfront cost is in the structural guards needed to avoid drowning in false positives. I measured it on the ctid case: five anti-noise mechanisms reduced the rule from one hundred seventy-eight raw alerts to one hundred eight real targets, without which it would have been disabled from lassitude within a week.

Third rule: instrumentation must come from prod, not from tests. None of these four defaults depends on the logic of the code — they all depend on volume, auth context, call frequency, or table history. The unit test never sees them. So the net is a daily prod probe, measuring what prod actually does, and screaming when a counter suspiciously resembles a ceiling. Why exactly one thousand? Why exactly zero refused accesses on a sensitive endpoint? Why has this policy never consumed CPU? These are questions no test asks, but a daily drift probe can ask the database itself.

A fourth rule, if you want one

And if you want one last sharp wedge, I'd place it here: never read a vendor default from an AI agent — read it from the official docs and materialize it in the repo. When you ask an agent what Supabase does when you don't declare .order(), it will answer plausibly, and there's a non-zero chance it gets the cap value wrong, or the version where the behavior changed, or the fallback order. The material source is the docs, and the real-world test is a local migration you inspect against ten thousand seeded rows. The agent can write the probe — it can't self-attest. That's exactly the posture that the doctrine I've published elsewhere imposes: cite the official text, materialize vendor defaults.

Coda

Four incidents in one week, one failure mode. The database doesn't lie out of malice — it executes contracts nobody explicitly signed in my repo and that my unit tests can't reproduce because they don't operate on those dimensions. The defense isn't more vigilance; I can see clearly now that human vigilance bends against four invisible defaults stacked on top of each other. It's more material guards, set once, that prevent the whole class of incidents from returning. An ESLint rule, a CHECK constraint, a drift probe, an ADR that names the vendor default — each of those buys back a quiet Tuesday afternoon. When Catherine calls again, it will be for a fifth reason, and that one I'd rather not know in advance.

Four Supabase episodes, one mini-series. The full ESLint rule and the pseudonymized fetchAll helper live at:
github.com/michelfaure/rembrandt-samples/tree/main/postgrest-row-cap

This vendor-default typology is the core of R12 in the Counterpart Toolkit ("cite the official text, materialise vendor defaults"). 14 rules, one-command install: github.com/michelfaure/doctrine-counterpart

Why your agent over-engineers your simplest request (and the 3 prompts that stop it)

Michel Faure — Thu, 09 Jul 2026 15:48:48 +0000

The request was eight words

Monday morning. I open the outgoing email queue: six hundred and forty-seven drafts waiting, six hundred and seventy-two sent. Nobody clicks Send. First-contact emails are prepared by a pipeline and they sleep, because the last step assumes a human. That human, I had stopped believing she would have the time. I state the decision: automate sending.

The response comes in seconds. Three levels of automation. Four channels. Three risk thresholds. All correct, all fit for a half-day architecture workshop. I had not asked for a workshop. Pauline walks behind me, glances at the screen, says nothing.

Three timed reframes

First reframe, brief: too strange, let's simplify. The agent drops two axes, keeps four residual layers, progressive warm-up over three weeks, deterministic anti-replay hash, configuration table in the database, manual Phase 1 followed by an automated Phase 2 to validate after two weeks of measurement. The target stays the same, that an email leaves without a human click. The path has grown accordingly.

Second reframe, drier: simple, three safeguards, a kill-switch, we do this in one day. The agent re-architects, accepts the one-day target, keeps the three safeguards. But slips in three prostheses it calls industry standard: real-time dashboard, exponential retry, structured audit log in a new table. Each justifiable in isolation. None of them requested.

Third reframe, shorter still: I don't understand why you're adding this. An opening line almost embarrassed, which I had never read from it before: "you're right, I'm over-engineering without necessity." And the version that should have arrived on the first round. A function that takes the draft record, checks three conditions, calls the send engine, returns.

// lib/email-outbox.ts — generateFirstContactDraft (commit 3756e63)
if (!EMAIL_REGEX.test(input.email)) {
  return { success: false, error: 'email_invalide' }
}
if (BLACKLIST_EMAILS.has(input.email.toLowerCase())) {
  return { success: true }               // silent
}
if (existing && existing.length > 0) return { success: true }  // dedup

// ... draft construction ...

const autoSend = process.env.PREMIER_CONTACT_AUTOSEND === 'true'
if (!autoSend) return { success: true }  // kill-switch → draft preserved

const { sendOutboxEmailCore } = await import('@/lib/email-outbox-send')
return sendOutboxEmailCore(inserted.id)

The cost of the dialogue

On the first round I wanted a function, the agent proposed a platform. On the second I wanted a day of code, it proposed a quarter of deployment. On the third I wanted fifteen lines, it proposed three observability mechanisms. The feature met its one-day target, but the day split into two unequal halves: ninety minutes of reframing, six hours of clean code.

The agent did not want to complicate things, and I write that without irony. It has training that rewards completeness of options. When a human asks a consultant "automate my sends," the competent consultant does not answer with a fifteen-line function — they answer with a decision grid. The agent learned that posture on millions of tokens, it applies it perfectly, on every request that looks from a distance like an architecture question.

My gauge

Three reframes in a session on a simple request is a signal. Either the initial prompt was too vague, or the agent switched to platform mode when we were in function mode. Beyond three, the cost cannot be recovered in the same day.

The fix candidate fits in one sentence, inserted at the top of the prompt: "propose the minimal version in fifteen lines. No matrix. No phases. Extensions after, below." The measure holds its first week. I'll report in the next episode whether it holds the month.

DEV Community: Michel Faure

Les 12 outils que j'utilise pour piloter Claude Code en production : gardés, jetés, contestés

L'incident qui pose la question

Le contexte qui survit à la session

Les dispositifs invocables

L'observabilité matérielle

La délégation et l'arbitrage

Ce que j'ai appris du catalogue

Quand `await mutation()` ment : le destructure `{ error }` qui sauve ton week-end

Le mercredi de la semaine où Supabase mentait

Le contrat dont personne ne parle

Le code qui a menti

Pourquoi ESLint ne suffit pas

Le wrapper qui force la destructure

Ce que Supabase n'invente pas

Coda

Pourquoi ton agent sur-équipe ta demande la plus simple (et les 3 prompts qui l'arrêtent)

La demande tenait en huit mots

Trois recadrages chronométrés

Le coût du dialogue

Ma jauge

Pourquoi j'ai cessé de lire mon propre backlog.md (et ce que je lis à la place)

Le matin où mon propre fichier m'a menti

Un summary est un Cache sans rafraîchisseur

Ce que je lis à la place

Coda

Ce que 74 ADR en 70 jours achètent vraiment à un dev solo (pas d'embauche, pas de client, juste le fichier)

La question qu'on n'ose pas poser à voix haute

La fausse économie du « je m'en souviens »

Le ROI mesurable en première personne

Ce que ça ne paie pas

Le ROI invisible

Coda

When `await mutation()` lies: the `{ error }` destructuring that saves your weekend

Wednesday of the week Supabase was lying

The contract nobody talks about

The code that lied

Why ESLint isn't enough

The wrapper that enforces destructuring

What Supabase didn't invent

Coda

La requête PostgREST qui trie en silence par `ctid` : une semaine Supabase, distillée

Le quatrième appel de la semaine

Les trois premiers

Et le quatrième, qu'on connaît déjà

Le profil commun

Trois règles pour fermer la porte

Une quatrième règle, si l'on veut

Coda

3 incidents Supabase, une seule racine : SECURITY DEFINER hérite de EXECUTE TO PUBLIC

Le mardi où la sonde sécurité a parlé

Trois objets, trois portes, un mécanisme

Le premier piège, CREATE TABLE AS SELECT

Le deuxième piège, CREATE POLICY ... TO public

Le troisième piège, racine partagée, SECURITY DEFINER hérite de EXECUTE TO PUBLIC

L'audit qui rend les trois pièges visibles

Ce que l'épisode 1 nous apprend, et ce que les suivants nous montreront

The Counterpart Doctrine: a seven-axis spec for working with an AI coding agent

The doctrine wasn't planned

The seven axes

Axis 1 — Material verification

Axis 2 — Bidirectional adversariality

Axis 3 — Data taxonomy and single source

Axis 4 — Session discipline

Axis 5 — Root cause, not patch

Axis 6 — Implicit pedagogy and business transversality

Axis 7 — Long-term auditability

Anti-patterns to flag immediately

What you can copy into your project

Toward v0.3 (open construction)

The doctrine applies to itself

RLS recursion infinite loop: why I gave up policies and bet everything on a JWT custom claims hook

The morning Françoise sees zero rows, again

The diagnostic that targets the wrong object

Three exits, two debts, one switch

The Custom Access Token Hook

What changes, what stays

Whatever you may think of "RLS best practices"

The PostgREST query that silently ORDER BY ctid: a Supabase week, distilled

The fourth call of the week

Le premier piège, `CREATE TABLE AS SELECT`

Le deuxième piège, `CREATE POLICY ... TO public`

Le troisième piège, racine partagée, `SECURITY DEFINER` hérite de `EXECUTE TO PUBLIC`