Des règles d'équipe pour les agents de code
TL;DR
Une équipe peut commencer avec quatre règles : limiter ce que l'agent peut toucher, versionner les conventions, bloquer automatiquement les erreurs vérifiables et garder une validation humaine avant livraison. Le cadre se déploie sur un projet pilote, puis s'élargit seulement quand les mesures montrent qu'il aide réellement.
Quatre décisions suffisent pour commencer : ce que l’agent peut toucher, ce qu’il peut lancer, ce que la machine vérifie et ce qu’un humain doit encore valider. Sans ces décisions, chaque dev invente son propre workflow agentique et la revue absorbe les écarts.
Ce cadre part de deux terrains limités : mon setup quotidien, équipé d’une quinzaine de hooks, et le déploiement de Kilo Code dans une équipe de développement. Je ne l’ai pas éprouvé dans une organisation de cent développeurs. À cette échelle, les mêmes principes tiennent, mais les rôles, les accès et l’audit demandent un travail supplémentaire.
Quelles règles méritent d’être écrites ?
Un fichier d’instructions sert à transmettre le contexte que l’agent ne peut pas deviner : les commandes du projet, les conventions locales, les limites du périmètre et les critères de fin. Le document doit rester court assez longtemps pour être relu. Les règles génériques y consomment de la place sans changer une décision.
Pour un dépôt applicatif, la première version peut tenir en quatre rubriques :
## Périmètre
- Ne modifier que les fichiers nécessaires à la demande.
- Ne jamais ajouter de fichier `.env` ou de secret au dépôt.
## Vérifications
- Lancer les types, le lint, puis les tests concernés.
- Montrer la sortie avant de déclarer le travail terminé.
## Validation humaine
- Ne pas pousser ni fusionner sans demande explicite.Codex lit les fichiers AGENTS.md avant de travailler et compose les instructions de la racine
jusqu’au dossier courant. Un sous-dossier peut donc préciser les commandes d’un service sans
dupliquer tout le règlement du dépôt. Cette hiérarchie est documentée par
OpenAI.
Que peut-on laisser à l’appréciation de l’agent ?
Le niveau de liberté dépend du coût d’une erreur. Lire le dépôt, proposer un plan ou lancer un test local se corrige facilement. Publier, modifier des droits, transmettre des données ou lancer une commande destructive change la situation en dehors du diff : l’équipe doit décider qui garde la main.
Une matrice courte évite les interprétations :
| Action | Par défaut | Contrôle attendu |
|---|---|---|
| Lire et rechercher dans le dépôt | Autorisée | Périmètre du projet |
| Modifier le code demandé | Autorisée | Diff limité à la tâche |
| Lancer types, lint et tests | Autorisée | Commandes versionnées |
| Installer une dépendance | À confirmer | Justification et source officielle |
| Pousser, fusionner ou publier | À confirmer | Validation humaine explicite |
| Manipuler un secret | Interdite par défaut | Canal et outil dédiés |
Cette table ne cherche pas à prévoir tous les outils. Elle fixe le niveau d’autorité. Un nouveau outil hérite ensuite de la règle correspondant à son effet réel.
Quelles règles faut-il transformer en contrôles ?
Une convention reste utile quand elle demande du jugement. Une condition binaire gagne à devenir un contrôle automatique : le lint passe ou échoue, un fichier sensible est présent ou absent, une review a tourné ou non.
Dans mon setup actuel, le commit est bloqué sans review préalable et le push exige types, lint et tests dans cet ordre. Ces contrôles ont retiré des vérifications répétitives de ma tête, mais ils ont aussi ajouté du code à maintenir. Le détail des hooks et de leur coût est documenté dans le dispatch sur les guardrails.
Le bon point d’enforcement est le moins coûteux qui attrape encore l’erreur à temps. Une erreur de format appartient au lint. Une règle qui doit empêcher un commit appartient à un hook. Une incompatibilité d’ensemble reste dans la CI ou dans la revue.
Comment déployer ces règles dans une équipe ?
Le premier déploiement doit rester assez petit pour que les faux positifs soient visibles. Un projet pilote, deux ou trois types de tâches et quelques semaines donnent plus d’informations qu’une charte écrite avant le premier usage.
- Versionne les commandes et les limites déjà communes à l’équipe.
- Ajoute un seul contrôle sur une erreur réellement rencontrée.
- Relève les blocages et les corrections demandées en revue.
- Corrige la règle avant de l’appliquer à un second dépôt.
Le déploiement de Kilo Code dans mon équipe a confirmé un point : l’outil choisi compte moins que la façon dont l’équipe l’intègre. Un modèle insuffisant sur les tâches réelles peut tuer l’adoption ; un bon modèle sans règles communes déplace simplement le coût vers la revue. Ce retour reste celui d’une équipe et d’une stack PHP/TypeScript, pas une mesure universelle.
Comment savoir si les règles aident vraiment ?
Le volume de code généré ne dit rien sur le travail livré. Quatre mesures suffisent pour une première boucle :
- le nombre de corrections substantielles demandées en revue ;
- la part des tâches qui passent les validations au premier essai ;
- le temps passé à débloquer les sessions ;
- les incidents évités ou détectés avant le push.
Le point de départ doit être relevé avant le pilote. Sans comparaison, une baisse des retours de review ressemble vite à un succès alors que l’équipe a peut-être confié des tâches plus faciles à l’agent.
Quand ce cadre devient-il trop lourd ?
Un script jetable ou un dépôt d’essai ne mérite pas la même mécanique qu’une application en production. Deux règles écrites et une revue du diff peuvent couvrir le risque. Ajouter un hook, un tableau de suivi et une procédure d’escalade ferait alors payer le cadre plus cher que l’erreur évitée.
La limite inverse existe aussi. Dès qu’un agent peut toucher plusieurs dépôts, appeler des services externes ou agir sans supervision directe, les règles du dépôt ne couvrent plus tout. L’identité, les permissions, les journaux d’activité et l’isolation deviennent des sujets de plateforme.
Ressources et suites
La documentation OpenAI décrit la hiérarchie des fichiers AGENTS.md
et la manière dont Codex compose les règles du projet.
Pour prolonger le cadre :
Questions fréquentes
- Quelles règles écrire avant d'utiliser un agent de code en équipe ?
- Commence par le périmètre de lecture et d'écriture, les commandes autorisées, les validations obligatoires et les actions qui demandent une confirmation humaine. Une règle vague comme « faire attention aux secrets » ne protège rien : le dépôt doit préciser les fichiers interdits et le contrôle qui bloque leur ajout.
- Faut-il un fichier AGENTS.md dans chaque dépôt ?
- Un fichier à la racine suffit pour les conventions communes. Des fichiers plus proches du code deviennent utiles quand un sous-dossier porte des commandes ou des contraintes différentes. Codex charge les instructions depuis la racine vers le dossier courant, les règles les plus proches pouvant préciser les précédentes.
- Quelles règles doivent devenir des contrôles automatiques ?
- Celles dont le résultat peut être décidé sans interprétation : tests obligatoires, lint, fichiers interdits, format d'un commit ou présence d'une validation. Les choix d'architecture et les compromis métier restent dans la revue humaine.
- Comment tester ce cadre sans ralentir toute l'équipe ?
- Lance-le sur un projet et un type de tâche pendant quelques semaines. Suis les blocages, les corrections demandées en revue et le temps gagné ou perdu. Une règle qui produit surtout des faux positifs doit être corrigée ou retirée avant d'être généralisée.