ADR 0007 : architecture et conventions de code #3

2026-11-02T12:41:37Z

pierre commented

2026-11-02 12:41:37 +00:00

Pourquoi

Le code d'Ustagammon va être écrit par des agents, et Pierre ne le relit pas en détail. Sans règles posées tôt, chaque agent organiserait le code à sa façon, et l'application deviendrait difficile à comprendre et à faire évoluer. Les premiers agents (0a.2 et 0a.3) sont justement en train d'écrire du code : c'est le moment de fixer le cadre.

Pierre a demandé des bonnes pratiques de niveau senior, mais surtout « quelque chose de simple, et compréhensible par un humain (pas d'overengineering) ». Il a arbitré trois points : le stockage des parties, la langue des identifiants et la vérification automatique de l'architecture.

Quoi

Un nouvel ADR, docs/adr/0007-architecture-et-conventions-de-code.md, fixe :

la simplicité d'abord : pas d'abstraction sans deuxième usage réel, pas de framework sans besoin avéré ;
trois parties (domaine pur, moteur derrière engine/include/engine.h, application), avec une seule règle : les dépendances vont vers le domaine, et aucun écran n'appelle le moteur directement ;
une partie est un journal d'événements, en arbre : les branches (« Rejouer d'ici ») et l'annulation en découlent sans code spécifique. Le reste de l'application est stocké simplement ;
le hasard est injecté : tests reproductibles, historique des dés consultable ;
les identifiants du code en anglais, les commentaires, la doc et les commits en français. L'interface C prévue sous le nom moteur.h devient donc engine.h ;
le langage commun du DDD sans sa cérémonie ;
la stratégie de tests : domaine avec un faux moteur, suite de contrat commune à tous les adaptateurs du moteur, peu de tests de bout en bout ;
les règles pour notre code C.

CLAUDE.md, docs/etape-0.md, la feuille de route et l'index des ADR sont mis à jour. Un second commit ajoute /.claude/ au .gitignore : les espaces de travail des sous-agents s'y trouvent, et le premier commit de cette branche les avait embarqués par erreur.

Comment

Les choix suivent ce que demande le cadrage, au plus simple :

