ADR 0008 : glossaire et scénarios, source unique pour le code, l'aide et les tests #4

2026-11-02T12:45:58Z

pierre commented

2026-11-02 12:45:58 +00:00

Pourquoi

Le code d'Ustagammon est en anglais (ADR 0007), mais l'interface et la documentation sont en français. Sans lien explicite entre les deux, un humain qui lit le code ne saurait pas que Cube est le videau, ni Drop le fait de passer. Les mots du jeu risqueraient aussi de varier entre le code, la doc et l'écran.

Pierre a fixé trois exigences pour la documentation :

un glossaire où chaque mot a sa traduction anglaise, référencé par le code du domaine ;
une documentation utilisateur fondée sur des cas d'usage réels, versionnée, consultable dans l'application, et pouvant servir de base aux tests de bout en bout ;
une seule source de vérité, sans documentation dupliquée.

Il a aussi rappelé que le travail de l'IA doit être encadré par des tests.

Quoi

L'ADR 0008 (docs/adr/0008-glossaire-et-scenarios-source-unique.md) fixe trois règles :

Glossaire dans docs/glossaire/, une fiche par terme. Chaque fiche commence par un en-tête (term, english, et code quand un type du domaine l'implémente), suivi d'une ligne « En bref ». C'est cette phrase que l'application affichera quand on touche le terme. Dans l'autre sens, le code du domaine cite le chemin de la fiche en commentaire.
Documentation utilisateur dans docs/scenarios/, un fichier par tâche d'un joueur, au format Markdown avec Gherkin (.feature.md). Le même fichier se lit comme une page d'aide et pourra s'exécuter comme test de bout en bout.
Une seule source : le build copie ces fichiers dans l'application, et ces copies ne sont jamais commitées.

Amorce :

26 fiches de glossaire : les termes déjà utilisés dans le cadrage et les ADR (partie, coup, videau, équité, pli, identifiants GNU, branche, événement de partie…).
Un premier scénario, « Jouer une partie contre l'ordinateur ». Il décrit exactement le résultat attendu de l'étape 0d, et servira de guide de test quand nous la vérifierons ensemble sur le téléphone.

Deux nouveaux tests, lancés par make test :

tests/test_glossary.sh : forme des fiches, titre, ligne « En bref », traductions anglaises uniques, index, liens « Voir aussi » valides ;
tests/test_scenarios.sh : titre « Fonctionnalité », au moins un « Scénario », étapes qui commencent par un mot-clé Gherkin français, index.

CLAUDE.md, docs/organisation.md, la feuille de route et l'index des ADR y renvoient.

Comment

Une fiche par terme plutôt qu'un fichier unique : chaque terme a ainsi son propre lien, ce qui est utile à la fois depuis le code et depuis l'application (le terme touchable ouvre sa fiche). Les fusions sont aussi plus simples quand plusieurs agents ajoutent des termes.

Format des scénarios : le Markdown avec Gherkin est pris en charge par Cucumber. Il est lisible comme une page d'aide, et ses étapes (« Étant donné », « Quand », « Alors ») sont exécutables. L'outil qui les exécutera sera choisi avec le socle.

Vérification des tests eux-mêmes : chacun a été lancé dans les deux sens. Ils passent sur le contenu actuel, et échouent sur une copie volontairement abîmée : traduction anglaise en double, lien vers une fiche inexistante, étape « Puis » au lieu d'un mot-clé Gherkin.

Choix et compromis

Le lien du code vers le glossaire n'est pas encore testé : le domaine n'existe pas encore. Le test sera ajouté avec le premier type du domaine, à l'étape 0d.
L'exécution des scénarios attend le choix du socle : d'ici là, ils se déroulent à la main.
La syntaxe exacte du Markdown avec Gherkin en français (mots-clés de titre, déclaration de langue) sera confirmée avec l'outil d'exécution. S'il le faut, un ajustement mécanique des titres suffira.
Les fiches sont des contenus pédagogiques (CC BY-SA 4.0), rédigées par Claude Code et marquées « à relire » : leur ton relève de Pierre.

Risques et déploiement

Seuls de la documentation et des tests changent.

Le glossaire et les scénarios deviennent des contrats : une fiche ou un scénario mal formé fait échouer make test, ce qui est voulu.
Les définitions sont simplifiées pour des débutants. Une définition inexacte serait affichée telle quelle dans l'application, d'où la relecture demandée.

Retour arrière : annuler le commit de fusion.

Comment vérifier

git switch main && git pull
make lint && make test
ls docs/glossaire
less docs/glossaire/videau.md
less docs/scenarios/jouer-une-partie.feature.md

Hors périmètre

La relecture des fiches et du scénario par Pierre, et éventuellement par Philippe à l'Atelier du Huit.
L'affichage de l'aide et du glossaire dans l'application : il viendra avec l'interface (étape 0d pour le minimum, étape 1 pour la version soignée).
Les MR précédentes apparaissent encore « open » dans Gitea alors qu'elles sont fusionnées. Le diagnostic côté serveur reste à faire.

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

## Pourquoi Le code d'Ustagammon est en anglais (ADR 0007), mais l'interface et la documentation sont en français. Sans lien explicite entre les deux, un humain qui lit le code ne saurait pas que `Cube` est le videau, ni `Drop` le fait de passer. Les mots du jeu risqueraient aussi de varier entre le code, la doc et l'écran. Pierre a fixé trois exigences pour la documentation : - un glossaire où chaque mot a sa traduction anglaise, référencé par le code du domaine ; - une documentation utilisateur fondée sur des cas d'usage réels, versionnée, consultable dans l'application, et pouvant servir de base aux tests de bout en bout ; - une seule source de vérité, sans documentation dupliquée. Il a aussi rappelé que le travail de l'IA doit être encadré par des tests. ## Quoi **L'ADR 0008** (`docs/adr/0008-glossaire-et-scenarios-source-unique.md`) fixe trois règles : 1. **Glossaire** dans `docs/glossaire/`, une fiche par terme. Chaque fiche commence par un en-tête (`term`, `english`, et `code` quand un type du domaine l'implémente), suivi d'une ligne « En bref ». C'est cette phrase que l'application affichera quand on touche le terme. Dans l'autre sens, le code du domaine cite le chemin de la fiche en commentaire. 2. **Documentation utilisateur** dans `docs/scenarios/`, un fichier par tâche d'un joueur, au format Markdown avec Gherkin (`.feature.md`). Le même fichier se lit comme une page d'aide et pourra s'exécuter comme test de bout en bout. 3. **Une seule source** : le build copie ces fichiers dans l'application, et ces copies ne sont jamais commitées. **Amorce :** - 26 fiches de glossaire : les termes déjà utilisés dans le cadrage et les ADR (partie, coup, videau, équité, pli, identifiants GNU, branche, événement de partie…). - Un premier scénario, « Jouer une partie contre l'ordinateur ». Il décrit exactement le résultat attendu de l'étape 0d, et servira de guide de test quand nous la vérifierons ensemble sur le téléphone. **Deux nouveaux tests, lancés par `make test` :** - `tests/test_glossary.sh` : forme des fiches, titre, ligne « En bref », traductions anglaises uniques, index, liens « Voir aussi » valides ; - `tests/test_scenarios.sh` : titre « Fonctionnalité », au moins un « Scénario », étapes qui commencent par un mot-clé Gherkin français, index. `CLAUDE.md`, `docs/organisation.md`, la feuille de route et l'index des ADR y renvoient. ## Comment **Une fiche par terme plutôt qu'un fichier unique** : chaque terme a ainsi son propre lien, ce qui est utile à la fois depuis le code et depuis l'application (le terme touchable ouvre sa fiche). Les fusions sont aussi plus simples quand plusieurs agents ajoutent des termes. **Format des scénarios** : le Markdown avec Gherkin est pris en charge par Cucumber. Il est lisible comme une page d'aide, et ses étapes (« Étant donné », « Quand », « Alors ») sont exécutables. L'outil qui les exécutera sera choisi avec le socle. **Vérification des tests eux-mêmes** : chacun a été lancé dans les deux sens. Ils passent sur le contenu actuel, et échouent sur une copie volontairement abîmée : traduction anglaise en double, lien vers une fiche inexistante, étape « Puis » au lieu d'un mot-clé Gherkin. ## Choix et compromis - **Le lien du code vers le glossaire n'est pas encore testé** : le domaine n'existe pas encore. Le test sera ajouté avec le premier type du domaine, à l'étape 0d. - **L'exécution des scénarios attend le choix du socle** : d'ici là, ils se déroulent à la main. - **La syntaxe exacte du Markdown avec Gherkin en français** (mots-clés de titre, déclaration de langue) sera confirmée avec l'outil d'exécution. S'il le faut, un ajustement mécanique des titres suffira. - **Les fiches sont des contenus pédagogiques** (CC BY-SA 4.0), rédigées par Claude Code et marquées « à relire » : leur ton relève de Pierre. ## Risques et déploiement Seuls de la documentation et des tests changent. - Le glossaire et les scénarios deviennent des contrats : une fiche ou un scénario mal formé fait échouer `make test`, ce qui est voulu. - Les définitions sont simplifiées pour des débutants. Une définition inexacte serait affichée telle quelle dans l'application, d'où la relecture demandée. Retour arrière : annuler le commit de fusion. ## Comment vérifier ``` git switch main && git pull make lint && make test ls docs/glossaire less docs/glossaire/videau.md less docs/scenarios/jouer-une-partie.feature.md ``` ## Hors périmètre - La relecture des fiches et du scénario par Pierre, et éventuellement par Philippe à l'Atelier du Huit. - L'affichage de l'aide et du glossaire dans l'application : il viendra avec l'interface (étape 0d pour le minimum, étape 1 pour la version soignée). - Les MR précédentes apparaissent encore « open » dans Gitea alors qu'elles sont fusionnées. Le diagnostic côté serveur reste à faire. Generated with Claude Code https://claude.com/claude-code

pierre added 1 commit 2026-11-02 12:45:59 +00:00

ADR 0008 : glossaire et scénarios, source unique pour le code, l'aide et les tests 77ca5a60ca

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

pierre referenced this pull request

2026-11-02 12:53:45 +00:00

Scénarios en Gherkin standard validés par l'analyseur officiel ; ADR amendables #5

pierre manually merged commit 42ace839d2 into main

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: pierre/Ustagammon#4