Le fichier qui s'ouvre avant le premier commit
30 avril 2026, fin d'après-midi. La page /admin de Rembrandt vient de me trahir pour la troisième fois en deux jours. Blandine, administratrice, ne voit pas l'onglet Émargement, alors que la case « Émargement » est cochée dans la grille de droits qu'elle gère elle-même. Trente minutes de diagnostic plus tôt, j'avais compris : la case écrit dans dashboard_cards (préférence d'affichage) et ne touche jamais can_access_emargement (flag de droit). Deux couches sémantiques empilées dans la même grille, traitées comme une.
Niran est dans le bureau, capuche pendue dans le dos, un emballage de burger replié sur le coin du laptop. Il prépare une analyse financière pour Antoine, il ne suit pas mon écran. Je m'apprête à ouvrir app/admin/page.tsx et à corriger. À la place, je crée un fichier vide : docs/adr/0040-admin-rbac-vs-dashboard-cards.md. Pas une ligne de code touchée. Une page Markdown.
Cette inversion de l'ordre — l'ADR avant le premier commit, jamais après — est l'unique discipline qui fait tenir l'architecture de Rembrandt. Je veux décrire pourquoi.
L'ADR rétroactif est un mensonge
L'Architecture Decision Record, dans la version courte que je tiens, fait quatre rubriques : décision retenue, alternatives écartées avec leur raison de rejet, conséquences positives et négatives, références. Une page. Le piège, c'est de l'écrire après coup. Le code est déjà poussé, la décision a été prise au flair, l'ADR documente ce qui s'est passé en lui donnant une cohérence rétrospective. Tout ce qui ne colle pas à la décision finale est lissé, les alternatives écartées sont écrites en sachant déjà qu'elles seront rejetées, les conséquences négatives sont prudentes parce qu'on les vit déjà.
C'est un mensonge poli. Pire, c'est un mensonge utile : il rassure le lecteur futur qui croit lire une décision testée, alors qu'il lit la rationalisation d'un premier réflexe.
Avec Claude Code, le risque est multiplié. Je décris un problème, l'agent rend une architecture cohérente en quelques minutes, je l'accepte parce qu'elle tient debout. Je n'ai pas testé l'alternative. Je n'ai même pas vu qu'il y en avait une. L'ADR rétroactif ratifie ce non-choix. L'ADR préalable l'interdit, parce qu'il faut écrire les alternatives avant de savoir laquelle sera retenue.
Ce que la forme oblige
Voici le squelette du 0040-admin-rbac-vs-dashboard-cards.md tel qu'il est en prod :
<!-- docs/adr/0040-admin-rbac-vs-dashboard-cards.md -->
# ADR-0040 — Page /admin : séparation RBAC / dashboard_cards / rôle
- Date : 2026-04-30
- Statut : Accepted
- Décideur : PBR
## Contexte
[trois couches sémantiques distinctes, incident Blandine, ~30 min diagnostic]
## Décision
1. Invariant `dashboard_cards ⊆ accessibleSlugs` (validation serveur)
2. UI séparée : 3 sections ordonnées
3. Server action `toggleUserFlag` avec whitelist stricte
4. Correction `listUserRoles` (SELECT explicite)
## Alternatives rejetées
1. Patch cosmétique (renommer libellés) — ne traite pas la cause racine
2. Fusionner dashboard_cards dans le RBAC — retire la granularité
3. Trigger Postgres en garde-fou DB — coût duplication TS↔SQL trop élevé
## Conséquences
[positives, négatives, différé volontairement]
La rubrique qui fait tout le travail, c'est Alternatives rejetées. Trois alternatives, chacune avec une raison de rejet courte et technique. Le patch cosmétique est rejeté parce qu'il ne traite pas la cause racine. La fusion est rejetée parce qu'elle retire la granularité. Le trigger DB est différé parce que la matrice vit en TS et la dupliquer en SQL crée son propre drift. Aucune de ces phrases n'est sortie naturellement de l'agent. Chacune est venue d'une question que je lui ai posée, par écrit, dans l'ADR : « et si on faisait ça ? — pourquoi pas ? ». La réponse écrite a éliminé l'option. La forme a fait son travail.
Le workflow Claude Code
Trois disciplines spécifiques, sans elles l'ADR vaut moins que rien.
Phase 0 — grep des ADR existants. Avant d'ouvrir 0040, je grep dashboard_cards et permissions dans docs/adr/. Je trouve ADR-0014 (RLS systématique) qui pose le décor RBAC et ADR-0017 (source vérité inscriptions) qui m'évite de réinventer un pattern. Sans ce grep, j'aurais dupliqué un raisonnement déjà fait. Claude Code aurait régénéré une cohérence locale, ignorante des décisions sœurs.
Agent challenger sur structurellement significatif. Pour ADR-0044 (tests de contrat DB ↔ code, livré J1 le 2 mai), l'agent challenger a soulevé six objections, classées bloquantes / importantes / cosmétiques. La section « Réponse au challenger » fait partie de l'ADR final — c'est l'audit-trail de la pré-engagement adversariale. Une décision qui n'a pas été attaquée n'a pas été testée. Une décision qui a été attaquée et tient s'inscrit.
Exiger une raison technique de rejet. Les alternatives écartées sans raison sont un piège. « Trop complexe » ne rejette rien. « Coût de duplication TS↔SQL trop élevé pour le bénéfice marginal vs double validation app-side » rejette. Je relis cette rubrique et tout ce qui ressemble à une intuition non-formulée repart en question.
La règle
Avant tout chantier touchant plus de deux fichiers ou changeant un invariant métier, ouvrir le fichier ADR. Pas de code avant que les quatre rubriques tiennent. L'ADR peut être incomplet, faux, à revoir — il existe. Le commit suivant peut le contredire. Mais il existe avant, et c'est cette antériorité qui filtre les décisions de complaisance.
Quand l'ADR est écrit après, c'est qu'il n'a servi à rien. Mieux vaut ne pas l'écrire que mentir.
Coda
Cinquante-quatre ADR en trente-cinq jours de travail effectif. Cinquante et un publiés dans le repo, trois fiscaux privés non publiables (0011–0013). Cadence d'environ un et demi par jour, coût marginal proche de zéro avec Claude Code. Cette cadence n'est pas un trophée — c'est une indication que le format ADR, étrillé pendant vingt ans dans des équipes lourdes, devient un instrument quotidien quand l'écriture est gratuite.
Niran a fini son analyse. Il ferme le laptop, plie l'emballage, dit « je file » en passant devant moi. Le fichier 0040 est fini. Le code n'est pas écrit. La couche peut être posée.
Code compagnon : rembrandt-samples/writing-adrs-claude-code/ — template ADR Rembrandt + checklist Phase 0 grep + script adr-grep.sh, licence MIT.
Top comments (0)