Interface du moteur : le cadrage la demandait déjà (« aucun écran ne l'appelle directement ») ; l'ADR en fait une règle générale du domaine.
Journal d'événements : il répond directement à deux fonctions du cadrage, les branches et l'annulation, et à l'export SGF, qui est lui-même un journal de coups.
Tests d'architecture : ils remplacent la relecture humaine, que Pierre ne fait pas.

Les deux agents en cours de travail ont reçu les nouvelles conventions (identifiants en anglais, simplicité) ; leurs branches les appliqueront.

Choix et compromis

Event sourcing limité aux parties, pas étendu à toute l'application avec projections (CQRS) : trop lourd pour une application hors ligne à un seul utilisateur.
Pas d'état classique pour les parties : plus simple au départ, mais les branches et l'annulation deviendraient du code au cas par cas.
Identifiants en anglais (choix de Pierre) : conventions habituelles du code et des bibliothèques, au prix d'un écart entre les noms du code et ceux de la doc. Le glossaire fera le lien.
Pas d'architecture hexagonale formelle ni de DDD complet : trop d'interfaces et de vocabulaire pour une application de cette taille.
L'outil de vérification des dépendances n'est pas encore choisi : il dépend du socle (PWA ou Android), décidé à la fin de l'étape 0.

Risques et déploiement

Aucun code applicatif ne change.

Le format des événements de partie devient un contrat durable : le changer plus tard demandera une migration et un nouvel ADR.
Le renommage moteur.h en engine.h touche l'ADR 0005, qui n'est pas réécrit (règle des ADR) : l'ADR 0007 signale le renommage.

Retour arrière : annuler le commit de fusion.

Comment vérifier

git switch main && git pull
make lint && make test
less docs/adr/0007-architecture-et-conventions-de-code.md
git ls-files .claude | wc -l    # 0

Hors périmètre

La structure exacte des dossiers du domaine, le langage de l'interface (TypeScript ou Kotlin) et l'outil de vérification des dépendances seront fixés avec le choix du socle.
Le glossaire des termes du jeu sera écrit avec les premières fonctions du domaine (étape 0d).
Les MR !1 et !2 apparaissent toujours « open » dans Gitea alors qu'elles sont fusionnées (commits de fusion 6958acc et aa4f504 sur main). C'est noté dans le journal ; le diagnostic côté serveur reste à faire.

Generated with Claude Code https://claude.com/claude-code

## Pourquoi Le code d'Ustagammon va être écrit par des agents, et Pierre ne le relit pas en détail. Sans règles posées tôt, chaque agent organiserait le code à sa façon, et l'application deviendrait difficile à comprendre et à faire évoluer. Les premiers agents (0a.2 et 0a.3) sont justement en train d'écrire du code : c'est le moment de fixer le cadre. Pierre a demandé des bonnes pratiques de niveau senior, mais surtout « quelque chose de simple, et compréhensible par un humain (pas d'overengineering) ». Il a arbitré trois points : le stockage des parties, la langue des identifiants et la vérification automatique de l'architecture. ## Quoi Un nouvel ADR, `docs/adr/0007-architecture-et-conventions-de-code.md`, fixe : - **la simplicité d'abord** : pas d'abstraction sans deuxième usage réel, pas de framework sans besoin avéré ; - **trois parties** (domaine pur, moteur derrière `engine/include/engine.h`, application), avec une seule règle : les dépendances vont vers le domaine, et aucun écran n'appelle le moteur directement ; - **une partie est un journal d'événements**, en arbre : les branches (« Rejouer d'ici ») et l'annulation en découlent sans code spécifique. Le reste de l'application est stocké simplement ; - **le hasard est injecté** : tests reproductibles, historique des dés consultable ; - **les identifiants du code en anglais**, les commentaires, la doc et les commits en français. L'interface C prévue sous le nom `moteur.h` devient donc `engine.h` ; - **le langage commun du DDD sans sa cérémonie** ; - **la stratégie de tests** : domaine avec un faux moteur, suite de contrat commune à tous les adaptateurs du moteur, peu de tests de bout en bout ; - **les règles pour notre code C**. `CLAUDE.md`, `docs/etape-0.md`, la feuille de route et l'index des ADR sont mis à jour. Un second commit ajoute `/.claude/` au `.gitignore` : les espaces de travail des sous-agents s'y trouvent, et le premier commit de cette branche les avait embarqués par erreur. ## Comment Les choix suivent ce que demande le cadrage, au plus simple : - **Interface du moteur** : le cadrage la demandait déjà (« aucun écran ne l'appelle directement ») ; l'ADR en fait une règle générale du domaine. - **Journal d'événements** : il répond directement à deux fonctions du cadrage, les branches et l'annulation, et à l'export SGF, qui est lui-même un journal de coups. - **Tests d'architecture** : ils remplacent la relecture humaine, que Pierre ne fait pas. Les deux agents en cours de travail ont reçu les nouvelles conventions (identifiants en anglais, simplicité) ; leurs branches les appliqueront. ## Choix et compromis - **Event sourcing limité aux parties**, pas étendu à toute l'application avec projections (CQRS) : trop lourd pour une application hors ligne à un seul utilisateur. - **Pas d'état classique pour les parties** : plus simple au départ, mais les branches et l'annulation deviendraient du code au cas par cas. - **Identifiants en anglais** (choix de Pierre) : conventions habituelles du code et des bibliothèques, au prix d'un écart entre les noms du code et ceux de la doc. Le glossaire fera le lien. - **Pas d'architecture hexagonale formelle ni de DDD complet** : trop d'interfaces et de vocabulaire pour une application de cette taille. - **L'outil de vérification des dépendances n'est pas encore choisi** : il dépend du socle (PWA ou Android), décidé à la fin de l'étape 0. ## Risques et déploiement Aucun code applicatif ne change. - **Le format des événements de partie devient un contrat durable** : le changer plus tard demandera une migration et un nouvel ADR. - **Le renommage `moteur.h` en `engine.h`** touche l'ADR 0005, qui n'est pas réécrit (règle des ADR) : l'ADR 0007 signale le renommage. Retour arrière : annuler le commit de fusion. ## Comment vérifier ``` git switch main && git pull make lint && make test less docs/adr/0007-architecture-et-conventions-de-code.md git ls-files .claude | wc -l # 0 ``` ## Hors périmètre - La structure exacte des dossiers du domaine, le langage de l'interface (TypeScript ou Kotlin) et l'outil de vérification des dépendances seront fixés avec le choix du socle. - Le glossaire des termes du jeu sera écrit avec les premières fonctions du domaine (étape 0d). - Les MR !1 et !2 apparaissent toujours « open » dans Gitea alors qu'elles sont fusionnées (commits de fusion 6958acc et aa4f504 sur `main`). C'est noté dans le journal ; le diagnostic côté serveur reste à faire. Generated with Claude Code https://claude.com/claude-code

pierre added 2 commits 2026-11-02 12:41:37 +00:00

ADR 0007 : architecture et conventions de code 59895393fe

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Ignorer les espaces de travail des sous-agents (.claude/) 5b976caf65

Retire les deux worktrees embarqués par erreur dans le commit précédent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

pierre manually merged commit 463bc6f553 into main

2026-11-02 18:02:01 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: pierre/Ustagammon#3