Quand Symfony apprend à parler aux agents IA

En dix jours de fin février à début mars 2026, trois publications convergentes dessinent un écosystème structuré de développement PHP assisté par IA autour de Claude Code et Symfony. L’article fondateur de Javier Eguiluz, les AI Skills pour Symfony UX de Simon André et l’initiative Symfony AI de Fabien Potencier forment un triptyque cohérent. Mais les retours de terrain, les questions ouvertes par les premiers utilisateurs et les contraintes réglementaires du secteur public français invitent à regarder cet écosystème tel qu’il est : puissant, fragile et exigeant.

Le développeur devient spécificateur. Et c’est plus dur que ça en a l’air.

Le 27 février 2026, Javier Eguiluz publie « Claude Code for Symfony and PHP: The Setup That Actually Works ». Évangéliste Symfony, créateur d’EasyAdmin, contributeur principal du framework, Eguiluz travaille sur des applications en production, pas sur des démos. Sa thèse centrale est nette : la différence entre des résultats médiocres et excellents ne tient pas au modèle d’IA, mais à la configuration de l’environnement de travail.

Ce constat déplace le centre de gravité du métier. Le fichier AGENTS.md, placé à la racine du projet, incarne ce déplacement : c’est un contrat d’interface entre le développeur et l’IA qui formalise les conventions de code, les patterns architecturaux autorisés, les commandes de validation. Eguiluz cite le créateur de Claude Code lui-même : l’équipe met à jour ce fichier en permanence. C’est la clé pour obtenir de bons résultats. Pas un gadget. Un actif immatériel qui exige un investissement continu.

Le parallèle avec l’évolution des années 2000 est pertinent. La montée en puissance des frameworks a éloigné les développeurs de la plomberie technique pour les recentrer sur la logique métier. L’IA pousse cette logique un cran plus loin : le développeur s’éloigne de l’écriture ligne par ligne pour se concentrer sur la formalisation des règles du jeu.

Mais cette évolution a un coût que l’enthousiasme ambiant tend à gommer. Pour que le modèle « développeur spécificateur » fonctionne, il faut que le spécificateur comprenne en profondeur ce qu’il spécifie. Quand Eguiluz écrit dans son article que sans le plugin php-lsp, Claude Code « hallucine des noms de méthodes, rate des paramètres de constructeur et utilise des classes qui n’existent pas », il décrit un outil qui, livré nu, ne comprend tout simplement pas PHP. La compétence du développeur n’est pas un supplément d’âme. C’est le filet de sécurité.

AGENTS.md contre CLAUDE.md : un choix de souveraineté technique

CLAUDE.md ne fonctionne qu’avec Claude Code. AGENTS.md est un standard ouvert (formalisé mi-2025 par OpenAI, Sourcegraph et Google) supporté par Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, Windsurf et d’autres. Eguiluz ne s’embarrasse pas de diplomatie : il recommande exclusivement AGENTS.md. Les dépôts officiels de Symfony AI maintiennent les deux fichiers en parallèle, mais la tendance est claire.

Pour les organisations, ce choix relève de la souveraineté technique. Le fichier AGENTS.md d’EasyAdmin illustre l’ampleur de l’investissement : compatibilité multi-versions Symfony, conventions de nommage, standards de code, règles de documentation, environnement DDEV. Ce n’est pas un fichier qu’on rédige en cinq minutes.

Un commentaire sous l’article d’Eguiluz, posté le 6 mars par un développeur utilisant à la fois Claude Code et Cursor, met le doigt sur un problème concret : les conventions CLAUDE.md ne se transfèrent pas proprement vers le format .mdc de Cursor. Le développeur se retrouve à réexpliquer le même contexte projet d’un outil à l’autre. C’est exactement le scénario que le standard ouvert AGENTS.md est censé résoudre. Mais tant que tous les outils ne l’interprètent pas de manière identique, la portabilité reste une promesse plus qu’une réalité opérationnelle.

