AI-Assisted Development PrestaShop 9 : Guide Complet

Tu génères du code PrestaShop avec une IA et tu passes plus de temps à corriger les erreurs architecturales qu’à développer — voici comment PrestaShop 9.2 règle ce problème une fois pour toutes.

Pour approfondir ce sujet, consultez notre article Guide complet Google Search Console pour PrestaShop.

Pour approfondir ce sujet, consultez notre article Facturation électronique 2026 : le guide technique complet pour mettre PrestaShop et WooCommerce en conformité avant l’échéance.

Tu travailles sur PrestaShop 9 et tu utilises un assistant IA — Copilot, Cursor, Claude Code ou Gemini CLI — pour accélérer ton développement. Résultat en l’absence de guidance explicite : l’assistant te génère du code basé sur ObjectModel là où l’architecture attend du CQRS, il ignore les contraintes multiboutique, et il appelle la base de données directement depuis un contrôleur Symfony. En production, ça donne des régressions difficiles à tracer, des refus en code review, et des heures de correction. PrestaShop 9.2 apporte une réponse structurée à ce problème : un système de fichiers de contexte intégrés dans les dépôts officiels, conçu pour que chaque outil IA génère du code conforme dès le premier jet. Voici tout ce que tu dois savoir pour en tirer le maximum.

Pourquoi PrestaShop 9 avait besoin d’un système de contexte IA natif

Avant d’entrer dans la mécanique, il faut comprendre pourquoi un contexte IA spécifique à PrestaShop est indispensable, et pas simplement utile.

La complexité architecturale de PrestaShop : un défi pour les LLM

PrestaShop est une plateforme e-commerce open source dont le code a plus de 15 ans d’histoire. La base de code mélange une couche legacy reposant sur ObjectModel — un ORMmaison fortement couplé — et une architecture moderne basée sur Symfony, CQRS (Command Query Responsibility Segregation), des services de domaine et des contrôleurs routés. Cette coexistence est intentionnelle : la migration est en cours, progressive, domaine par domaine.

Un Large Language Model entraîné sur des millions de dépôts GitHub a une probabilité statistiquement élevée de générer du code ObjectModel pour PrestaShop, car c’est le pattern dominant dans les anciennes versions (1.6, 1.7) que les modèles ont massivement ingérées. Sans guidance explicite, le LLM ne sait pas qu’en PrestaShop 9, un nouveau handler de commande CQRS ne doit jamais instancier directement un ObjectModel.

Les contraintes sont multiples et interdépendantes :

• La séparation stricte des couches : Core Domain, Adapter, PrestaShopBundle et Legacy sont des zones étanches avec des règles de dépendance précises.
• Le pattern CQRS obligatoire pour toute nouvelle fonctionnalité Back Office : chaque opération de lecture passe par une Query, chaque mutation par une Command.
• Les contraintes multiboutique : toute entité qui peut varier par boutique doit implémenter la logique de shop context, sans exception.
• Les classes final par défaut, le strict typing PHP 8.x, l’absence d’ObjectModel dans le nouveau code.
• Les conventions de nommage des services Symfony, des routes et des opérations CQRS.

Sans source de vérité unique, chaque développeur qui utilise un outil IA doit soit passer 30 minutes à tout ré-expliquer en prompt, soit accepter du code non conforme qu’il devra corriger manuellement.

Ce que l’IA produit sans contexte : une liste de problèmes concrets

L’architecture du système de contexte IA dans PrestaShop 9.2

Le système repose sur un principe simple mais puissant : une source de vérité centrale en Markdown, et des fichiers-pointeurs à la racine du dépôt pour chaque outil IA. Le contenu n’est jamais dupliqué.

Le dossier .ai/ : la source de vérité unique

Dans le dépôt PrestaShop/PrestaShop, disponible depuis la version 9.2, l’ensemble du contexte est centralisé dans un dossier .ai/ à la racine du projet. Sa structure hiérarchique est la suivante :

