Engineering choices5 min read
Décisions d’architecture
Les décisions qui donnent sa forme au logiciel, au format ADR. Je sépare ce que les sources confirment de ce qui reste une hypothèse.
Not translated yet
Un ADR (Architecture Decision Record), c’est la fiche d’une décision qui donne sa forme au code et qui coûterait cher à défaire. Ils ont tous le même plan : le contexte, les contraintes, les alternatives, la décision, ses raisons, ses compromis et ses conséquences, puis les risques qui restent et ce qui ferait revoir la décision. Le détail technique est dans les pages qui décrivent le code. L’ADR y renvoie et ne le recopie pas.
Ces quatorze ADR ont été rédigés avec Claude Code le 13 novembre 2026, à partir de l’historique git, des AGENTS.md et de l’ancien journal des décisions. Dans chaque en-tête, la date est celle de la décision. Ce n’est pas celle du jour où l’ADR a été écrit. Le dépôt est privé. Pour relire les commits cités, il faut donc un accès au dépôt, et je montre volontiers le code en entretien.
Confirmé ou supposé
- Une raison est confirmée quand quelqu’un l’a écrite au moment de la décision. Ça peut être une décision que j’ai datée (dans un
AGENTS.md, un message de commit ou l’ancien journal des décisions), un message de commit, un commentaire du code ou d’une migration. La source est citée à côté. Un commit se relit avecgit show <hash>, et l’ancien journal avecgit show 2fd35cdb09^:docs/decisions.md. - Une raison est une hypothèse quand personne ne l’a écrite à l’époque. Dans ce cas, on la déduit du code, de l’ordre des commits ou d’une page écrite après coup, cette doc comprise. L’ADR le signale, pour qu’on puisse la confirmer ou la corriger.
- Une alternative n’est dite « étudiée » que si une trace le montre. Les autres, ce sont celles auxquelles un lecteur penserait. Elles servent à situer la décision. Ça ne veut pas dire qu’on en a débattu.
Ce qui me revient dans ces décisions
Dans sept de ces ADR, la décision ou la demande qui les fonde est datée de moi, dans les contraintes ou dans les raisons confirmées.
| ADR | Ce que j’ai décidé ou demandé | Date |
|---|---|---|
| 0006 | retirer le journal des décisions et vider docs/, pour que la raison d’une règle soit dans le code ou dans un test | 1er et 5 septembre |
| 0007 | un écran de l’ERP s’affiche sans attendre sa lecture la plus lente | 22 octobre |
| 0009 | la migration de la prod se joue à la main avant la fusion, puis sans copie de la base, puis avec un geste outillé | 31 août, 25 octobre, 13 novembre |
| 0010 | un dépôt privé qui reste gratuit, une seule branche, une CI plus simple, puis des tests que je suis le seul à lancer | 17 et 21 septembre, 12 octobre |
| 0012 | l’analyse de TanStack AI avant d’intégrer Fisher, puis pas de plan Pro, donc des échanges conservés trente jours, et un périmètre ouvert | 23 et 26 octobre |
| 0013 | ne plus ajouter de copie à mettre à jour à la main | 9 novembre |
| 0014 | retirer le délai d’attente des nouvelles versions, une décision renversée depuis | 29 août |
Ce sont des décisions de budget, de périmètre et de méthode. Les dates du 31 août et du 25 octobre viennent de Ma contribution et l’IA. Les autres viennent de l’ADR lui-même.
Les sept autres ADR, ce sont les choix de structure : le monorepo, les deux applications, la base partagée et le rôle du site, l’irréversible confié à l’ERP, la sortie du code commun, l’argent inaltérable et l’authentification. Ils sont nés de propositions de Claude Code, dans le cadre que je posais, et je les ai retenus. Pour l’argent inaltérable, ma trace, c’est une question. Le 10 novembre, j’ai demandé de vérifier l’ERP contre les quatre conditions de la loi sur les logiciels de caisse. Le commit du lendemain scelle les ventes dès leur premier encaissement (l’épisode).
Je propose de défendre n’importe lequel de ces ADR en entretien, sans l’IA, et de dire ce qui me ferait changer d’avis (les questions que je propose).
Compromis, risques, révision
Les trois dernières sections ne disent pas la même chose :
- Un compromis, c’est un coût certain. On le paie dès que la décision est prise.
- Un risque résiduel, c’est ce qui peut encore mal tourner malgré la décision et ses gardes. L’ADR dit aussi ce qui le limite.
- Quand la revoir donne le signal observable qui rendrait la décision mauvaise, et l’évolution qu’il faudrait faire dans ce cas.
Les deux dernières sont une analyse écrite le 13 novembre 2026. Ce ne sont pas des décisions. Elles disent ce qui ferait changer d’avis, et elles ne prévoient rien. Les risques qui ne dépendent d’aucune décision, et les évolutions classées selon l’urgence de leur signal, sont dans Dette, risques et évolutions.
Ce que ces pages ne recopient pas
Le 1er septembre 2026, j’ai retiré le journal des décisions (docs/decisions.md). Il ne disait plus lesquelles de ses entrées étaient encore valables. À partir de là, la raison d’une règle devait être à l’endroit exact du code, ou dans un test (2fd35cdb09). Ces ADR en tiennent compte. Ils ne recopient pas un seuil, une durée ou une liste que le code connaît déjà. Ils donnent le fichier ou le symbole où ça se trouve (fichier.ts#SYMBOLE). Les chiffres qu’ils citent sont datés, et ils décrivent le projet au moment de la décision.
Une décision renversée garde son ADR. Son statut dit ce qui la remplace, et le nouvel ADR dit ce qu’il remplace. Une décision retouchée sans être renversée est dite « amendée », avec la date et la source de l’amendement.
- 0001 · Un monorepo, des paquets en source(in French)Les applications et le code qu’elles partagent sont dans un seul dépôt pnpm. Les paquets n’ont pas de build et pas de version.
- 0002 · La boutique et l’ERP, deux applications(in French)Le site public sort de l’ERP et devient une application Next.js à part. Il est parti d’une copie élaguée de l’ERP.
- 0003 · Une base partagée, un rôle borné pour le site(in French)L’ERP et le site lisent et écrivent dans la même base Postgres. C’est la base elle-même qui limite ce que le site peut faire.
- 0004 · Ce qui ne se défait pas appartient à l’ERP(in French)Seul l’ERP confirme un paiement, émet une pièce, écrit dans le stockage et a les clés d’écriture. Le site lui parle par des canaux signés.
- 0005 · Le code commun sort du fork sans casser les tests(in French)L’application câble ses paquets, des relais gardent le chemin d’origine, et un contrôle empêche deux copies d’une même règle de diverger.
- 0006 · Le lint garde les frontières du code(in French)Les couches, l’isolement des modules et l’accès à la base sont vérifiés par ESLint. Si on franchit une frontière, c’est une erreur, et plus une simple consigne.
- 0007 · Tout en cache sur le site, presque rien dans l’ERP(in French)L’ERP et le site rendent sur le serveur par défaut, avec un prérendu partiel. Le site met en cache par tags. L’ERP relit la base à chaque geste, sauf deux référentiels.
- 0008 · L’argent et les pièces, inaltérables dans la base(in French)Des montants en centimes, des instantanés à la vente, une numérotation sans trou. C’est Postgres qui impose les gardes et le chaînage, plutôt que le code.
- 0009 · Prisma sur Neon, migrations avant le code(in French)Le schéma Prisma est sur Neon. Les migrations passent en prod avant la fusion, et pour revenir en arrière, on restaure la base à un instant.
- 0010 · Pas de CI hébergée : la porte est sur le poste(in French)Les contrôles tournent sur mon poste, dans le hook pre-push. Seule main se déploie, et les tests se lancent à la main.
- 0011 · Better Auth, un seul rôle dans l’ERP(in French)Une seule bibliothèque d’authentification, dans un paquet, avec deux fabriques : les clés d’accès pour le personnel, le code par e-mail pour les clients.
- 0012 · Fisher : Anthropic seul, des chiffres sourcés(in French)Fisher, l’assistant de l’ERP, appelle les modèles d’Anthropic par la passerelle de Vercel. Ses gestes sont dans un registre, ses chiffres sont vérifiés et ses écritures sont confirmées.
- 0013 · La documentation vit dans le dépôt(in French)La doc est une troisième application Next.js du monorepo. Elle inclut les textes du dépôt et recalcule ses figures au build.
- 0014 · Un catalogue de versions, un jour d’attente(in French)Chaque dépendance commune a une seule version. Elle doit être publiée depuis au moins un jour, avec au moins autant de garanties que la précédente.