Le conseil d’Eguiluz sur la maintenance continue du fichier mérite aussi qu’on s’y arrête. Un AGENTS.md laissé à l’abandon devient une carte d’une ville qui n’existe plus : l’agent s’accroche à des conventions obsolètes et produit du code incohérent avec l’état réel du projet. C’est une charge de maintenance que peu d’équipes intègrent dans leur estimation de coût. Et c’est la différence entre les résultats « impressionnants » d’Eguiluz et les résultats « médiocres » qu’il mentionne en ouverture.

Qu’est-ce qu’un fichier AGENTS.md ?

Un fichier Markdown placé à la racine d’un projet logiciel, lu automatiquement par les agents IA de code au démarrage de chaque session. Il contient les conventions de code, les patterns autorisés, les commandes de validation et les règles architecturales. Standard ouvert, indépendant de tout éditeur. Efficace quand il est concis, actionnable et maintenu. Contre-productif quand il est généré automatiquement ou laissé à l’abandon.

Planifier avant de coder : le vrai différenciateur (et la vraie discipline)

Claude Code propose un mode Plan (activable via Shift+Tab) qui interdit à l’IA de modifier le moindre fichier. Elle lit le code, pose des questions, propose un plan détaillé, mais ne touche à rien. Le développeur valide, puis l’IA bascule en mode exécution.

Eguiluz résume la philosophie en une formule qui devrait être affichée dans toutes les salles de réunion : corriger un mauvais plan est toujours préférable à corriger du mauvais code. Pour les fonctionnalités complexes, il n’est pas rare de passer plus de trente minutes en planification pure. Son prompt d’exemple pour les group actions d’EasyAdmin 4.26 est instructif : ni trop vague (il mentionne les fichiers clés via le préfixe @), ni trop directif (il laisse Claude proposer ses propres solutions). Le juste dosage entre guidage et liberté.

Cette discipline de planification est le point le plus sous-estimé de l’article. Sans elle, le risque documenté par Eguiluz lui-même est que Claude Code reste en « mode work » par défaut et produise des résultats médiocres sur les tâches complexes. La plupart des développeurs qui se plaignent de la qualité du code IA n’ont probablement jamais quitté ce mode par défaut.

La gestion de la fenêtre de contexte (environ 200 000 tokens) est le talon d’Achille opérationnel de l’écosystème. Eguiluz recommande de vider le contexte après la planification pour que l’implémentation bénéficie d’un espace propre. La commande /clear doit être utilisée systématiquement entre les tâches. Des retours sur GitHub documentent des cas où le contexte se vide prématurément, entraînant une perte de l’historique de conversation en pleine session de travail. Les notes de version de Claude Code de mars 2026 montrent qu’Anthropic travaille activement sur ces problèmes (réduction de la consommation mémoire, amélioration de la reprise de sessions compactées), mais le sujet reste un point de vigilance pour les tâches de longue haleine.

Point structurant : les fichiers AGENTS.md survivent à la compaction puisqu’ils sont relus depuis le disque. Le plan est l’artefact persistant. Le code est le produit régénérable. C’est un renversement de paradigme.

Six plugins, pas un de plus : le minimalisme comme compétence

L’erreur la plus courante est de surcharger Claude Code de plugins. Eguiluz cite le créateur de l’outil lui-même : même lui n’en utilise pas beaucoup. Six plugins suffisent pour un environnement Symfony complet.

php-lsp (Intelephense) est le plus critique. Sans lui, selon les propres mots d’Eguiluz, Claude Code hallucine. Avec lui, la navigation dans le code passe de 45 secondes (recherche textuelle) à 50 millisecondes (requête LSP), et l’agent vérifie ses propres hypothèses contre le système de types réel du projet. C’est la différence entre un agent qui « croit » comprendre le code et un agent qui le vérifie. Un article technique récent documente le gain : 6 fois moins de tokens consommés en exploration, donc 6 fois plus de contexte disponible pour le travail réel.

Context7 (par Upstash) injecte la documentation à jour des bibliothèques (Symfony, Doctrine, Twig, API Platform) dans les prompts. security-guidance intercepte les vulnérabilités (injection, XSS, désérialisation) dans le code généré. Les trois autres (code-review, code-simplifier, Playwright) apportent l’audit de PR, le nettoyage de code et les tests navigateur.