• .ai/CONTEXT.md : Le point d’entrée global. Il couvre l’architecture générale du projet (les 4 couches), les conventions CQRS, les standards de code universels (strict types, classes final), et fournit un index vers tous les contextes de domaine et de composant.
• .ai/STRUCTURE.md : Documente les conventions du dossier .ai/ lui-même et fournit le template canonique pour rédiger un nouveau CONTEXT.md.
• .ai/GOTCHAS.md : Recense les pièges architecturaux fréquents et les patterns délicats qui ne sont pas évidents à la lecture du code.
• .ai/MULTISTORE.md : Guidance spécifique à la gestion multiboutique — le sujet le plus complexe et le plus souvent mal géré par les assistants IA.
• .ai/Domain/{NomDomaine}/CONTEXT.md : Un fichier de contexte par domaine métier. Le dépôt principal en compte 57, couvrant des domaines tels que Cart, Order, Product, Customer, Carrier, Currency, etc.
• .ai/Component/{NomComposant}/CONTEXT.md : Un fichier de contexte par composant technique transversal. 22 composants sont documentés : CQRS, Grid, Form, Hook, Twig Extensions, Console, etc.
• .ai/skills/ : Templates de tâches réutilisables pour les assistants IA. Scaffolding d’un nouveau handler CQRS, création d’une définition Grid, ajout d’un domaine — ces templates guident l’IA étape par étape.
• .ai/generated/ : Index pré-générés en Markdown. Ces fichiers listent de manière exhaustive les routes existantes (routes.md), les entités (entities.md), les commandes et queries CQRS (cqrs.md) et les hooks (hooks.md). Ils permettent à l’IA de découvrir l’existant sans avoir à crawler tout le code source.

Le template canonique des fichiers CONTEXT.md

Chaque fichier de contexte, qu’il soit de domaine ou de composant, suit un template standardisé défini dans .ai/STRUCTURE.md. Ce template comporte les sections suivantes :

• Purpose : Ce que couvre ce domaine ou composant.
• Architecture overview : Classes clés, services et leurs relations.
• Coding standards : Conventions spécifiques à ce périmètre.
• Do / Don’t : Règles explicites avec exemples positifs et négatifs.
• Testing expectations : Quels tests sont obligatoires (unit, Behat, integration).
• Canonical examples : Fichiers de référence à suivre dans le dépôt.
• Related skills : Liens vers les templates de tâches réutilisables.

Les fichiers-pointeurs : l’approche agnostique

Plutôt que de maintenir une configuration séparée pour chaque outil IA, PrestaShop adopte une approche agnostique. À la racine du dépôt, des fichiers-pointeurs minimalistes redirigent chaque outil vers le dossier .ai/. Ces fichiers ne contiennent pas le contexte eux-mêmes : ils se contentent de pointer vers .ai/CONTEXT.md.

La conséquence pratique est directe : quand l’équipe PrestaShop met à jour .ai/Domain/Order/CONTEXT.md, tous les outils IA bénéficient immédiatement de la mise à jour, sans aucune action de la part des développeurs. La maintenance est centralisée.

La chaîne de navigation de l’IA

Quand tu ouvres le dépôt PrestaShop dans Cursor ou que tu lances Claude Code sur un fichier lié au domaine Cart, voici la chaîne de navigation que l’outil IA suit automatiquement :

1. L’outil lit son fichier-pointeur à la racine (ex. CLAUDE.md ou .cursor/rules/prestashop-context.mdc).
2. Il suit la référence vers .ai/CONTEXT.md, qui lui donne l’architecture globale et l’index des domaines et composants.
3. En fonction du fichier sur lequel tu travailles, il charge le contexte de domaine correspondant (ex. .ai/Domain/Cart/CONTEXT.md).
4. Il charge également les contextes de composants pertinents (ex. .ai/Component/CQRS/CONTEXT.md et .ai/Component/Form/CONTEXT.md).
5. Il consulte .ai/GOTCHAS.md et .ai/MULTISTORE.md pour les contraintes transversales.
6. Il vérifie les index générés pour découvrir les commandes, queries, routes et hooks existants avant de créer du nouveau code.

