Développer un module avec l’aide d’une IA
Une IA peut accélérer fortement le développement d’un module Portix 3, à condition de lui fournir le bon contexte et de lui imposer les conventions du projet.
Le principal risque n’est pas que l’IA produise du code PHP incorrect.
Le principal risque est qu’elle produise du bon code PHP qui ne respecte pas Portix 3.
L’IA doit donc être utilisée comme un développeur assistant travaillant à l’intérieur d’une architecture existante, et non comme l’architecte d’un nouveau CMS.
1. Règle fondamentale
Ne demandez pas simplement :
Crée-moi un module Portix 3.
Une IA qui ne connaît pas exactement l’état courant du projet risque d’inventer :
- une API de modules inexistante ;
- des classes inexistantes ;
- un routeur différent ;
- un moteur Twig ;
- une architecture Composer obligatoire ;
- des migrations étrangères à Portix ;
- des méthodes de template inexistantes ;
- des permissions ne correspondant pas au CMS.
La bonne méthode consiste à lui donner les sources faisant autorité.
2. Sources à fournir à l’IA
Pour développer un module, le contexte minimal recommandé est :
les guides développeur Portix 3 présents dans la base documentaire ;
src/Installation/default-content.json pour la source documentaire distribuée ;
Ajoutez ensuite les fichiers techniques utiles :
src/Module/ModuleManifest.php
src/Module/ModuleInstaller.php
src/Module/ModuleSchemaInstaller.php
includes/engine.php
bootstrap/autoload.php
Enfin, fournissez un module existant servant de référence.
Le meilleur exemple pour un module éditorial complexe est actuellement :
var/modules/articles/
Pour une fonctionnalité plus simple, utilisez le module existant qui ressemble le plus au projet envisagé.
3. Toujours indiquer la version
Commencez le travail par :
Nous développons pour Portix 3 version 0.7.09.
Ne suppose aucune API provenant d’une version future.
C’est particulièrement important car la feuille de route 0.8 prévoit plusieurs changements :
- contrôleurs injectés ;
- nouveau manifeste ;
- contrat de thème ;
- nouveaux composants de templates.
L’IA ne doit pas implémenter aujourd’hui une architecture simplement prévue pour demain.
4. Donner les invariants du projet
Le prompt de départ doit rappeler explicitement les règles qui ne doivent pas être modifiées.
Exemple :
Contraintes :
- PHP 8.2 minimum.
- SQLite via PDO.
- Requêtes préparées.
- Pas de nouvelle base de données.
- Le module doit rester dans var/modules/<module>.
- Son schéma doit utiliser database/*/desc.csv.
- Ne pas modifier le Migrator du noyau.
- Templates Portix\View\Template uniquement.
- Toutes les variables de template doivent être initialisées.
- Échappement HTML automatique.
- Html::trusted uniquement pour du HTML déjà nettoyé.
- CSRF pour toute modification.
- Suppression uniquement en POST avec confirmation.
- Respect des rôles admin/redactor.
- Traductions FR et EN.
- Pas de modification du noyau sans nécessité démontrée.
Cette liste évite une grande partie des erreurs typiques des développements assistés par IA.
5. Décrire le module avant de demander du code
Avant toute génération, demander à l’IA de produire une spécification.
Par exemple :
Je veux créer un module FAQ.
Fonctions publiques :
- liste des questions ;
- catégories ;
- URL courte par question.
Administration :
- créer/modifier une question ;
- brouillon/publié ;
- catégories ;
- suppression réservée à l’administrateur.
Accès :
- rédacteur pour créer et modifier ;
- administrateur pour supprimer.
Je ne veux encore aucun code.
Propose :
1. les routes ;
2. les tables ;
3. l’arborescence de fichiers ;
4. les permissions ;
5. les tests nécessaires.
Vérifiez cette proposition avant de laisser l’IA écrire le module.
Une erreur d’architecture coûte beaucoup plus cher à corriger après génération de vingt fichiers.
6. Développement par étapes
Il est préférable de travailler en plusieurs phases.
Phase 1 — Architecture
Demander uniquement :
- structure ;
- routes ;
- données ;
- droits ;
- dépendances.
Phase 2 — Manifeste et schéma
Produire :
desc.xml
database/*/desc.csv
Puis installer immédiatement le module.
Phase 3 — Repository
Créer et tester les opérations SQL.
Phase 4 — Partie publique
Créer :
index.php
templates/
lang/
Phase 5 — Administration
Créer :
config.php
AdminController
templates admin
Phase 6 — Routage avancé
Ajouter seulement ensuite :
PublicRouteResolver
PublicNavigation
si nécessaire.
Phase 7 — Tests
Créer les smoke tests.
Phase 8 — Validation complète
Lancer toute la suite Portix.
Cette méthode permet d’identifier immédiatement quelle étape introduit une erreur.
7. Ne pas laisser l’IA inventer une API
Lorsqu’une opération doit appeler Portix mais que la méthode exacte n’a pas encore été fournie, donnez cette instruction :
Si tu ne trouves pas une API ou une méthode dans les sources fournies, ne l’invente pas. Signale ce qui manque et cherche d’abord comment les modules existants réalisent cette opération.
C’est une règle très importante.
Exemple d’erreur typique :
$module->registerRoute(...)
si aucune méthode registerRoute() n’existe réellement dans Portix 3.
Un code plausible n’est pas nécessairement un code valide.
8. Utiliser un module existant comme modèle
Pour un module éditorial, vous pouvez demander :
Étudie var/modules/articles.
Je veux reprendre uniquement ses conventions :
- desc.xml ;
- schéma desc.csv ;
- repository ;
- contrôleur admin ;
- traductions ;
- templates ;
- route resolver.
Ne copie pas sa logique métier.
Cette méthode donne généralement de meilleurs résultats qu’une description abstraite de l’architecture.
9. Exiger une justification des modifications du noyau
Ajoutez systématiquement :
Le module doit fonctionner sans modification du noyau.
Si tu estimes qu’une modification du noyau est indispensable, n’effectue pas la modification immédiatement. Explique d’abord pourquoi l’API actuelle du module est insuffisante.
Cela évite qu’une IA modifie :
Application.php
engine.php
Migrator.php
Request.php
pour résoudre un problème qui pouvait rester entièrement local au module.
10. Utiliser des classes plutôt que grossir les points d’entrée
La branche 0.7 utilise encore :
index.php
config.php
mais cela ne signifie pas qu’il faut y placer toute la logique.
Demandez explicitement :
index.php et config.php doivent rester des points d’entrée minces.
Place la logique métier dans src/.
Une organisation recommandée :
config.php
↓
Controller
↓
Service / Repository
et :
index.php
↓
Repository / Service
↓
Template
11. Demander du code testable
Une IA a tendance à produire beaucoup de code avant de le tester.
Préférez :
Fais une première version minimale permettant uniquement d’installer le schéma et de créer/lire un élément. Nous ajouterons l’interface ensuite.
Puis testez :
& "C:\xampp\php\php.exe" tools\install_module.php var\modules\monmodule
avant de poursuivre.
12. Donner immédiatement les erreurs réelles à l’IA
Lorsque PHP renvoie :
Undefined template variable: ...
ou :
Invalid template file: ...
transmettez l’erreur exacte.
Ne reformulez pas simplement :
ça ne marche pas.
Une stack trace réelle permet à l’IA de localiser précisément :
- fichier ;
- ligne ;
- méthode ;
- étape du rendu.
13. Ne jamais corriger au hasard
Demandez :
Identifie d’abord la cause à partir du code et de l’erreur. Ne modifie rien avant d’avoir expliqué quel chemin d’exécution provoque le problème.
Puis seulement :
Corrige la cause minimale et ajoute un test qui aurait détecté cette régression.
Cette deuxième partie est importante.
Chaque bug découvert devrait idéalement améliorer la suite de tests.
14. Templates stricts
Portix considère une variable manquante comme une erreur.
L’IA doit donc examiner le template et vérifier que chaque :
{{ variable }}
et chaque :
{% if variable %}
possède une valeur définie dans tous les chemins d’exécution.
Demandez explicitement :
Fais la liste des variables utilisées par le template et vérifie leur initialisation dans le contrôleur.
Cela évite de nombreux HTTP 500.
15. Sécurité à imposer à l’IA
Un prompt de développement doit contenir :
Sécurité obligatoire :
- requêtes PDO préparées ;
- validation des entrées ;
- CSRF sur toutes les écritures ;
- POST pour les suppressions ;
- contrôle des rôles côté serveur ;
- pas seulement dans l’interface ;
- HTML utilisateur échappé ;
- HTML riche nettoyé avant Html::trusted ;
- aucun secret dans les logs ;
- aucun fichier privé sous une URL publique.
Ne demandez jamais simplement :
sécurise le module.
Donnez des critères précis et vérifiables.
16. Accessibilité
Ajouter également :
Le module doit respecter les conventions d’accessibilité de Portix 3 :
- labels de formulaire ;
- titres structurés ;
- focus clavier ;
- boutons nommés ;
- role=status lorsque nécessaire ;
- pas de tabindex positif ;
- pas d’événement inline ;
- alternative aux opérations drag-and-drop.
Une IA peut alors contrôler son propre HTML avant livraison.
17. Faire produire les tests en même temps que le code
Au lieu de demander :
Maintenant écris les tests.
demandez dès le début :
Chaque fonctionnalité créée doit avoir une stratégie de test. Pour chaque correction de bug, ajoute un test de non-régression.
Un module devrait vérifier au minimum :
installation
réinstallation
création
lecture
modification
publication
permissions
suppression
routage
selon les fonctions qu’il propose.
18. Boucle de validation recommandée
Après chaque étape importante :
& "C:\xampp\php\php.exe" tools\check_php_syntax.php
Puis les tests spécifiques.
À la fin :
& "C:\xampp\php\php.exe" tools\validate_release.php --http=http://localhost/P3
Si un test échoue, ne poursuivez pas vers une nouvelle fonctionnalité avant d’avoir compris l’échec.
19. Demander un résumé des fichiers modifiés
Après chaque intervention de l’IA, demander :
Donne-moi :
1. la liste exacte des fichiers créés ;
2. la liste exacte des fichiers modifiés ;
3. la raison de chaque modification ;
4. les tests qui couvrent ces changements ;
5. les éventuelles limites restantes.
Cela facilite énormément la revue.
20. Faire contrôler les régressions
Avant livraison :
Compare le module avec les conventions de les guides techniques installés dans la documentation Portix 3. Cherche uniquement les violations ou risques de régression. Ne propose pas de nouvelles fonctionnalités.
Ce type de revue est souvent plus efficace qu’un simple :
vérifie mon code.
21. Exemple de prompt initial complet
Nous travaillons sur Portix 3 version 0.7.09.
Je veux créer un module nommé FAQ.
Avant d’écrire du code, étudie les fichiers que je te fournis :
- les guides techniques Portix 3 présents dans la base documentaire
- includes/engine.php
- src/Module/ModuleManifest.php
- src/Module/ModuleSchemaInstaller.php
- var/modules/articles/
Contraintes :
- PHP 8.2 minimum ;
- SQLite PDO ;
- requêtes préparées ;
- schéma du module via desc.csv ;
- ne pas modifier Migrator ;
- ne pas modifier le noyau sauf nécessité démontrée ;
- templates Portix natifs ;
- variables de template toujours initialisées ;
- traductions FR/EN ;
- CSRF sur les écritures ;
- suppression en POST ;
- contrôle réel des rôles ;
- WCAG 2.2 AA ;
- index.php et config.php doivent rester minces.
Fonctions :
- catégories de questions ;
- questions en brouillon ou publiées ;
- URL publique courte ;
- création et modification pour rédacteur ;
- suppression pour administrateur ;
- affichage public par catégorie.
Dans ta première réponse, ne produis aucun code.
Donne uniquement :
1. l’arborescence proposée ;
2. les routes ;
3. le schéma de données ;
4. les permissions ;
5. les étapes de développement ;
6. les tests à prévoir.
N’invente aucune API Portix absente des sources.
Ce prompt constitue une bonne base pour démarrer un développement assisté.
22. Prompt pour passer à l’implémentation
Après validation de l’architecture :
Architecture validée.
Implémente uniquement l’étape 1 :
- dossier du module ;
- desc.xml ;
- schéma desc.csv ;
- test d’installation.
Ne crée pas encore l’interface publique ni l’administration.
À la fin :
- liste les fichiers créés ;
- explique chaque choix ;
- donne les commandes de test.
Puis poursuivre étape par étape.
23. Prompt de correction de bug
Voici l’erreur exacte :
[coller erreur]
Voici les fichiers concernés :
[coller ou fournir fichiers]
Analyse le chemin d’exécution.
Ne propose pas plusieurs corrections hypothétiques.
Identifie la cause exacte, applique la correction minimale puis ajoute un test de non-régression.
24. Ce qu’il ne faut pas envoyer à une IA externe
Même pour faciliter le développement, ne transmettez pas inutilement :
database/portix2.sqlite
var/sys/config.json
sessions/
var/private/
mots de passe
clés API
adresses privées
journaux contenant des données personnelles
Préférez :
- une base de test ;
- des données fictives ;
- un extrait minimal du schéma ;
- des logs nettoyés.
25. IA et base de données
Évitez de demander :
modifie directement ma base pour que ça marche.
Demandez plutôt :
adapte le schéma du module et le code d’installation de façon reproductible.
Un correctif uniquement effectué dans une base locale n’est pas un véritable correctif du logiciel.
26. IA et architecture future
L’IA peut suggérer une amélioration destinée à Portix 3 0.8, mais elle doit la distinguer de la solution actuelle.
Exemple :
Solution 0.7 compatible :
...
Amélioration possible pour 0.8 :
...
Ne mélangez pas les deux.
Un module destiné à la 0.7 doit d’abord fonctionner correctement avec la 0.7.
27. Répartition idéale du travail
L’humain décide
- fonction du module ;
- ergonomie ;
- droits ;
- comportement métier ;
- choix de données ;
- acceptation finale.
L’IA aide
- analyser le code existant ;
- produire le squelette ;
- écrire du code répétitif ;
- créer les repositories ;
- écrire les templates ;
- générer les tests ;
- chercher les incohérences ;
- documenter le module.
Les tests décident
Le fait que l’IA affirme :
tout est correct
n’a aucune valeur particulière.
La référence finale reste :
tests automatisés
+
test navigateur
+
validation humaine
28. Workflow recommandé complet
1. Définir la fonction
↓
2. Fournir les sources Portix à l’IA
↓
3. Demander une architecture sans code
↓
4. Valider l’architecture
↓
5. Créer manifeste + schéma
↓
6. Tester l’installation
↓
7. Créer repository
↓
8. Tester les données
↓
9. Créer interface publique
↓
10. Tester
↓
11. Créer administration
↓
12. Tester les rôles et CSRF
↓
13. Ajouter routage/navigation
↓
14. Ajouter tests de non-régression
↓
15. validate_release.php
↓
16. Tests navigateur
↓
17. Revue humaine
29. Checklist IA avant livraison
Demandez finalement à l’IA de répondre point par point :
- Aucune API Portix inventée ?
- Aucun changement inutile du noyau ?
- Schéma appartenant uniquement au module ?
- Installation idempotente ?
- Requêtes préparées ?
- Validation des entrées ?
- CSRF ?
- Contrôles de rôles serveur ?
- Suppressions en POST ?
- Templates complets ?
- Aucune variable non initialisée ?
- HTML riche nettoyé ?
- Traductions FR et EN ?
- Accessibilité ?
- Tests spécifiques ?
- Validation Portix complète ?
- Pas de données privées dans les fichiers produits ?
Si un point ne peut pas être démontré, il doit rester considéré comme non validé.
Conclusion
L’IA est particulièrement efficace avec Portix 3 lorsqu’elle travaille à partir du code réel et de règles précises.
La méthode recommandée peut se résumer ainsi :
Le projet existant est la source de vérité.
L’IA analyse avant de coder.
Elle travaille par petites étapes.
Elle ne modifie pas le noyau sans justification.
Chaque bug devient un test.
Chaque développement se termine par la validation complète de Portix 3.
Utilisée de cette façon, l’IA devient un outil de développement très efficace sans prendre le contrôle de l’architecture du CMS.
30. Maintenir la documentation
Une intervention assistée par IA n’est pas terminée lorsque le code fonctionne seulement. Toute modification fonctionnelle ou ergonomique doit mettre à jour le guide utilisateur ou développeur concerné dans src/Installation/default-content.json, puis compléter tools/smoke_test_documentation.php. Le résumé final doit citer les documents modifiés et signaler explicitement tout comportement encore non documenté.
Travailler depuis une baseline connue
Lorsqu’une IA intervient sur Portix, elle doit recevoir la version réellement utilisée comme référence. Ne jamais construire un correctif à partir d’une ancienne archive si la production a reçu des modifications intermédiaires.
Pour une intervention sur un module, fournir le dossier actuel du module. Pour une modification du noyau, utiliser la baseline P3 courante. Le numéro de version du module doit être intégré au manifeste, et non seulement au nom du ZIP.
Vérifier les fichiers générés
Avant livraison, contrôler au minimum la syntaxe PHP, la syntaxe JavaScript lorsqu’elle est modifiée, les variables de templates, la cohérence du schéma SQLite et les tests de non-régression concernés.
CI PHP 8.2–8.4
Lorsqu’une modification est intégrée au dépôt, la validation continue doit réussir sous PHP 8.2, 8.3 et 8.4. Un échec de CI doit être traité comme une régression à diagnostiquer, et non contourné en désactivant le test sans justification.