Ustagammon/CLAUDE.md

CLAUDE.md — Règles du projet

Ce fichier est lu par Claude Code au début de chaque session. Il fixe le cadre du projet. Le cadrage complet est dans docs/cadrage.md, l'étape en cours dans docs/etape-0.md.

En début de session, lire docs/organisation.md, docs/feuille-de-route.md, la fin de docs/journal.md et les plans en cours dans docs/plans/, puis reprendre là où en est la feuille de route.

Le projet en bref

Ustagammon : application de backgammon pour apprendre et progresser, entièrement hors ligne.

• Moteur : GNU Backgammon (C, GPLv3). Il est la seule autorité pour les règles, les coups légaux, le videau et les évaluations. L'application ne réimplémente jamais de logique de backgammon de son côté.
• Cibles : Android (téléphone de test : Fairphone 4, arm64) et, si le prototype le valide, une PWA avec le moteur compilé en WebAssembly. Pas d'iOS.
• IA générative : en V1, uniquement des boutons qui copient un prompt contextualisé. Aucun appel réseau.
• Licence : tout le code sous GPLv3. Les contenus pédagogiques (leçons, textes) sous CC BY-SA 4.0.
• Langue : interface, contenus, commentaires de code et messages de commit en français.
• Communauté de départ : l'app sera d'abord diffusée auprès des joueurs de l'Atelier du Huit, café associatif à Cugnaux. Elle doit être accessible à de vrais débutants.
• Identité visuelle : définie par le brief créatif (https://claude.ai/artifact/36WMwZWqvMxXvSSVBJTgwd). Les choix de produit, de ton et d'identité appartiennent au porteur du projet ; le rôle de Claude Code est technique : les mettre en œuvre et signaler leurs conséquences techniques.

Contraintes de l'environnement (importantes)

• Machine de développement ancienne : ThinkPad Edge E420s (2011), CPU 2 cœurs, peu de RAM, disque dur classique (pas de SSD).
  • Compiler avec -j2 au maximum. Pas de builds parallèles lourds.
  • Ne jamais recompiler le moteur s'il n'a pas changé (dépendances make correctes, artefacts en cache).
  • Pas d'Android Studio, pas d'émulateur : build en ligne de commande, tests sur le vrai téléphone via adb.
  • Les chaînes d'outils lourdes (NDK, Emscripten, gnubg de référence) tournent dans des conteneurs Docker légers, construits une fois.
• Aucun service cloud : ni GitHub Actions ni CI distante. Le code est poussé sur un Gitea personnel, qui ne sert qu'à l'héberger. Tout se lance en local via make.
• Le développeur ne relit pas le code en détail (projet « vibe codé ») et n'est spécialiste ni du C, ni du NDK, ni de WebAssembly. Les tests automatiques sont le filet de sécurité principal : aucune fonctionnalité sans test.

Le contrat du Makefile

Toutes les opérations passent par make. Après chaque modification, lancer make lint puis make test ; ne déclarer une tâche finie que si les deux passent.

Commande	Rôle
make setup	Installe ou construit la chaîne d'outils (images Docker, dépendances). Idempotent.
make build	Compile le moteur (si nécessaire) puis l'application.
make test	Lance tous les tests, dont les positions de référence comparées à GNU Backgammon.
make lint	Vérifie le style et les erreurs courantes.
make deploy	Android : installe l'APK sur le téléphone (adb). Web : sert la PWA sur le réseau local.
make clean	Supprime les artefacts de build, sans toucher aux images Docker ni au cache du moteur.
make help	Liste les commandes, une ligne d'explication chacune.

Des cibles plus fines (make engine, make engine-wasm, make bench…) sont bienvenues si elles apparaissent dans make help.

Façon de travailler

0. Pilotage. La session principale est chef de projet technique : elle tient la feuille de route et délègue l'exécution à des sous-agents, selon docs/organisation.md. Toute tâche déléguée a son plan dans docs/plans/, écrit avant la délégation et complété à la clôture. Rien d'important ne vit seulement dans la mémoire d'une session.
1. Petites étapes vérifiables. Une étape = un résultat observable (une commande qui répond, un test qui passe). Présenter un plan court avant toute étape de plus d'une heure.
2. Tests d'abord pour le moteur. Les positions de référence sont évaluées avec le GNU Backgammon de bureau (en ligne de commande, dans Docker) et stockées dans tests/reference/. Le moteur embarqué doit concorder.
3. Expliquer simplement. Après chaque étape : ce qui a été fait, comment le vérifier soi-même (commande exacte), ce qui reste.
4. Ne jamais masquer un échec. Pas de test désactivé, pas de résultat simulé. Dire clairement ce qui bloque et la cause probable.
5. Commits fréquents, messages courts en français. Ne jamais pousser sur le dépôt distant sans demande explicite.
6. Dépendances : peu, maintenues, compatibles GPLv3. Signaler chaque nouvelle dépendance et sa licence.
7. Journal : docs/journal.md reçoit une entrée datée à la fin de chaque session (fait, décidé, reste à faire). Les décisions structurantes vont dans docs/decisions.md.

Sources du moteur

• GNU Backgammon : https://git.savannah.gnu.org/cgit/gnubg.git
• gnubg-nn (bibliothèque d'évaluation seule) : https://git.savannah.gnu.org/cgit/gnubg/gnubg-nn.git
• CBG, portage Android de GNU Backgammon (GPLv3, point de départ pour la compilation NDK) : https://github.com/clavierhaus/gnubg-android

Respecter les mentions de copyright ; créditer ces projets dans CREDITS.md.

Structure cible du dépôt (ajustable)

.
├── CLAUDE.md
├── Makefile
├── LICENSE              GPLv3
├── CREDITS.md
├── docs/                cadrage, feuille de route, organisation, étape en cours,
│                        plans des tâches déléguées, journal, décisions
├── engine/              sources du moteur (sous-module ou copie versionnée) + interface C
├── engine-cli/          programme en ligne de commande pour interroger le moteur
├── web/                 prototype puis application PWA
├── android/             prototype puis application Android
├── docker/              Dockerfiles des chaînes d'outils
└── tests/               tests, dont tests/reference/