# AGENTS.md ## Rôle Tu développes cette application avec une architecture stricte et non négociable : - Backend : Laravel - Frontend : React - Frontend language : TypeScript - Tests backend : Pest ou PHPUnit selon l’existant - Tests frontend / E2E / visuels : Playwright Tu ne proposes pas d’autre stack sauf demande explicite. Tu ne remplaces pas React par Blade-only, Livewire, Vue, Next.js ou autre. Tu ne déplaces pas la logique métier sensible côté frontend. --- ## Objectif Chaque fonctionnalité livrée doit être : - correcte fonctionnellement - cohérente avec l’architecture existante - testée côté backend si le backend change - testée côté navigateur si le frontend change - vérifiée visuellement quand le rendu est important - diagnostiquable rapidement en cas d’échec Une fonctionnalité n’est pas terminée tant qu’elle n’est pas prouvée par des tests ou des artefacts de vérification. --- ## Architecture imposée ### Backend - Utiliser Laravel de manière idiomatique. - Garder des contrôleurs fins. - Mettre la logique métier dans des services, actions, classes métier ou couches déjà utilisées dans le projet. - Utiliser des Form Requests pour la validation quand pertinent. - Utiliser Policies / Gates pour l’autorisation quand pertinent. - Utiliser Eloquent, Query Builder, Resources, DTOs ou conventions déjà présentes dans le projet. - Toute logique métier critique doit vivre côté Laravel. ### Frontend - Utiliser React avec TypeScript. - Préférer des composants petits, lisibles et réutilisables. - Séparer clairement : - composants UI - hooks - logique métier légère côté client - services d’appel API - Éviter les composants géants. - Éviter les useEffect inutiles ou fragiles. - Toujours gérer clairement les états : - loading - success - error - empty - Ne jamais dupliquer une règle métier backend dans le frontend sauf besoin strict d’UX, et dans ce cas la validation source reste côté backend. --- ## Règles de développement - Toujours analyser l’existant avant de coder. - Toujours respecter les conventions déjà présentes dans le projet. - Faire le changement le plus petit possible qui résout correctement le besoin. - Ne pas refactorer massivement sans demande explicite. - Ne pas ajouter de dépendance sans raison forte. - Ne pas laisser de code mort. - Ne pas laisser de logs temporaires inutiles. - Ne pas casser une convention du projet pour une préférence personnelle. - Quand un comportement est ambigu, choisir la solution la plus simple, testable et cohérente avec Laravel + React. --- ## Politique obligatoire de tests ### Principe général À chaque nouvelle fonctionnalité ou correction, tu dois déterminer quels tests sont nécessaires, puis les écrire. Tu ne te contentes jamais d’implémenter le code sans mettre à jour la preuve de fonctionnement. --- ## Tests backend obligatoires Créer ou mettre à jour des tests Laravel quand tu modifies : - routes - contrôleurs - Form Requests - validation - Policies / Gates - services métier - actions - commandes Artisan - events / listeners / jobs - persistance BDD - API - règles métier Les tests backend doivent couvrir selon le besoin : - cas nominal - cas d’erreur - validation - permissions / interdictions - écritures en base - régressions métier Quand la BDD change, utiliser des assertions explicites comme : - présence des données attendues - absence des données interdites - comptage des enregistrements - statut final attendu en base --- ## Tests frontend / navigateur obligatoires Créer ou mettre à jour des tests Playwright quand tu modifies : - pages - formulaires - composants critiques - parcours utilisateur - affichage conditionnel important - modales - tableaux - dashboards - bugs UI - interactions riches Les tests navigateur doivent couvrir selon le besoin : - chargement de page - affichage attendu - interaction utilisateur - saisie de formulaire - soumission - messages d’erreur - message de succès - navigation - régression visible importante --- ## Vérification visuelle obligatoire Quand le rendu visuel compte, ajouter une preuve visuelle. Exemples typiques : - page complète - carte - dashboard - formulaire important - modal - tableau critique - composant marketing - composant complexe - état d’erreur - état vide - responsive important Dans ce cas, utiliser Playwright avec capture ou comparaison de screenshot. Tu ne dis jamais qu’un rendu est bon sans preuve visuelle quand le rendu fait partie du besoin. --- ## Artefacts de diagnostic obligatoires en cas d’échec Quand un test navigateur ou visuel échoue, exploiter les artefacts disponibles. À conserver ou analyser selon le setup du projet : - screenshots d’échec - traces Playwright - vidéos d’échec - logs console navigateur - erreurs réseau - réponses API - logs Laravel - exceptions serveur Quand c’est utile, ajouter temporairement du logging ciblé pour diagnostiquer un problème, puis le retirer une fois le problème résolu. --- ## Vérification BDD Quand une fonctionnalité implique de la création, modification ou suppression de données : - ne jamais considérer le front seul comme preuve suffisante - vérifier aussi l’état réel de la base via tests backend ou assertions de persistance - préférer une preuve automatisée à une inspection manuelle - utiliser factories, seeders, états de test et données déterministes --- ## Workflow obligatoire pour chaque tâche Pour chaque tâche, tu dois suivre cet ordre : 1. Comprendre la structure existante 2. Identifier les fichiers impactés 3. Implémenter la modification 4. Ajouter ou mettre à jour les tests pertinents 5. Ajouter ou mettre à jour la vérification visuelle si nécessaire 6. Lancer les vérifications pertinentes 7. Lire les erreurs, logs et artefacts si ça échoue 8. Corriger jusqu’à obtenir un résultat cohérent 9. Résumer clairement le travail réalisé Tu ne t’arrêtes pas après avoir juste écrit le code. Tu dois essayer de prouver que ce que tu as fait fonctionne. --- ## Politique de correction autonome Quand une vérification échoue : - lire précisément le message d’erreur - analyser les logs et artefacts disponibles - identifier la cause la plus probable - corriger la cause - relancer les vérifications pertinentes Tu ne changes pas le code au hasard. Tu ne contournes pas les tests. Tu ne désactives pas une assertion juste pour faire passer la suite. --- ## Ce qu’il faut tester selon le type de modification ### Si tu modifies uniquement le backend Tu dois : - écrire ou mettre à jour les tests backend - vérifier la persistance ou le comportement métier - vérifier les droits d’accès si concernés ### Si tu modifies uniquement le frontend Tu dois : - écrire ou mettre à jour les tests Playwright pertinents - vérifier l’interaction principale - vérifier le rendu si visuellement important ### Si tu modifies backend + frontend Tu dois : - écrire ou mettre à jour les tests backend - écrire ou mettre à jour les tests Playwright - vérifier le flux complet - vérifier la persistance si la feature écrit en base - vérifier le rendu final si important --- ## Interdictions - Ne jamais livrer une feature UI importante sans test navigateur. - Ne jamais livrer une feature de saisie sans vérifier la persistance côté backend. - Ne jamais affirmer qu’une feature fonctionne sans preuve raisonnable. - Ne jamais ignorer une erreur console visible. - Ne jamais ignorer une erreur réseau visible pendant un test. - Ne jamais laisser un correctif partiel sans signaler les limites restantes. - Ne jamais créer une architecture parallèle non demandée. - Ne jamais dupliquer inutilement la logique. - Ne jamais préférer une solution rapide mais fragile à une solution simple et propre. --- ## Conventions de qualité - Préférer la clarté à la magie. - Préférer les conventions Laravel natives. - Préférer des composants React simples. - Préférer des fonctions courtes et lisibles. - Préférer des tests ciblés et compréhensibles. - Préférer des données de test déterministes. - Préférer des noms explicites. - Préférer des abstractions peu nombreuses mais solides. --- ## Attendu sur les tests Quand tu ajoutes une fonctionnalité, essaie de couvrir : ### Backend - happy path - validation - autorisation - persistance - régression principale ### Frontend - rendu initial - interaction clé - erreur utilisateur - succès - état final visible ### Visuel - capture du rendu final si le besoin est visuel --- ## Attendu sur le diagnostic Quand un test échoue, tu dois prioritairement regarder : 1. message d’erreur exact 2. stack trace 3. logs console navigateur 4. erreurs réseau 5. logs Laravel 6. état de la BDD 7. screenshot / trace Playwright --- ## Réponse finale attendue après une tâche Quand tu termines une tâche, retourne toujours : - un résumé court de ce qui a été fait - la liste des fichiers modifiés - la liste des tests ajoutés ou mis à jour - les vérifications exécutées - les points encore incertains ou non vérifiés - les éventuels artefacts utiles à consulter --- ## Préférence d’implémentation Par défaut : - backend robuste d’abord - frontend branché proprement ensuite - tests backend ensuite - tests Playwright ensuite - vérification visuelle ensuite si nécessaire --- ## Règle finale Le code n’est pas considéré comme terminé parce qu’il compile. Le code est considéré comme terminé quand il est : - cohérent - testé - vérifié - lisible - diagnostiquable facilement en cas d’échec