Consignes-cadre pour l'agent de développement

Projet Site e-commerce — Maison Crosnier · 22 juillet 2026

Ce document fixe les règles générales que l'agent doit respecter quoi qu'il code. Il ne décrit pas les fonctionnalités (voir les specs du dossier /dev) mais la manière de développer : architecture, qualité, sécurité, garde-fous. Il est indépendant de la stack ; les règles spécifiques à la technologie seront ajoutées une fois celle-ci choisie. Destiné à servir de fichier de règles de l'agent (ex. CLAUDE.md / AGENTS.md).

0. Posture de l'agent

• Les documents du dossier /dev font foi (synthèse, cartographie, contrat Gateway, modèle de données, exigences API caisse, direction artistique). En cas de contradiction, ils priment sur toute supposition.
• Demander plutôt que supposer : face à une ambiguïté ou à une décision d'architecture structurante non tranchée, poser la question au lieu de choisir en silence.
• Respecter les décisions actées (ADR) et ne pas réintroduire une option explicitement écartée.
• Signaler tout compromis, raccourci ou limite introduits, plutôt que de les masquer.

1. Architecture

• Site autonome, « caisse-ready ». Au lancement, le site fait autorité sur son catalogue, ses prix, ses commandes et ses avoirs (propriété temporaire). Il est conçu pour intégrer la caisse plus tard sans réécriture.
• Accès aux données derrière des interfaces (ports/adaptateurs). Jamais d'accès direct à une source de données depuis la logique métier : passer par un port. Implémenté aujourd'hui par la base du site, demain par un adaptateur caisse — sans toucher au métier.
• Conserver le modèle métier (produit, déclinaison, option, formule, groupe de choix, famille) et un champ refCaisse (nullable) sur produits, commandes, clients et avoirs, pour l'intégration future.
• Le paiement est isolé derrière une abstraction (prestataire PayPlug). Aucune dépendance directe au PSP dans le cœur applicatif.
• Séparer nettement présentation, logique métier et accès aux données. La logique métier ne vit ni dans les composants d'UI, ni couplée au stockage.
• Prévoir un back-office (gestion du catalogue + préparation des commandes) et un chemin de synchronisation site → caisse pour l'intégration.

2. Assets & front (règles strictes)

• Ne JAMAIS encoder un asset (image, police, icône) en base64 dans le HTML/CSS/JS. Toujours référencer un fichier externe.
• Logos et icônes en SVG de préférence (vectoriel, net à toutes tailles). Images matricielles optimisées (formats modernes, dimensions adaptées, loading="lazy").
• Pas de CSS ni de JS inline en volume : feuilles de style et scripts dans des fichiers externes, mis en cache.
• Design tokens centralisés (variables CSS : couleurs, typo, espacements, rayons). Aucune valeur de marque codée en dur et dispersée.
• Arborescence d'assets conventionnelle (ex. assets/img, assets/css, assets/js, assets/fonts). Chemins et noms de fichiers en minuscules et cohérents — le serveur (Apache) est sensible à la casse : un chemin qui marche en local peut casser en ligne.
• Favicon déclaré par fichiers (favicon.ico à la racine + PNG/SVG + apple-touch-icon), jamais en dur dans le code.
• Respecter la direction artistique (tokens, composants, interactions) sans inventer de styles hors charte.

3. Qualité de code

• Code lisible et maintenable : nommage clair, fonctions courtes, responsabilités uniques. Convention de langue (fr/en) fixée et cohérente.
• DRY : pas de copier-coller ; factoriser. Pas de code mort ni de fichiers inutiles.
• Gérer les erreurs explicitement : pas d'échec silencieux ; messages utiles ; états de chargement/erreur prévus côté UI.
• Configuration hors du code : URLs, clés, paramètres d'environnement dans des variables d'environnement / fichiers de config non versionnés.
• Dépendances minimales et justifiées : ne pas ajouter de bibliothèque lourde pour un besoin marginal.

4. Sécurité

• Aucun secret dans le dépôt ni côté client (clés PayPlug, identifiants caisse, etc.).
• Valider et échapper toutes les entrées : protection contre XSS, injections SQL, CSRF.
• Ne jamais manipuler de données de carte bancaire côté site : déléguer entièrement au PSP.
• HTTPS partout ; en-têtes de sécurité (CSP, HSTS, etc.).
• RGPD : ne collecter que le nécessaire, informer, prévoir les durées de conservation et les droits des personnes.

5. Performance

• Mobile-first et budget de performance : maîtriser le poids des pages, optimiser et dimensionner les images, différer le non-critique, lazy-load.
• Limiter les requêtes bloquantes ; mettre en cache ce qui peut l'être (dont le catalogue en cache, rafraîchi manuellement — cf. specs).

6. Accessibilité

• HTML sémantique, alt sur les images, hiérarchie de titres correcte.
• Navigation clavier complète, focus visibles, ARIA seulement quand nécessaire.
• Respecter prefers-reduced-motion : toute animation non essentielle doit pouvoir se désactiver.
• Contrastes suffisants (attention à l'or sur crème).

7. SEO

• Le site est responsable du SEO : URLs propres et lisibles, métadonnées (title/description), balisage sémantique et données structurées, sitemap.xml, gestion des redirections.

8. Versionnement & process

• Git : commits atomiques, messages clairs et explicites.
• .gitignore pour secrets, dépendances installées et artefacts de build ; ne pas versionner de fichiers volumineux inutiles.
• Historique propre ; pas de « commit fourre-tout ».

9. Garde-fous — ce que l'agent ne doit JAMAIS faire

• Encoder un asset en base64 dans le code.
• Court-circuiter les ports d'accès aux données (accès direct au stockage depuis la logique métier) ou coder en dur des données catalogue/prix (elles se gèrent en back-office).
• Contourner l'abstraction Gateway ou l'abstraction de paiement.
• Stocker un secret dans le dépôt ou l'exposer côté client.
• Introduire une dépendance lourde ou un choix d'architecture structurant sans validation.
• Utiliser des chemins d'assets sensibles à la casse incohérents.
• Livrer une fonctionnalité sans état d'erreur/chargement ni prise en compte du mobile et de l'accessibilité.
• Supposer une règle métier non spécifiée : demander.

À compléter une fois la stack choisie : conventions spécifiques au langage/framework, outillage (lint, formatage, tests), structure de projet détaillée, stratégie de tests.