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.