Depuis que nous faisons travailler des agents de code sur des projets WordPress en autonomie partielle, un constat revient à chaque nouveau projet : sans fichier de contexte à la racine du dépôt, l’agent redécouvre les mêmes conventions à chaque session, pose les mêmes questions, et parfois enfreint des règles pourtant évidentes pour l’équipe. Les fichiers AGENTS.md et CLAUDE.md répondent à ce problème : un texte lu automatiquement en début de session, qui donne à l’agent les repères qu’un nouveau développeur recevrait lors de son intégration. Ce n’est pas un article sur la rédaction de prompts ponctuels : il s’agit d’un document persistant, versionné avec le code.
Voici la structure que nous utilisons désormais sur nos projets WordPress, testée sur une dizaine de dépôts différents, avec les erreurs de rédaction qui rendent ce type de fichier inutile.
Les commandes avant les principes
Le premier réflexe consiste souvent à écrire des règles générales du style « respecter les standards de codage WordPress ». C’est vrai mais peu actionnable. Ce qui fait gagner du temps, ce sont les commandes exactes du projet : comment lancer les tests, comment vider le cache, comment accéder à l’environnement de recette. Un agent qui connaît la commande exacte évite d’en inventer une approximative.
# Commandes du projet
- Tests PHP : `composer test`
- Linter WordPress : `vendor/bin/phpcs --standard=WordPress src/`
- Environnement local : `wp server --host=localhost --port=8888`
- Build des assets : `npm run build`
- Ne jamais lancer `wp db query` directement sur la base de production
Les zones interdites, en clair
La section la plus utile de nos fichiers reste celle qui liste explicitement ce que l’agent ne doit jamais toucher sans validation humaine : le répertoire wp-content/uploads, les identifiants stockés dans wp-config.php, les migrations de base de données en production, ou la branche principale du dépôt Git. Sans cette section, un agent bien intentionné peut proposer une modification techniquement correcte mais organisationnellement dangereuse.
Les conventions spécifiques au projet
Chaque projet WordPress a ses habitudes qui s’écartent parfois des standards génériques : préfixe de fonctions particulier, choix entre ACF et champs personnalisés natifs, structure de dossiers du thème, convention de nommage des hooks personnalisés. Nous documentons systématiquement ces choix, avec un exemple de code correct et un exemple à éviter, plutôt qu’une simple description abstraite.
Un exemple concret qui a évité un incident
Sur un projet, le client utilisait un système de traduction maison plutôt que les fonctions __() et _e() classiques, pour des raisons historiques liées à une migration ancienne. Sans mention explicite dans le fichier de contexte, un agent avait commencé à réintroduire les fonctions natives WordPress dans plusieurs fichiers, cassant la cohérence du système de traduction existant. Une ligne ajoutée au fichier a suffi à corriger le comportement dès la session suivante.
La taille compte autant que le contenu
Un fichier de trois mille lignes n’est pas mieux respecté qu’un fichier absent : au-delà d’une certaine longueur, les instructions les plus importantes se diluent. Nous visons une structure courte avec des liens vers une documentation plus détaillée si nécessaire, plutôt qu’un unique fichier monolithique. La priorité va toujours aux informations qui évitent une erreur coûteuse, pas à l’exhaustivité.
- Commandes exactes du projet, testées et à jour
- Zones et actions interdites sans validation humaine
- Conventions spécifiques qui s’écartent des standards génériques
- Structure des dossiers et emplacement des points d’entrée principaux
- Contacts ou procédure à suivre en cas de doute
Un fichier de contexte n’est pas un manuel de style, c’est un filet de sécurité contre les erreurs qu’un agent ne peut pas deviner seul.
En résumé
AGENTS.md et CLAUDE.md ne remplacent pas la revue de code, mais réduisent nettement le nombre d’allers-retours inutiles avec un agent. Sur nos projets équipés, nous avons observé moins d’erreurs liées aux conventions locales et une adoption plus rapide des habitudes du dépôt dès la première session. La règle qui fonctionne : court, concret, centré sur ce qui coûterait cher à découvrir par erreur.