Les dépôts supportés et leurs structures de contexte

PrestaShop/PrestaShop (Core)

C’est le dépôt principal qui bénéficie du contexte IA le plus complet. La hiérarchie .ai/ avec ses 57 domaines et 22 composants est disponible à partir de la version 9.2 sur la branche develop. Si tu travailles sur du code core PrestaShop, c’est ce dépôt que tu dois ouvrir directement dans ton IDE pour bénéficier du contexte automatique.

PrestaShop/ps_apiresources

Ce module gère l’exposition des ressources via l’API Admin basée sur API Platform et CQRS. Sa structure de contexte est plus simple : un seul fichier CONTEXT.md à la racine, accompagné de ses fichiers-pointeurs. Le contenu couvre les 8 attributs d’opération CQRS (CQRSGet, CQRSCreate, CQRSPartialUpdate, CQRSDelete, etc.), les conventions de nommage des URI et des scopes OAuth2, les règles de mapping des propriétés et les attentes de tests avec ApiTestCase.

PrestaShop/hummingbird

Le thème officiel moderne de PrestaShop. Son fichier CONTEXT.md documente l’architecture du thème (Smarty pour les templates, SCSS avec méthodologie BEM, TypeScript strict sans jQuery, Vite comme bundler), le système de liaisons DOM basé sur des attributs data-ps-*, l’architecture des couches SCSS, et les exigences d’accessibilité. Un point notable : le contexte hummingbird interdit explicitement toute logique métier dans les templates de thème — une règle que les LLM violent régulièrement sans guidance.

Configuration outil par outil : ce que tu dois savoir concrètement

Claude Code

Claude Code lit automatiquement CLAUDE.md à la racine du dépôt à chaque nouvelle session. Ce fichier pointe vers .ai/CONTEXT.md. Aucune configuration manuelle n’est requise. Si tu travailles sur un domaine spécifique, tu peux mentionner explicitement le domaine dans ton prompt pour que Claude charge en priorité le contexte de domaine correspondant. Par exemple : « En suivant le contexte du domaine Order, crée un nouveau CommandHandler pour annuler une commande. »

Cursor IDE

Cursor charge automatiquement les règles définies dans .cursor/rules/prestashop-context.mdc dès l’ouverture du projet. Tu n’as rien à faire. Si tu ouvres un fichier appartenant au domaine Product, Cursor chargera progressivement le contexte associé. Dans la pratique, il est utile d’avoir les fichiers du domaine sur lequel tu travailles ouverts dans l’éditeur pour que Cursor les prenne en compte dans sa fenêtre de contexte.

GitHub Copilot

Copilot lit le fichier .github/copilot-instructions.md et c’est valable aussi bien dans VS Code que dans les IDEs JetBrains (IntelliJ IDEA, PhpStorm) avec l’extension Copilot installée. Le fichier pointe vers .ai/CONTEXT.md. La qualité du code généré par Copilot dans PrestaShop 9.2+ devrait être significativement meilleure que dans les versions antérieures, car le LLM reçoit maintenant les règles CQRS et les contraintes de couches avant de générer.

Windsurf IDE

Windsurf lit .windsurfrules à la racine du projet. Le mécanisme est identique aux autres outils. Windsurf est particulièrement efficace pour ce type de guidance car il supporte des contextes de règles multi-niveaux par défaut.

Gemini CLI

Gemini CLI (outil en ligne de commande de Google) lit GEMINI.md. Cet outil est davantage orienté workflows en terminal, mais il bénéficie de la même guidance que les IDEs. Si tu l’utilises pour du scaffolding ou des refactorings en batch, le contexte est disponible automatiquement.

Assistants web (ChatGPT, Claude.ai, Gemini en interface web)

Ces interfaces ne lisent pas directement les fichiers de ton dépôt. Pour bénéficier du contexte, tu dois copier-coller manuellement le contenu de .ai/CONTEXT.md (et des contextes de domaine pertinents) dans ta conversation, en tant que message système ou premier message utilisateur. C’est fastidieux mais efficace pour des questions ponctuelles. Pour un travail soutenu, je te recommande de passer à un outil IA intégré à l’IDE qui gère ce chargement automatiquement.