Chaque plugin consomme de la fenêtre de contexte. Dans un environnement où cette ressource est le facteur limitant principal, la sobriété outillage est une compétence à part entière.

AI Skills Symfony UX : quand le framework comble les lacunes des LLM

Le 6 mars 2026, Symfony publie officiellement des « AI Skills » pour sa stack frontend UX. Créées par Simon André (SensioLabs, équipe Symfony UX), cinq skills couvrent l’ensemble du stack : un orchestrateur avec un arbre de décision (Stimulus, Turbo, TwigComponent, LiveComponent), puis un skill dédié à chaque technologie. Le dépôt fournit des fichiers d’entrée multi-agents au format SKILL.md (standard ouvert supporté par plus de 27 agents IA).

L’existence même de ces skills est un aveu pragmatique : si les LLM comprenaient nativement les conventions Symfony UX, personne n’aurait besoin de packager cette connaissance dans des fichiers structurés. La prolifération des projets communautaires dédiés (superpowers-symfony avec ses 49 skills, atournayre/claude-agents avec ses agents PHP spécialisés) confirme le besoin.

Mais la question posée par Benoit Baudoin dans les commentaires du blog Symfony mérite d’être prise au sérieux : « En utilisant Claude Code Opus 4.6 au quotidien sur ma base de code Symfony, je constate que les agents ont déjà une bonne compréhension des packages Symfony UX. Est-ce que quelqu’un ressent une vraie amélioration avec ces skills ? Ma crainte est d’ajouter de l’information potentiellement redondante chaque fois qu’un agent travaille sur une tâche liée à Symfony UX. »

C’est la question qui compte. Les skills apportent une valeur indiscutable sur les cas limites (quand choisir un LiveComponent plutôt qu’un contrôleur Stimulus), sur les fonctionnalités récentes que les données d’entraînement ne couvrent pas encore, et sur les alertes de sécurité (comme la CVE-2025-47946). Mais sur les patterns courants que les LLM maîtrisent déjà, elles consomment de la fenêtre de contexte sans gain évident. L’enjeu est de charger la bonne connaissance au bon moment, pas d’empiler de l’information.

C’est précisément ce que le format SKILL.md est conçu pour résoudre, avec son modèle de chargement progressif (100 tokens pour la description au démarrage, 5 000 pour le contenu complet uniquement quand la skill est activée). Mais entre la théorie du chargement progressif et la réalité de la consommation de contexte en session, la marge est à observer sur le terrain.

Sous-agents et Agent Teams : un aperçu de l’avenir, pas un outil de production

Les Agent Teams (activables via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 dans la config d’Eguiluz) permettent à plusieurs instances de Claude Code de travailler en équipe. Un lead coordonne, des coéquipiers implémentent en parallèle, et les coéquipiers communiquent directement entre eux (pas seulement via le lead). La documentation officielle détaille le fonctionnement.

Pour Symfony, le cas d’usage est concret : implémenter simultanément un handler Messenger, sa classe de message, le test fonctionnel et la configuration de routing. Eguiluz recommande aussi les sous-agents classiques (via l’outil Task) pour des tâches indépendantes en parallèle, chacun dans sa propre fenêtre de contexte.

Le mot clé est « expérimental ». Les limitations sont réelles : pas de reprise de session, un seul team par session, conflits d’écriture sur les mêmes fichiers, coût en tokens multiplié par le nombre de coéquipiers. Et si la fenêtre de contexte d’un seul agent se dégrade significativement au-delà de 60 à 75 % de remplissage, la question de la cohérence architecturale d’une équipe d’agents sur un codebase Symfony complexe reste ouverte.

C’est la fonctionnalité qui incarne le mieux la trajectoire : le développeur comme chef d’orchestre d’agents spécialisés. Mais aujourd’hui, c’est un aperçu, pas un outil qu’on déploie les yeux fermés sur une application de production.

Symfony, Laravel, Next.js : trois philosophies, un même pari

