1. Expression du besoin (User Stories + criteres d'acceptation testables)
2. BDD (scenarios Gherkin en francais, specifications executables)
3. TDD (tests avant le code, couverture metier)
4. TDD strict (cycle Red-Green-Refactor)
5. Tests unitaires (chaque regle metier isolee, documentation vivante)
6. Tests End-to-End (parcours utilisateur complet via Playwright)
7. Definition of Done (contrat partage, checklist non negociable)
8. Clean Code (noms explicites, fonctions courtes, pas de duplication)
9. SOLID (S, O, L, I, D — particulierement le D avec architecture hexagonale)
10. DDD (langage ubiquitaire en francais, domaine isole)
11. Architecture hexagonale (Ports & Adapters, dependances exterieur -> centre)
12. Cas d'usage (logique metier pure, zero dependance infra)
13. Documentation des API (OpenAPI)
14. Front-end (adaptation au canal, separation des responsabilites)
15. Separation contenu/presentation (DOM semantique vs CSS)
16. CI/CD (tests + build + deploiement automatiques, regression = blocage)
17. Documentation technique detaillee
18. Sprint en cours et principes Kanban
19. Configuration IA et pair programming avec l'IA
20. Metriques (management visuel des delivrables)
21. Observabilite (logs structures, alertes, tracabilite)
22. Securite (OWASP, validation entrees, gestion secrets, audit dependances)
23. Gestion des erreurs et resilience (erreurs typees, fail fast, pas de catch vide)
24. Performances et accessibilite (mesurer avant d'optimiser, HTML semantique)

• Chaque contribution doit tendre vers ces pratiques, pas les ignorer
• Signaler les ecarts : quand le code existant ne respecte pas une pratique du referentiel, le mentionner (sans forcement tout corriger d'un coup)
• Proposer des ameliorations : si une pratique du referentiel peut etre mieux appliquee, ou si une nouvelle pratique devrait y etre ajoutee, le suggerer au manager
• Boy Scout Rule : laisser le code un peu plus propre qu'on ne l'a trouve
• Ne pas regresser : ne jamais introduire un ecart volontaire par rapport au referentiel sans justification explicite

Le document est vivant. Quand un ecart ou une amelioration est identifie :

• Signaler l'ecart au manager (ex: "Le referentiel mentionne X mais le code fait Y")
• Proposer des ajouts si une pratique emerge du travail
• Ne pas modifier le referentiel sans validation du manager — c'est son document

---

| Commande | Effet | |----------|-------| | `GO US` | Jouer le role de l'agent US : reformuler la demande en User Story + CA, ecrire le fichier MD dans le sprint, mettre a jour `US en cours` (etape = `US-review`). | | `GO NEXT` | Avancer d'une etape. Faire la revue de l'etape livree, puis passer a l'etape suivante. Fonctionne pour toutes les transitions : US -> BDD -> TDD-back-end -> TDD-front-end. | | `GO FIN` | Enchainer toutes les etapes restantes sans pause. Faire les revues soi-meme. S'interrompre uniquement si un arbitrage est necessaire. | | `US VALIDEE` | La valeur metier a ete creee et delivree. Marquer l'US comme COMPLETEE : etape = `done`, renommer le fichier avec le suffixe `COMPLETE`. Ce n'est pas la validation de l'artefact US, c'est la cloture. |

Ces commandes sont desormais des skills Claude Code (fichiers dans `.claude/commands/`). Les invoquer avec `/go-prod`, `/go-debug`, etc. dans le chat.

| Skill | Effet | |-------|-------| | `/go-prod` | Analyse `git diff` : lint+Jest si contenu seul (~1 min), pipeline complet si code modifie (~20 min). Construit le message de commit. Demande au manager de lancer `npm run publie`. Ne jamais lancer `npm run publie` via Bash (pipeline ~20 min — depasse le timeout outil). | | `/go-debug` | Lire automatiquement `logs/publish-errors.txt` + `test-results.json` + `playwright-report/data.json`. Fonctionne pour tout contexte : Jest, BDD, E2E, pipeline. Identifier la cause racine, corriger. Jamais demander au manager de copier-coller des logs. Annoncer "Relance le pipeline." | | `/go-build` | tsc --noEmit puis next build. Rapport d'erreurs. | | `/go-metrics` | Collecter les metriques et afficher le rapport synthetique. | | `/go-sitemap` | Regenerer le plan du site + specs E2E apres ajout de page ou lien. | | `/go-css [containers\|off]` | Activer/desactiver les bordures debug CSS sur les containers listes. Script pur, pas de conversation LLM. | | `/go-help` | Afficher le guide de reference complet (commandes Claude + menu + skills + scenarios). |

---

Lors d'un GO NEXT, le Lead Dev discute avec l'utilisateur avant de passer a l'etape suivante :

1. Resumer : ce qui a ete compris de l'etape a venir (contexte, objectif).
2. Proposer : le plan pour l'etape (grandes lignes, pas le detail).
3. Demander validation : « Ca te convient ? », « As-tu des precisions ? ».
4. Attendre : ne pas lancer l'etape tant que l'utilisateur n'a pas confirme ou ajuste.

GO FIN : pas de mode interactif. Le Lead Dev enchaine les etapes et fait les revues lui-meme. S'interrompre uniquement si un arbitrage critique est necessaire.

Les tests ne sont pas listes a l'avance. Le developpeur TDD fait emerger le code :

1. Choisir le cas le plus simple : ecrire UN test qui echoue (RED).
2. Code minimal : implementer le strict minimum pour faire passer ce test (GREEN). Exemple : si on implemente `+` et que le premier test est `1+1`, la methode retourne `2` — c'est le code le plus simple.
3. REFACTOR : ameliorer sans casser le test.
4. Prochain petit pas : choisir le test suivant et recommencer.

Pas de liste prealable de tests — cela creerait un biais pour l'implementation. Les CA definissent le QUOI, les baby steps emergent du COMMENT.

• Reformuler l'echange en User Story (En tant que / Je souhaite / Afin de) + Criteres d'Acceptation testables.
• Ecrire le fichier `US-X.Y - Titre.md` dans le dossier du sprint courant (`data/A propos/Sprints/YYYY-MM-DD - Titre/`).
• Mettre a jour `data/A propos/Sprints/US en cours.md` : reference, titre, etape = `US-review`.
• Ne produit aucun code ni fichier `.feature`.

#### Format strict du fichier US

• Detail du critere
• Autre detail

• Detail

• Ecrire uniquement les fichiers `.feature` dans `tests/bdd/`.
• Gherkin en francais : `# language: fr`, mots-cles `Fonctionnalite`, `Scenario`, `Etant donne que`, `Quand`, `Alors`.
• Pour les Scenario Outline : utiliser les mots-cles anglais (contrainte du parseur playwright-bdd).
• Couvrir les CA de l'US. Pas de BDD artificiel : uniquement les comportements observables testables.
• Listes dans un step -> DocString (`"""..."""`), pas de tirets directs.
• DDD / langage ubiquitaire : si l'US exprime une longue phrase sans termes techniques, identifier le vocable du domaine (langage ubiquitaire) qui decrit la demande sans ambiguite. Utiliser ce vocabulaire dans les scenarios.
• Refactoriser : identifier dans les `.feature` existants les scenarios qui ne sont plus conformes a l'US en cours et les aligner. Ne pas laisser de scenarios obsoletes.
• Ne produit aucun code ni step definition.
• En fin de livraison : lister les steps utilises pour faciliter le TDD.

• Implementer la logique metier uniquement dans `utils/` (et `types/` si necessaire).
• TDD Baby Steps strict : RED -> GREEN -> REFACTOR, un test a la fois. L'agent TDD choisit le premier test, implemente seulement lui (RED, GREEN, REFACTOR), puis choisit le prochain petit pas, et ainsi de suite. Du vrai TDD. Les CA definissent le quoi, les baby steps definissent le comment.
• Couverture 100% sur le code modifie dans `utils/`.
• Ne touche pas a `app/`, `components/`, ni aux fichiers `.feature`.

• Implementer l'UI dans `app/` et `components/`.
• TDD Baby Steps strict (meme regle : l'agent choisit sa strategie d'implementation incrementale).
• Arbitrer Server Components vs Client Components selon le besoin (SSR, interactivite).
• Respecter la strategie RAW : structure DOM avec classes racine (camelCase), attributs `data-layout`.
• Tout element interactif doit avoir `e2eid="e2eid-{id}"` ou etre explicitement exclu (`e2eid={null}`).
• Nouvelle page / nouveau lien : mettre a jour le plan du site (`scripts/update-site-map.ts`), regenerer E2E (`npm run test:e2e:generate`).
• Ne touche pas a `utils/` ni aux `.feature`.

#### Contraintes sur les step definitions BDD

• Ne pas dupliquer : si un step existe deja dans un autre fichier, ne pas le redefinir.
• Steps partages : les steps de navigation generiques sont centralises (ex: `a-propos-du-site-tableau-de-bord.steps.ts`).
• Expressions Cucumber : n'echapper que les caracteres autorises (`{`, `}`, `(`, `)`, `\`, `/`, espaces). Ne pas utiliser `\+`.

• Applique uniquement le CSS dans `app/content-styles.css` et `app/globals.css`.
• Approche Data first : le DOM pilote le rendu. Styles par selecteurs (types HTML + classes racine + `data-*`), pas de surcharges ad hoc.
• Tokens (variables) dans `globals.css`. Aucune valeur en dur si un token existe.
• Ne modifie pas les composants ni les utils.

#### Brief Designer — ressources

| Ressource | Fichier | |-----------|---------| | Guide DOM et conventions | `app/raw/README.md` | | Structure des pages | `data/A propos/Documentation technique/4. Organisation du DOM.md` | | Hierarchie du site | `data/A propos/Documentation technique/5. Hierarchie du site.md` | | Tokens CSS | `app/globals.css` | | Styles types de contenu | `app/content-styles.css` | | Debug CSS | `app/css-debug.css` |

#### Strategie responsive (breakpoints)

• 1 seul breakpoint : `@media (min-width: 48rem)` (768px) — mobile portrait vs reste.
• Fluidite : privilegier `clamp()`, `min()`, `max()` pour tailles, padding, gap, typo.
• Grilles : `repeat(auto-fit, minmax(min(100%, Xpx), 1fr))` plutot que colonnes figees par breakpoint.
• Unites : `rem` pour le scaling proportionnel.
• Regle : entre 768px et grands ecrans, la fluidite suffit — pas de breakpoint intermediaire sauf necessite imperative.

#### Mode debug CSS → skill `/go-css`

• `/go-css hero sidebar` : afficher les containers listes avec bordure + fond (couleurs distinctes).
• `/go-css off` : remettre `--CouleurBordDeContainer` a transparent et desactiver les surcharges debug.
• Fichier dedie : `app/css-debug.css` — ne pas polluer `content-styles.css` ni `globals.css`.

---

• Principes Clean Code (SOLID, pas de duplication, noms explicites)
• Tests TDD/BDD avec couverture 100%
• Cycle RED -> GREEN -> REFACTOR respecte
• Scenarios BDD valides et coherents avec les BDD existants

• Corriger ecarts mineurs (typographie, structure)
• Retourner taches non conformes avec commentaires precis
• BLOQUER si couverture < 100%

Lorsqu'on repasse sur du code qui ne respecte pas les consignes, faire nettoyer en passant (corriger soi-meme si mineur).

Voir la memoire persistante (`revue-specifique.md`) pour les verifications liees a ce projet (plan du site, e2eID, E2E, DoD, responsive).

---

• `data/A propos/Sprints/US en cours.md` : reference, titre, etape du workflow. Parse par le site pour le board Kanban.
• Fichiers US : `US-X.Y - Titre.md` dans le dossier sprint. Renommes avec `COMPLETE` quand clotures.
• Sprint goal : `00 - Sprint goal et contexte.md` dans chaque dossier sprint.

| Etape dans `US en cours.md` | Signification | Board Kanban | |------------------------------|---------------|--------------| | `US-review` | US redigee, en attente de validation du manager | Colonne US, avec loupe | | `US` | US en cours de redaction | Colonne US | | `BDD` | Scenarios BDD en cours | Colonne BDD | | `TDD-back-end` | Implementation back-end en cours | Colonne TDD-back-end | | `TDD-front-end` | Implementation front-end en cours | Colonne TDD-front-end | | `done` | US completee (valeur metier delivree) | Colonne Fait |

Le suffixe `-review` (ex: `BDD-review`) place le post-it dans la colonne correspondante avec une loupe.

Quand un refactoring casse des BDD existants et que le comportement a change volontairement (pas une regression), remonter a l'US d'origine et la marquer obsolete :

• Ajouter en tete du fichier MD : `> OBSOLETE — Remplacee par US-X.Y suite au refactoring Z`
• Permet de distinguer evolution volontaire vs regression

---

Meme pour une correction technique (CSP, config, refactoring) :

1. RED : ecrire un test qui echoue (ou verifier qu'un test existant couvre le cas)
2. GREEN : code minimal pour faire passer le test
3. REFACTOR : ameliorer en gardant tests verts

• Cycle RED -> GREEN -> REFACTOR — UN TEST A LA FOIS
• Couverture 100% obligatoire sur le code modifie dans `utils/`
• Pas de code sans test, meme hors tunnel

• Tests BDD : scenarios en francais, comportements observables testables
• Steps non dupliques entre fichiers. Steps generiques definis une seule fois.
• Pas de BDD artificiel : uniquement la ou ca apporte de la valeur.

• `npm run lint` doit produire 0 erreur, 0 warning
• Obligation avant toute livraison

• Pas de `any` : typage explicite ; `unknown` + gardes si besoin ; exceptions documentees (ex. tables Gherkin, mocks).
• Regle `@typescript-eslint/no-explicit-any` respectee sur le code modifie ; dette existante traitee en Boy Scout.

• Si le contrat API change (endpoints, structure JSON), incrementer la version dans `utils/vitrine/openApiSpec.ts`
• Version API = MAJOR.MINOR (ex: 1.0, 1.1, 2.0)
• MAJOR : breaking change (suppression, renommage)
• MINOR : ajout retrocompatible

• Ne pas lancer le build ni la suite de tests complete pendant le tunnel (sauf tests pertinents a l'etape)
• C'est a la cloture de l'US (etape = `done`) qu'on lance build et suite de tests complete
• Metriques : `npm run metrics:collect` lors de chaque build

---

• utils/ = coeur metier (readers, builders, parsers) - zero dependance sur Next.js/React
• app/ + components/ = adaptateurs front-end (Server Components, Client Components)
• app/api/ = adaptateurs API REST
• Les dependances vont toujours de l'exterieur (app) vers le centre (utils)

Le site utilise 8 types de contenu definis dans `utils/vitrine/pageReader.ts` : titre, video, texteLarge, domaineDeCompetence, callToAction, groupeDeBoutons, listeDeTemoignages, listeDeDetournementsVideo

Chaque page est composee a partir de fichiers JSON dans `data/` qui referencent ces types.

• Noms metier en francais dans le code (variables, fonctions, types, interfaces)
• camelCase pour les classes CSS des types de contenu (ex: `.domaineDeCompetence`, `.hero`)
• Un seul nom par type de contenu : meme nom dans JSON, TypeScript et CSS — pas de variante entre couches
• e2eID : convention lettre+numero (h=header, b=bouton, v=video, a=action, c=competence, l=lien)

Tout element interactif (lien, bouton, CTA, carte cliquable) doit avoir un identifiant E2E, sauf exclusion explicite.

| Contexte | Propriete | Format | |----------|-----------|--------| | JSON | `e2eID` (camelCase) | `string \| null` | | JSX | `e2eid` (minuscules) | `"e2eid-{id}"` ou `{null}` |

• Elements issus du JSON : utiliser l'`e2eID` fourni par les donnees, ne pas inventer.
• Exclusion volontaire : `e2eid={null}` (JSX) ou `e2eID: null` (JSON).
• Ne pas utiliser `data-testid` ni `data-e2eid`. Playwright cible l'attribut `e2eid`.
• Apres nouvelle route ou nouveau lien : (1) `scripts/update-site-map.ts`, (2) `npm run test:e2e:generate`, (3) traiter `e2e-ids-pending.json`.

• Les types de contenu sont styles uniquement dans `app/content-styles.css` (CSS global)
• Tokens (couleurs, tailles) dans `app/globals.css`
• Pas de `.module.css` pour les types de contenu
• Exceptions : Maintenance, Metrics et A propos peuvent avoir du CSS dedie

• TDD strict : RED -> GREEN -> REFACTOR. L'agent TDD fait emerger le code par baby steps, dans l'ordre qu'il choisit (du plus simple au plus complexe)
• Couverture 100% visee sur `utils/`
• BDD : scenarios Gherkin en francais dans `tests/bdd/*.feature`
• E2E : specs generees automatiquement (ne pas modifier manuellement `tests/end-to-end/*.spec.ts`)
• ESLint : 0 erreur, 0 warning obligatoire avant toute livraison

| Fichier | Script generateur | |---------|-------------------| | `data/_Pages-Liens-Et-Menus.json` | `scripts/update-site-map.ts` | | `data/plan-du-site.json` | `scripts/update-site-map.ts` | | `data/A propos/Documentation technique/9. Hierarchie containers par page.md` | `npm run css:hierarchy` | | `tests/end-to-end/*.spec.ts` | TI `generate-e2e-navigation.integration.test.ts` |

Menu header : le fichier `data/_Menus-header.json` est la source editable du menu. Son contenu est fusionne dans `_Pages-Liens-Et-Menus.json` lors du build. Pour modifier le menu, editer `_Menus-header.json` puis regenerer.

Le manager lance `npm run publie` dans son terminal. En cas d'echec :

• Le pipeline ecrit `logs/publish-errors.txt` (etape en echec, scenarios KO)
• Le manager tape `GO DEBUG` dans Claude — pas de copier-coller
• Claude lit les logs, corrige, annonce "Relance le pipeline."

1. Sources de verite : `logs/publish-errors.txt` (etape en echec) → `test-results.json` (details Jest) → `playwright-report/data.json` (details E2E/BDD). Dans cet ordre, sans relancer les tests pour retrouver les erreurs.
2. Identifier le probleme metier/fonctionnel AVANT la solution technique
3. Solution simple avant solution complexe
4. Pas de corrections multiples en parallele
5. Si echec multiple → repartir de zero avec User Story -> Plan de test -> TDD
6. Lors d'un `GO TESTS` : lire les erreurs soi-meme, corriger, relancer — ne jamais demander au manager de copier-coller des logs