Utilisation des fichiers générés et des skills

Les index générés dans .ai/generated/

Ces fichiers sont des atouts souvent sous-estimés. Avant de créer une nouvelle Command CQRS, demande explicitement à ton outil IA de consulter .ai/generated/cqrs.md pour vérifier qu’une commande équivalente n’existe pas déjà. Même logique pour les routes (routes.md), les entités Doctrine (entities.md) et les hooks (hooks.md).

Cette approche évite deux erreurs fréquentes : créer un doublon d’une commande déjà existante, ou créer une commande dont le nommage ne respecte pas les conventions du domaine.

Les skills dans .ai/skills/

Les skills sont des templates de tâches réutilisables pour les opérations récurrentes. Ils encodent la séquence d’étapes à suivre pour des travaux standardisés : ajouter une nouvelle CQRS command, créer une définition Grid, scaffolder un nouveau domaine, ajouter un hook. Avant de demander à ton outil IA de réaliser une tâche structurée de ce type, vérifie si un skill correspondant existe dans .ai/skills/. Les skills produisent une sortie plus cohérente que les prompts génériques.

Bonnes pratiques terrain pour maximiser la qualité du code généré

Travailler avec les bons fichiers ouverts dans l’éditeur

La plupart des outils IA contextuels (Cursor, Copilot, Claude Code) utilisent les fichiers ouverts dans l’éditeur comme signal de contexte. Si tu travailles sur le domaine Order, ouvre simultanément le fichier que tu modifies, .ai/Domain/Order/CONTEXT.md et .ai/Component/CQRS/CONTEXT.md. La fenêtre de contexte de l’outil sera peuplée des bonnes informations.

Relire systématiquement le Do/Don’t du domaine

Avant de valider du code généré, lis la section Do/Don’t du CONTEXT.md du domaine concerné. C’est une liste courte et binaire des règles les plus importantes. Si le code généré viole l’un des « Don’t », rejette-le et reformule ton prompt en citant la règle violée.

Vérifier les contraintes multiboutique

La multiboutique est le sujet le plus souvent mal géré par les LLM sur PrestaShop, même avec le contexte chargé. Chaque fois que tu crées ou modifies une entité qui peut varier par boutique, vérifie que le code généré :

• Utilise ShopConstraint dans les commandes CQRS qui affectent des entités liées à une boutique.
• Passe par le ShopContext approprié dans les adaptateurs.
• Gère les cas de boutique unique, groupe de boutiques et toutes boutiques.

Demande explicitement à l’IA de consulter .ai/MULTISTORE.md lorsque tu sais que ton code touche au périmètre multiboutique.

Ne jamais sauter la revue de code

Le contexte IA améliore significativement la qualité du premier jet, mais il ne remplace pas la revue humaine. Les fichiers de contexte eux-mêmes le précisent : le code généré par IA soumis comme contribution PrestaShop doit respecter exactement les mêmes standards que tout autre code. Les mainteneurs du projet appliquent les mêmes critères de revue, sans exception pour les contributions assistées par IA.

Maintenir les fichiers de contexte à jour

Si tu travailles sur un fork de PrestaShop ou sur un module privé pour lequel tu as créé tes propres fichiers de contexte, intègre leur mise à jour dans ton workflow de développement. Un fichier de contexte obsolète est pire qu’un fichier absent : il induit l’IA en erreur avec des informations périmées. La documentation officielle fournit une page dédiée à la maintenance des contextes.

Créer un système de contexte IA pour ton propre module

L’approche de PrestaShop peut être répliquée sur tes modules tiers ou modules clients. Si tu développes un module PrestaShop 9 avec une architecture métier non triviale, voici comment implémenter un contexte IA local.

Structure minimale recommandée pour un module

