🤖 Agent IA : 3 fichiers max par tâche ⚡
Découvrez la règle « 3 fichiers max » pour vos agents IA : revue de code plus simple, risques IA réduits, dev assisté par IA maîtrisé. Testez !
Agents de codage : pourquoi limiter une tâche à trois fichiers
Un agent de codage peut modifier une douzaine de fichiers, lancer les tests et déclarer le travail terminé. Sur le moment, ça paraît efficace. Puis vient la vérification : qu'est-ce qui a vraiment changé ? Une fonction renommée de plusieurs façons, un import oublié, des comportements sans rapport réunis dans le même diff... La vitesse de génération ne dit rien, à elle seule, sur la maîtrise de la modification.
Une règle simple aide à réduire ce risque : limiter à trois fichiers le périmètre d'une tâche confiée à l'agent. Si le changement en implique davantage, l'agent doit d'abord les lister et expliquer à quoi sert chaque fichier. Ensuite, vous décidez : découper la tâche, ou, parfois, accepter une exception.
Ce n'est ni une loi universelle, ni un remplaçant de la revue de code. C'est une limite de rayon d'impact, particulièrement utile quand l'agent touche à des comportements existants. Voyons ce qu'elle protège, comment la mettre en place, et quand il vaut mieux s'en écarter.
Pourquoi limiter le nombre de fichiers modifiés
Le nombre de fichiers n'est pas une mesure parfaite de la complexité. Modifier une seule ligne dans un fichier central peut avoir plus d'effets qu'un changement mécanique dans vingt fichiers. Mais pour les changements de comportement, ce critère joue bien son rôle : il impose un garde-fou simple à comprendre, et surtout une pause avant que le périmètre ne s'élargisse sans décision claire.
Dans un projet réel, l'agent travaille à partir du dépôt, des consignes et du contexte disponible. Il peut produire rapidement une série de changements « cohérents » en apparence. Le problème, c'est que chaque fichier en plus ajoute des dépendances à vérifier : appels, types, tests, configuration, documentation. Plus la modification s'étend, plus il devient dur de distinguer ce qui est vraiment nécessaire de ce qui a été ajouté en cours de route.
L'agent peut perdre le fil du code réellement présent
Un agent peut commencer en lisant correctement les fichiers concernés, puis « s'aligner » sur ce qu'il pense déjà comprendre. Quand les changements s'accumulent, de petites incohérences finissent par apparaître : un utilitaire renommé à un endroit mais pas à un autre, un ancien import conservé, ou un commentaire qui décrit encore l'ancien comportement.
Et ce n'est pas une question de « modèle assez intelligent ». C'est un problème de contrôle : le système doit modifier plusieurs éléments et garder leur cohérence en même temps. Plus le périmètre grossit, plus la vérification de cette cohérence finit par coûter cher.
Un grand diff est rarement relu avec la mĂŞme attention
Une revue utile doit répondre à des questions concrètes : quel comportement change, pourquoi, et quels cas sont couverts par les tests. Quand le diff mélange des modifications nombreuses ou hétérogènes, la revue devient plus laborieuse. On survole, on se repose sur les tests, et l'approbation peut glisser vers la formalité.
Trois fichiers ne garantissent pas une revue de qualité. En revanche, la limite pousse l'agent à produire plus souvent des changements dont le périmètre est lisible. Le but, c'est de vérifier vite le cœur du changement, puis de regarder de près les détails qui présentent un risque réel. La rapidité de revue ne doit jamais devenir un automatisme de validation superficielle.
Un changement trop imbriqué coûte plus cher à annuler
Imaginons qu'un agent modifie douze fichiers pour mettre à jour une règle métier, réorganiser un service et retoucher un écran. Si la règle retenue s'avère mauvaise, ces travaux se retrouvent dans le même panier. Il faut alors séparer ce qu'on peut garder de ce qu'il faut retirer, ou revenir sur l'ensemble.
Avec des étapes plus petites, une erreur s'isole mieux. Le découpage ne rend pas le retour arrière « gratuit », mais il limite le risque de jeter avec une mauvaise décision une partie du travail qui était correcte. C'est particulièrement utile sur une branche partagée, une application en production, ou un produit où les livraisons sont fréquentes.
Une limite de fichiers ne remplace pas le jugement technique. Elle empêche surtout le périmètre de grossir sans que quelqu'un ait décidé de l'accepter.
Les cas oĂą trois fichiers ne sont pas la bonne limite
Cette règle vise surtout les modifications de comportement dans du code existant, là où l'agent a tendance à coupler des changements qui auraient dû rester distincts. Elle n'est pas là pour ralentir des opérations uniformes, ni pour réduire chaque travail à une taille arbitraire.
Migrations mécaniques : privilégier l'automatisation contrôlée
Renommer un symbole dans quarante fichiers, remplacer une clé de configuration partout, ou mettre à jour une dépendance : ça peut faire beaucoup de changements, tout en restant une opération homogène. Imposer trois fichiers dans ce cas obligerait à multiplier les tâches sans améliorer forcément le contrôle.
La question n'est donc pas seulement « combien de fichiers ? », mais « les transformations sont-elles uniformes et vérifiables ? ». Il faut préciser le motif attendu, exécuter l'outil adapté, inspecter un échantillon puis le diff complet, et lancer les tests pertinents. Un script déterministe peut même être plus fiable qu'un agent génératif pour une substitution simple et répétable.
Une exception peut être raisonnable si elle est cadrée : préciser que c'est une migration mécanique, indiquer le motif de transformation, demander un rapport des fichiers modifiés, et définir les contrôles. L'exception ne doit pas devenir une autorisation vague d'élargir le périmètre.
Création de nouveaux fichiers : compter les unités, pas seulement les fichiers
Générer un nouveau module, son test, puis son point d'intégration donne souvent exactement trois fichiers. Dans ce cas, le plafond ne gêne pas et peut même aider à garder un ensemble bien délimité : le code, la vérification et le raccordement.
Si une nouvelle fonctionnalité demande plus, regardez si les fichiers appartiennent réellement à la même unité livrable. Il peut être logique de créer d'abord la structure, puis d'ajouter les comportements dans une autre tâche. Mais éviter une séparation « trop artificielle » : découper jusqu'au point où chaque partie devient impossible à tester seule, ça finit par coûter plus cher qu'un diff plus large.
Les protocoles et contrats d'API méritent un périmètre explicite
Une modification d'API peut toucher le schéma, le serveur, le client et les tests. Demander à un agent de régénérer toute la spécification en une passe peut déclencher des renommages en cascade et rendre la revue pénible. Souvent, un découpage par point de terminaison ou par contrat rend le résultat plus vérifiable.
Par exemple, vous pouvez cadrer autour d'un contrat précis : un point de terminaison, ses champs, sa validation, puis une vérification côté serveur de développement. Là encore, le principe compte plus que le chiffre : « un contrat à la fois », une vérification claire, et une source de vérité qui ne dérive pas au fil de la génération.
Les urgences ne justifient pas un périmètre aveugle
En production, intervenir vite peut impliquer plusieurs fichiers. La limite ne vous interdit pas d'agir ; elle vous oblige à assumer le fait que vous acceptez un périmètre plus large. Dans ce cas, vous devez être encore plus clair : risque, tests disponibles, plan de retour arrière, et personnes qui valideront le changement.
Le bon garde-fou n'est pas « trois fichiers quoi qu'il arrive ». C'est « pas d'extension de périmètre sans raison compréhensible et décision assumée ». Une exception peut exister pour un incident, mais il faut garder une revue adaptée et documenter ce qui a été accepté.
Faire du périmètre un outil de décision
Le plus gros bénéfice de cette règle n'est pas toujours de réduire le diff. C'est qu'elle oblige à rendre l'intention explicite. Un ticket qui demande beaucoup de fichiers contient souvent plusieurs objectifs, ou révèle une dépendance que personne n'avait formulée clairement.
Cette clarification aide autant côté produit que côté technique. Une demande du type « améliorer le parcours d'inscription » est trop vague pour qu'un agent sache où s'arrêter. La liste de fichiers peut révéler que le travail combine validation métier, changement d'interface et refonte de la télémétrie. Ces sujets n'ont pas les mêmes critères d'acceptation, ni les mêmes risques, ni forcément les mêmes interlocuteurs.
Une limite de rayon d'impact, pas une garantie de sécurité
Dans un contexte professionnel, la maîtrise des changements générés par l'IA relève aussi de la gouvernance. Une limite de fichiers rend les modifications plus simples à examiner, mais elle ne garantit ni la conformité RGPD, ni l'absence de vulnérabilité, ni la qualité de la décision métier. Un changement dans un seul fichier peut exposer des données personnelles ; une modification plus large peut, au contraire, être parfaitement maîtrisée.
Pour les systèmes qui manipulent des données sensibles ou des fonctions critiques, le périmètre doit être complété par des contrôles adaptés : accès restreints aux environnements, vérification des secrets, tests de sécurité, validation humaine et traçabilité. Le principe est le même que pour tout outil de développement : automatiser l'exécution ne déplace pas la responsabilité de la décision.
Le temps de génération n'est pas le coût total
Un agent qui modifie dix fichiers « d'un coup » peut sembler plus rapide qu'un agent qui travaille en trois étapes. Mais il faut compter aussi le temps passé à relire le diff, repérer les régressions, corriger les incohérences, et expliquer le changement à l'équipe. Dans une organisation, la revue consomme du temps : développeurs, responsables techniques, et parfois équipes produit ou sécurité.
La comparaison pertinente, c'est le coût de bout en bout : génération, vérification, correction, intégration et maintenance. Si découper ajoute une étape mais évite une longue revue ou un retour arrière risqué, c'est souvent plus rentable. À l'inverse, fragmenter une migration uniforme peut générer de la coordination... sans gain réel. Il faut donc regarder le travail réel, pas seulement le temps d'exécution de l'agent.
Une consigne simple Ă essayer cette semaine
Si vous voulez tester la règle sans réorganiser tout votre processus, choisissez une tâche « standard » qui modifie un comportement existant. Ajoutez cette consigne à votre demande :
Trois fichiers maximum. Avant de commencer, liste les fichiers que tu prévois de modifier et explique le rôle de chacun. Si tu en prévois davantage, arrête-toi et propose un découpage.
Après quelques tâches, observez les résultats : la liste a-t-elle révélé des intentions mélangées ? Les diffs sont-ils plus faciles à relire ? Les exceptions reviennent-elles souvent, et sont-elles vraiment justifiées ? Si le seuil bloque des travaux homogènes, ajustez la règle à ces cas. Et si les agents dépassent systématiquement le périmètre sans explication, le problème vient peut-être aussi de la formulation des tickets, ou des consignes trop générales.
L'objectif n'est pas d'imposer un chiffre « par principe ». C'est de préserver une boucle où l'agent propose, l'équipe comprend, puis le changement est accepté en connaissance de cause.
Conclusion : commencer par une règle simple
La limite de trois fichiers n'est pas une règle universelle. C'est un garde-fou pragmatique pour les agents qui modifient du code existant : elle réduit les changements entremêlés, rend la revue plus concrète, et fait apparaître quand un ticket cache plusieurs intentions.
Commencez par l'appliquer à une tâche de comportement : demandez à l'agent d'annoncer le périmètre avant de coder, puis discutez les exceptions au lieu de les interdire automatiquement. Si vous utilisez déjà des agents de codage, testez cette consigne cette semaine sur un changement « courant ». Le gain utile n'est pas forcément un diff plus petit : c'est une modification que votre équipe peut comprendre, vérifier et assumer.
Comment appliquer la règle sans ralentir l'équipe
La règle marche mieux quand elle est formulée comme une contrainte de travail, pas comme une préférence floue. Dire à l'agent « reste prudent » ne fixe ni de seuil ni de procédure quand il pense avoir besoin de plus.
Une consigne opérationnelle peut tenir en deux phrases :
Le détail important, c'est l'ordre des opérations : l'agent annonce le périmètre avant de modifier le code. Une liste fournie après coup ne sert pas le même objectif. Elle ne permet pas d'identifier les dépendances au moment où la demande est encore « ajustable ».
Traiter la liste de fichiers comme un diagnostic
Quand l'agent propose quatre, six ou dix fichiers, ne répondez pas automatiquement « non ». Regardez la liste. Chaque fichier doit correspondre à une raison identifiable : changer une logique, adapter un appelant, couvrir un comportement dans un test, modifier une configuration nécessaire.
Cette discussion révèle souvent que la demande initiale mélange plusieurs intentions. Par exemple, « ajouter une option de facturation et harmoniser les écrans de paiement » peut recouvrir deux chantiers : implémenter la règle métier, puis revoir l'interface. Le ticket semblait unique parce qu'il décrivait un résultat, pas parce qu'il correspondait à une seule unité de changement.
On peut s'aider d'une règle de décision simple :
Si le périmètre dépasse la limite, formulez des tâches relisables et validables séparément. Évitez de découper arbitrairement « par fichier ». Le bon découpage suit l'intention et le comportement, pas seulement l'arborescence du dépôt.
Garder un cycle court entre plan, code et vérification
Pour chaque tâche, demandez à l'agent : quels fichiers prévoit-il de toucher, quel comportement change, et comment il compte vérifier. Une fois le périmètre accepté, il peut coder, lancer les tests concernés, puis résumer le diff. Ensuite, vous vérifiez que les fichiers modifiés correspondent bien au plan.
Une séquence utile ressemble à ceci :
Les tests restent indispensables, mais ils ne prouvent pas à eux seuls que le changement est bien délimité. Ils peuvent passer même si l'agent a modifié des zones sans rapport, ou si un cas important n'est pas couvert. La limite vise donc le périmètre ; les tests valident une partie du comportement ; la revue humaine reste responsable de la décision.
Suivre la règle avec des indicateurs utiles
Il n'est pas obligatoire de lancer tout de suite une politique complexe ou un outil de mesure. Sur quelques semaines, notez les cas où l'agent dépasse la limite : les raisons invoquées, les incidents repérés en revue. Vous saurez si le garde-fou réduit le travail de correction, ou s'il crée des blocages inutiles.
Évitez de transformer « trois fichiers » en objectif individuel. Si les équipes sont récompensées pour rester sous le seuil, elles risquent de contourner la règle ou de découper artificiellement. Le but n'est pas de produire un chiffre « propre », mais d'améliorer la lisibilité et le contrôle.