# 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`, l'index des ADR (`docs/adr/README.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 ; identifiants du code en anglais.
- **Architecture et code** : simplicité d'abord, pas de sur-ingénierie ; domaine pur, moteur derrière `engine.h`, parties en journal d'événements ; règles complètes dans l'ADR 0007, à transmettre à chaque sous-agent.
- **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 supprimé à la clôture. Chaque décision structurante a son ADR dans `docs/adr/`. 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, sur une branche dédiée. Jamais de commit direct sur `main` : chaque changement passe par une merge request Gitea (`tea pulls create --login sans-pub`), décrite selon `docs/organisation.md`. Claude Code la fusionne lui-même une fois `make lint` et `make test` au vert.
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 un ADR (`docs/adr/`), jamais réécrit une fois accepté.

## 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, ADR, journal
├── 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/
```