• CONTEXT.md à la racine du module : architecture du module, patterns utilisés, règles de domaine spécifiques.
• CLAUDE.md à la racine : pointe vers CONTEXT.md.
• .github/copilot-instructions.md : pointe vers CONTEXT.md.
• .cursor/rules/module-context.mdc : pointe vers CONTEXT.md.

Si ton module est complexe avec plusieurs domaines, crée un sous-dossier .ai/ et décompose les contextes par domaine en t’inspirant du template canonique de .ai/STRUCTURE.md du core.

Ce que doit contenir le CONTEXT.md d’un module

Au minimum, documente les points suivants dans le CONTEXT.md de ton module :

• La version de PrestaShop ciblée et les dépendances majeures.
• L’architecture du module (patterns utilisés : CQRS ou legacy ObjectModel, services Symfony, hooks principaux).
• Les entités de base de données et leur structure (tables créées, relations).
• Les hooks utilisés et leur rôle.
• Les règles de validation métier propres au module.
• Les pièges spécifiques (contraintes de compatibilité, edge cases multiboutique, etc.).
• Les fichiers de référence à suivre comme exemples canoniques.

Impact sur la qualité de code et les Web Vitals : ce que le contexte IA ne couvre pas

Il est important de délimiter le périmètre du système de contexte IA de PrestaShop. Il couvre l’architecture PHP et la conformité aux patterns du framework. Il ne couvre pas :

• La performance front-end et les Core Web Vitals (LCP, CLS, INP). Ces aspects dépendent de la couche thème, des assets et de la configuration serveur — sujets qui relèvent de la documentation performance PrestaShop 9, pas du contexte IA.
• La sécurité applicative. Les fichiers de contexte mentionnent des règles générales, mais l’audit de sécurité reste une discipline distincte.
• La compatibilité PHP. PrestaShop 9 requiert PHP 8.1 minimum. Les contextes IA peuvent générer du code PHP 8.x conforme, mais la vérification de compatibilité avec ta version de production reste de ta responsabilité.
• L’optimisation des requêtes SQL. Le contexte IA guide vers les bons patterns (QueryHandler, repository), mais il n’audite pas les performances des requêtes générées.

Questions Fréquentes (FAQ)

Le système de contexte IA est-il disponible dans PrestaShop 8 ?

Non. Le dossier .ai/ complet avec la hiérarchie de domaines et de composants est disponible à partir de PrestaShop 9.2 sur la branche develop. Pour les versions 8.x, aucun contexte natif n’est fourni. Tu peux créer manuellement des fichiers de contexte en t’inspirant de la structure 9.2, mais tu n’auras pas les 57 domaines ni les 22 composants documentés.

Les fichiers de contexte ralentissent-ils mon IDE ou consomment-ils ma fenêtre de contexte LLM ?

La consommation de tokens est réelle mais maîtrisée. Les outils comme Cursor et Claude Code chargent les contextes de manière sélective — en priorité les contextes des domaines et composants liés aux fichiers ouverts. Le CONTEXT.md root fait quelques centaines de lignes. Un contexte de domaine en fait généralement entre 100 et 300. La plupart des modèles modernes avec des fenêtres de contexte de 100K+ tokens gèrent cela sans difficulté. En pratique, aucun ralentissement notable n’est observé dans les IDEs supportés.

Dois-je utiliser CQRS pour mon module tiers si je veux bénéficier du contexte IA ?

Non, le contexte IA est agnostique à l’architecture de ton module. Il documente les patterns du core PrestaShop pour que l’IA génère du code core conforme. Pour un module tiers, tu peux utiliser ObjectModel, Doctrine, ou CQRS selon ce qui est approprié. Le contexte IA du core ne s’applique pas au code de ton module — c’est pourquoi il est recommandé de créer ton propre CONTEXT.md de module pour documenter tes propres patterns.

Comment le contexte IA gère-t-il la coexistence legacy/modern dans PrestaShop 9 ?

