PrestaShop a intégré un système d'onboarding IA dans son repo

Le README du core PrestaShop contient maintenant une instruction qu'on n'avait jamais vue dans un projet open source de cette taille : "Si tu utilises des outils IA pour écrire du code, assure-toi que ton agent a lu le fichier .ai/CONTEXT.md."

TL;DR — Si tu n'as que 30 secondes : PrestaShop a ajouté un dossier .ai/ dans son repo core avec 57 contextes de domaine, 22 contextes de composant, des index pré-générés et des skills réutilisables. C'est un système d'onboarding pour agents IA, directement versionné dans le code. C'est une approche que j'aurais dû adopter plus tôt sur mes propres modules.

🧠 Ce qu'est vraiment le dossier .ai/

La première fois que j'ai vu ce dossier sur le repo develop de PrestaShop, j'ai cru à une expérimentation. C'est beaucoup plus structuré que ça.

Le .ai/ est un système de contexte hiérarchique pour agents IA. La structure complète :

.ai/
├── CONTEXT.md        ← point d'entrée global
├── STRUCTURE.md      ← template canonique pour écrire de nouveaux contextes
├── GOTCHAS.md        ← pièges courants et patterns tricky
├── MULTISTORE.md     ← guidance spécifique multistore
├── Domain/           ← 57 contextes de domaine (Cart, Order, Product...)
├── Component/        ← 22 contextes de composant (CQRS, Grid, Form...)
├── skills/           ← templates de tâches réutilisables
└── generated/        ← index pré-calculés (CQRS, routes, entités, hooks)

Ce n'est pas un fichier de doc supplémentaire. C'est un système d'alimentation de contexte pensé pour les agents qui vont modifier le code.

🔑 La mécanique de chargement : les pointer files

Le problème classique avec les agents IA sur un gros repo : ils ne savent pas quoi lire en premier. PrestaShop résout ça avec des fichier-pointeurs à la racine.

Chaque outil lit son propre fichier de démarrage, qui redirige vers .ai/CONTEXT.md :

Le flux de navigation :

Outil lit CLAUDE.md
  → CLAUDE.md pointe vers .ai/CONTEXT.md
    → CONTEXT.md liste les domaines et composants disponibles
      → Agent charge .ai/Domain/Cart/CONTEXT.md si nécessaire

Aucune configuration manuelle. Tu ouvres le projet, l'agent lit automatiquement le bon contexte selon les fichiers ouverts.

📊 Ce que contient un contexte de domaine

Chaque CONTEXT.md de domaine suit un template standardisé défini dans .ai/STRUCTURE.md. Pour le domaine Cart par exemple :

• Purpose — ce que ce domaine couvre
• Architecture overview — classes clés, services et leurs relations
• Coding standards — conventions spécifiques au domaine
• Do / Don't — règles explicites
• Testing expectations — quels tests sont requis
• Canonical examples — fichiers de référence à suivre
• Related skills — liens vers les templates de tâches réutilisables

C'est exactement ce qu'on met dans un prompt système quand on configure un agent pour travailler sur un module. La différence : ici c'est versionné, partagé, et maintenu par l'équipe core.

Les 22 contextes de composant couvrent les éléments cross-cutting : CQRS, Grid, Form, Hooks. Ce sont les zones où une erreur d'un agent se propage dans tout le codebase — d'où le soin particulier apporté à ces fichiers.

🚀 Les index pré-générés : le truc le plus malin

Le sous-dossier generated/ contient quatre index calculés à l'avance :

• cqrs.md — toutes les commandes et queries CQRS existantes
• routes.md — index des routes
• entities.md — index des entités
• hooks.md — index des hooks

Pourquoi c'est important ? Un agent qui veut ajouter un endpoint Admin API doit savoir quelles queries CQRS existent déjà. Sans cet index, il hallucine des noms de classes ou re-propose ce qui existe. Avec l'index pré-calculé, il peut checker l'existant avant de proposer quoi que ce soit.

C'est le même principe que le context-memory agent que j'avais construit pour mes projets — sauf que là, l'équipe PrestaShop maintient ces index dans le cadre du développement normal du projet.

⚠️ Ce que ça impose aux contributions IA

La documentation d'utilisation est claire sur ce point : le code généré par IA soumis en contribution doit respecter les mêmes standards qu'une contribution humaine.

Concrètement, ça signifie vérifier que le code :

• Suit le pattern CQRS là où c'est requis
• N'utilise pas ObjectModel dans du nouveau code
• Respecte les contraintes multistore
• Inclut les tests appropriés

Ce n'est pas un laissez-passer. C'est un onboarding accéléré. La différence est importante.

Conclusion

Pour être direct : le dossier .ai/ de PrestaShop ressemble à ce que la documentation technique orientée agents devrait toujours être — hiérarchique, versionnable, outil-agnostique. Est-ce que ça remplace une bonne connaissance du codebase ? Non. Est-ce que ça rend un agent IA significativement plus fiable sur un projet de cette complexité ? Absolument.

Personnellement, on vais adapter cette approche sur mes modules commerciaux. Si tu contribues au core PrestaShop ou si tu construis des outils IA au-dessus de l'écosystème, lis le CONTEXT.md avant de laisser ton agent toucher au code.

Nicolas Dabène — Développeur PrestaShop & Laravel de solutions sur mesure.