Préparer un projet Symfony pour les agents IA

Instructions du dépôt, runtime, périmètre et preuves : préparez un projet Symfony pour obtenir des contributions IA plus faciles à vérifier.

Un agent peut produire un correctif convaincant tout en utilisant la mauvaise version de PHP, en modifiant un contrôleur voisin ou en oubliant que le projet héberge plusieurs sites. Le problème commence parfois avant la génération : l’environnement et les règles utiles ne lui ont pas été rendus accessibles. Préparer ce contexte est un travail de développement à part entière.

Le AI Coding Radar de Theodo fait une place au Context Engineering et à la conception de dépôts adaptés aux agents. À partir de ces thèmes publics, je propose une méthode centrée sur les projets Symfony : rendre les faits vérifiables, limiter le périmètre et demander des preuves de fonctionnement.

Sources consultées le . Les outils évoluent ; les exemples ci-dessous proposent une méthode de travail à adapter au dépôt.

Décrire le système qui tourne réellement

La première fiche utile tient en quelques réponses : comment démarrer le projet, où exécuter PHP, quelle base utiliser pour les tests et quels contrôles constituent une validation acceptable. Un README indiquant PHP 8.2 alors que le conteneur en utilise une autre version peut orienter le diagnostic dans la mauvaise direction.

Distinguez les déclarations et les observations. composer.json exprime des contraintes, composer.lock les versions verrouillées ; le conteneur en cours d’exécution est encore une autre réalité. Pour un problème de méthode absente ou d’extension manquante, partez du runtime concerné. Ne demandez pas à l’agent de déduire toute l’infrastructure depuis les noms des dossiers.

Dans un projet Sulu, précisez aussi le webspace, la langue et le point d’entrée de console à utiliser. Une commande destinée au contexte d’administration ne doit pas être remplacée au hasard par une commande du site public. Les diagnostics du projet, lorsqu’ils existent, fournissent une meilleure base qu’une supposition sur le câblage des services.

Une fiche courte pour les règles stables

Les règles permanentes doivent rester faciles à retrouver : architecture, conventions, commandes et limites de l’environnement. Les détails propres à la fonctionnalité vont dans son ticket ou sa spécification. Cette séparation évite de transformer les instructions du dépôt en un historique de toutes les conversations.

Projet : application Symfony avec plusieurs sites publics.

Exécution
- Utiliser le service PHP de l'environnement de développement documenté.
- Utiliser uniquement la base de test prévue par le projet pour les fixtures.
- Lire la configuration de CI pour retrouver les contrôles attendus.

Architecture
- Les contrôleurs HTTP délèguent les règles métier aux services concernés.
- Les lectures publiques respectent le site, la langue et la publication.
- Les médias et les brouillons sont des données, pas des fichiers à réinitialiser.

Validation
- Choisir les tests qui couvrent le comportement modifié.
- Rapporter les commandes exécutées et leur résultat.
- Signaler les vérifications impossibles avec leur raison.

Ce texte est un exemple à compléter avec les vrais chemins et commandes du dépôt. Selon l’outil, il peut alimenter un fichier AGENTS.md ou des instructions spécifiques. GitHub documente notamment .github/copilot-instructions.md pour ses instructions de dépôt. Vérifiez les fichiers pris en charge et leur portée dans la documentation de votre assistant ; tous les agents ne lisent pas les mêmes conventions.

Fournir les points d’entrée utiles à la mission

Pour une anomalie de recherche, le contexte utile peut être la route, un exemple d’URL, le service qui construit la requête et un test voisin. Ajouter une transcription complète de cent fichiers ne remplace pas cette orientation. Commencez par une carte courte, puis laissez l’agent consulter les sources nécessaires.

La mission doit rendre les règles observables. « Corriger les résultats » reste ambigu. « Un filtre chocolat + vanille doit retenir les recettes portant les deux ingrédients, avant pagination, en excluant les brouillons » donne un résultat vérifiable. Le code existant décrit le fonctionnement actuel ; il ne tranche pas seul le comportement souhaité.

Un bon premier retour de l’agent expose les fichiers concernés, l’hypothèse retenue et les inconnues qui pourraient modifier la solution. Une question sur une règle métier mérite une réponse. Une hésitation sur une commande déjà documentée doit d’abord conduire à relire le dépôt.

Préparer les preuves en même temps que le contexte

Demandez une correspondance entre risque et contrôle. Une règle de calcul se prête à un test unitaire. Un filtre dépendant de PostgreSQL mérite une vérification sur ce moteur. Le maintien des cases cochées dans une page se vérifie au niveau HTTP ou navigateur. La documentation des tests Symfony distingue tests unitaires, d’intégration et d’application ; cette distinction aide à choisir une preuve adaptée.

L’analyse statique et les linters restent utiles pour les types et les conventions, mais ils ne décident pas si une recette doit contenir tous les ingrédients choisis. Un rapport « tout passe » doit donc préciser ce qui a été lancé, sur quelle partie du système et avec quelles limites. Un contrôle non exécuté n’est pas implicitement réussi.

Garder le contexte vivant sans le gonfler

À la fin d’un travail, conservez une découverte réutilisable : une commande correcte, un emplacement de configuration inattendu ou une contrainte de publication. Supprimez les consignes devenues fausses. Ne recopiez ni secrets, ni données clients, ni journaux bruts pour enrichir artificiellement la mémoire du projet.

Je propose un essai simple : confier une petite modification à partir d’une copie propre de l’environnement, puis observer les recherches et les commandes qui échouent. La documentation GitHub sur les tâches confiées aux agents recommande des missions délimitées et des critères d’acceptation explicites. La préparation du dépôt peut alors être évaluée sur les frictions réellement rencontrées, plutôt que sur la longueur de ses instructions.

← Tous les articles