C’est précisément l’un des apports les plus importants des fichiers de contexte. Le CONTEXT.md root et les fichiers GOTCHAS.md explicitent les frontières entre les zones legacy (contrôleurs Legacy, ObjectModel) et les zones modernes (Symfony, CQRS, Doctrine). Ils précisent quand il est acceptable de faire appel à une couche legacy depuis du code modern (via les adaptateurs), et quand c’est une violation architecturale. Sans ce contexte, les LLM ne peuvent pas distinguer les deux zones.

Puis-je contribuer à améliorer les fichiers de contexte ?

Oui. Les fichiers .ai/ font partie du dépôt open source PrestaShop et sont soumis aux mêmes règles de contribution que le code. Tu peux soumettre une pull request pour améliorer un contexte de domaine, ajouter un piège manquant dans GOTCHAS.md ou créer un nouveau skill. La documentation officielle explique comment contribuer à la documentation du projet.

Les fichiers de contexte sont-ils mis à jour à chaque release PrestaShop ?

Les fichiers de contexte .ai/ sont maintenus en continu sur la branche develop par l’équipe PrestaShop et les contributeurs. Ils sont mis à jour quand l’architecture évolue, quand de nouveaux domaines sont migrés vers CQRS, ou quand des pièges récurrents sont identifiés. Ils ne suivent pas un cycle de release figé mais une maintenance continue comme la documentation de code.

GitHub Copilot lit-il vraiment les fichiers .github/copilot-instructions.md automatiquement ?

Oui, depuis que GitHub a généralisé le support des custom instructions pour Copilot dans VS Code et JetBrains. Le fichier est lu automatiquement dès que le projet est ouvert avec l’extension Copilot activée. Tu peux vérifier que les instructions sont bien chargées dans le panneau Copilot Chat de ton IDE.

Que se passe-t-il si je travaille sur du code qui touche plusieurs domaines simultanément ?

C’est fréquent en PrestaShop : une opération de commande peut toucher les domaines Order, Product et Customer simultanément. Dans ce cas, la meilleure approche est de charger explicitement les contextes des domaines concernés dans ton prompt, ou de t’assurer que les fichiers de ces domaines sont ouverts dans ton éditeur. Pour Claude Code et Cursor, tu peux référencer directement les chemins des fichiers de contexte dans ton prompt.

Le contexte IA empêche-t-il totalement les erreurs de génération ?

Non. Il réduit significativement leur fréquence, mais ne les élimine pas. Les LLM peuvent encore produire du code incorrect, notamment sur des cas limites architecturaux non documentés, des interactions entre domaines complexes, ou des règles implicites que même les développeurs humains méconnaissent. La revue de code reste obligatoire. Le contexte IA est un outil d’amélioration de la productivité, pas un système de garantie de qualité.

Est-ce que ce système fonctionne avec des outils IA non listés comme Codeium ou Tabnine ?

Ces outils n’ont pas de fichier-pointeur dédié dans le dépôt PrestaShop 9.2. Si ton outil supporte des fichiers d’instructions personnalisées à la racine du projet (sous une forme ou une autre), tu peux créer un fichier pointeur correspondant et l’ajouter via une pull request, ou simplement pour ton usage local. La logique est identique : un fichier à la racine qui pointe vers .ai/CONTEXT.md.

Conclusion

Le système de contexte IA intégré dans PrestaShop 9.2 est une innovation architecturale autant qu’un outil de productivité. En centralisant dans .ai/ l’ensemble des règles, conventions et pièges de la plateforme, et en les rendant accessibles automatiquement à tous les assistants IA courants, PrestaShop résout un problème réel que tout développeur senior sur cette plateforme a rencontré : les assistants IA génèrent du code PrestaShop qui semble raisonnable mais viole des règles non écrites. Ce système rend ces règles explicites, versionnées, et universellement disponibles.

Pour toi qui développes des modules ou contribues au core, l’adoption de cette infrastructure est immédiate dès que tu travailles sur PrestaShop 9.2+ dans un IDE compatible. Pour tes propres modules, la création d’un CONTEXT.md structuré selon le template canonique de PrestaShop est un investissement qui se rentabilise rapidement dès que l’équipe ou la complexité du module grossit.