L’écosystème ne se construit pas en isolation. Laravel a lancé Laravel Boost (août 2025) : un serveur MCP rendant le framework accessible aux agents IA. Approche pragmatique, orientée productivité immédiate. Next.js et Vercel mènent la course avec v0, des AGENTS.md intégrés et un écosystème de skills. Approche radicalement AI-first.

Symfony emprunte une voie distincte. L’initiative Symfony AI (annoncée par Fabien Potencier en juillet 2025, v0.1.0 en décembre 2025, plus de 70 packages, 80 contributeurs) ne se contente pas de rendre le framework utilisable par les agents. Elle intègre les capacités IA dans les applications : interface unifiée vers plus de 25 plateformes IA (Platform), framework d’agents, stockage vectoriel pour le RAG, serveur MCP officiel (Mate).

La singularité de Symfony est l’application systématique de son architecture de composants à l’IA : séparation des responsabilités, testabilité (InMemoryPlatform), extensibilité. Là où Laravel privilégie l’accessibilité et Vercel la vitesse, Symfony mise sur la robustesse architecturale. Pour les organismes de protection sociale, les établissements de santé ou les opérateurs d’infrastructure, ce positionnement a du sens.

Ressources

Articles et publications de référence

Claude Code for Symfony and PHP: The Setup That Actually Works par Javier Eguiluz (dev.to, 27 février 2026)
Introducing AI Skills for Symfony UX (blog Symfony, 6 mars 2026)
Kicking off the Symfony AI Initiative (blog Symfony, 11 juillet 2025)
Symfony AI v0.1.0 : First Tagged Release (blog Symfony, 24 décembre 2025)
Superpowers Symfony: 49 Skills to Code Like a Senior par KevDev

Documentation officielle Claude Code

Fichiers de configuration de référence

Plugins recommandés

php-lsp (Intelephense)
Context7 par Upstash (intégration Claude Code, GitHub)
code-review, code-simplifier, security-guidance, Playwright
Building lsp-mcp-server: Giving LLMs Semantic Code Intelligence (retour technique sur l’apport du LSP)

AI Skills et projets communautaires

Dépôt Skills Symfony UX par Simon André
Spécification SKILL.md et standard Agent Skills
superpowers-symfony par MakFly
atournayre/claude-agents (Packagist)
awesome-claude-skills et awesome-agent-skills
SkillsMP

Intégrations MCP et Symfony AI

Conclusion : un écosystème prêt. Des organisations qui ne le sont pas encore.

L’écosystème Claude Code + Symfony de mars 2026 forme un tout cohérent. Le fichier AGENTS.md formalise ce que les meilleurs architectes logiciels ont toujours fait : documenter les conventions, expliciter les décisions, rendre le savoir collectif transmissible. Le mode Plan réhabilite la conception comme étape productive. Les AI Skills permettent au framework de communiquer directement ses propres règles aux agents. Symfony AI intègre l’IA comme composant d’architecture, pas comme couche marketing.

Mais il faut regarder l’écosystème tel qu’il est, pas tel qu’on voudrait qu’il soit. Les hallucinations de Claude Code sur PHP sans le plugin LSP sont un fait documenté par Eguiluz lui-même. La portabilité des conventions entre outils reste un chantier. La fenêtre de contexte est une ressource rare dont la gestion conditionne tout. Les Agent Teams sont expérimentales. Et pour une partie significative du secteur public français, ces outils sont tout simplement hors cadre réglementaire pour les travaux sensibles.

Le triptyque d’Eguiluz (AGENTS.md, planification, minimalisme) n’est pas un raccourci vers la productivité. C’est un cadre exigeant qui demande plus de rigueur, pas moins. Plus de documentation, pas moins. Plus de discipline architecturale, pas moins. L’IA ne simplifie pas le développement. Elle déplace la complexité vers l’amont : la spécification, la formalisation, la gouvernance.

Les organisations qui comprendront cette inversion gagneront un avantage réel. Celles qui attendront des gains automatiques perdront du temps, de l’argent et, accessoirement, les compétences de leurs équipes.