J’ai construit du logiciel avec un agent d’IA. Voici ce que j’ai appris.
Je travaille avec l’IA depuis 2022, et avec des agents depuis qu’ils ont commencé à apparaître, mi-2025. Avec eux, j’ai construit de vrais projets : un backend, une application mobile, un site web et cette page. Au début, l’agent écrivait vite et je relisais lentement. Avec le temps, j’ai compris que la qualité ne dépendait pas d’instructions mieux écrites, mais d’un environnement où le mauvais code ne pouvait pas passer.
Cette page rassemble ces leçons. Elle ne vend rien : elle raconte ce qui a mal tourné, ce que j’ai changé et pourquoi ça marche, d’une façon qui s’applique à n’importe quel langage ou stack.
Laissez l’IA écrire, et faites en sorte que le projet dise non quand quelque chose ne va pas.
Une architecture stricte, avec des tests et des linters qui échouent quand elle se brise, transforme la vitesse de l’agent en code que vous pouvez maintenir.
Leçon 1
Un agent oublie votre conception d’une session à l’autre.
Ce qui s’est passé
J’ai écrit les règles du projet dans un document : quelle couche peut importer quelle autre, où va chaque chose, ce qu’il ne faut pas toucher. L’agent les lisait et les suivait presque toutes. Mais chaque session repart de zéro, et les « presque toutes » finissent par s’accumuler.
La dérive n’était jamais grande. Un import qui franchissait une frontière, de la logique métier dans un contrôleur, un test manquant. Chaque changement semblait raisonnable pris isolément, et je m’en rendais compte des semaines plus tard, quand du code avait déjà été construit par-dessus.
Ce que j’ai changé
J’ai cessé de compter sur l’agent pour se souvenir des règles et je les ai transformées en contrôles qui s’exécutent tout seuls. Si un changement franchit une frontière, le build ou un test échoue, avec le nom de la règle dans le message d’erreur.
Avec des règles dans un document, les petits écarts s’accumulent. Avec des règles qui s’exécutent, chacun est arrêté dans le changement qui le provoque.
Pourquoi ça marche
Un agent lit les erreurs avec beaucoup d’attention. Une erreur nommée lui dit exactement quelle règle il a enfreinte, et il corrige le changement avant même que je ne le voie. La règle ne dépend plus de la mémoire de personne, ni de celle de l’agent ni de la mienne.
Des règles dans un document
L’agent les lit au début et les suit la plupart du temps.
La dérive apparaît des semaines plus tard, en revue.
Relire, c’est chercher les erreurs à l’œil.
Des règles qui s’exécutent
Elles sont vérifiées à chaque changement, sans exception.
Le changement est rejeté aussitôt, avec le nom de la règle.
Relire, c’est décider sur un travail qui a déjà passé les contrôles.
Leçon 2
L’agent travaille toujours dans le même ordre.
Ce qui s’est passé
Sans ordre fixe, l’agent faisait ce qui lui semblait le plus utile à chaque instant. Parfois, il modifiait des fichiers alors que je n’avais posé qu’une question. Parfois, il commençait à écrire sans lire comment le reste était construit, ou déclarait une chose terminée sans l’avoir testée.
Ce que j’ai changé
Pour cela, j’utilise Organic Driven Development : un flux de travail en sept étapes que l’agent suit à chaque demande, petite ou grande. Le processus grandit avec la taille de la tâche, au lieu d’appliquer le même formalisme à tout.
Autoriser
Explorer
Lever les doutes
Classer
Petite : directement au code
Implémenter
Grande : suivie d’abord
Suivre
Implémenter
Clore
Chaque demande suit le même tronc. Classer décide si le travail va directement au code ou s’il est d’abord suivi.
01
Autoriser
Il vérifie d’abord que j’ai vraiment demandé un changement. Une question, une revue ou un plan ne touche aucun fichier.
Sans cette étapeDes modifications surprises alors que je voulais seulement une réponse.
02
Explorer
Il lit le code existant et les règles du projet avant de proposer quoi que ce soit.
Sans cette étapeDes solutions qui fonctionnent, mais qui ne s’intègrent pas à ce qui existe déjà.
03
Lever les doutes
Si une décision me revient (produit, périmètre, conception), il pose une seule question précise et attend. Si elle est technique, il décide et continue.
Sans cette étapeSoit un déluge de questions mécaniques, soit des décisions prises à ma place qui ne lui reviennent pas.
04
Classer
Une tâche est petite si elle est comprise, si son risque est circonscrit et si elle pourrait être reprise à partir du seul diff. Sinon, elle est grande.
Sans cette étapeSoit tout reçoit du formalisme, soit rien.
05
Suivre
Les grandes tâches reçoivent un document qui cite ma demande mot pour mot, une liste de tâches et un journal des décisions.
Sans cette étapeLe travail se perd quand une session casse, et le résultat s’écarte de ce que j’ai demandé sans que personne ne le remarque.
06
Implémenter
D’abord un test qui échoue, puis le code qui le fait passer. Les commits se font par unité de travail, d’environ 400 lignes au maximum.
Sans cette étapeD’énormes changements, sans preuve qu’ils fonctionnent, impossibles à relire d’une traite.
07
Clore
Il indique ce qui a réussi, ce qui a échoué et ce qu’il n’a pas pu vérifier.
Sans cette étape« Terminé » sans preuve, et moi qui découvre l’échec plus tard.
Pourquoi ça marche
L’ordre transforme le bon jugement en habitude. Il ne dépend pas du fait que l’agent « se souvienne » d’être prudent : chaque étape produit un résultat concret que je peux vérifier. Et comme le processus s’adapte à la tâche, une correction d’une ligne reste rapide.
Leçon 3
L’agent ouvre la pull request. Je décide quand elle est prête.
Ce qui s’est passé
Quand l’agent peut parcourir tout le cycle seul, écrire, tester et fusionner, la revue devient une formalité. Des changements arrivaient sur la branche principale parce que les contrôles passaient, pas parce que quelqu’un avait décidé qu’ils étaient justes.
Ce que j’ai changé
J’ai séparé « c’est fait » de « c’est prêt ». L’agent travaille sur une branche et ouvre la pull request, mais l’intégration continue ne démarre que lorsque j’ajoute une étiquette à la main. La fusion exige que cette exécution réussisse, et l’agent n’a pas le droit d’ajouter l’étiquette.
L’agent écrit et teste en local
Il ouvre la pull request
Une personne ajoute l’étiquette
L’intégration continue s’exécute
Vert : la fusion est possible. Rouge : l’étiquette est retirée et le travail revient à l’agent
Pourquoi ça marche
Chaque fusion passe par une décision humaine explicite, et cette décision coûte peu : j’arrive en revue avec les tests, le lint et l’architecture déjà vérifiés en local. Mon rôle n’est plus de chasser les erreurs, mais de juger si le changement est le bon.
Leçon 4
Si vous ne voyez pas ce que fait l’agent, vous ne savez pas quand intervenir.
Ce qui s’est passé
Avec plusieurs sessions ouvertes en même temps, je perdais le fil. L’une attendait ma réponse depuis dix minutes, une autre avait épuisé son contexte et commençait à faire des erreurs bêtes, et une autre avait fini sans que je m’en aperçoive. Pour le savoir, je devais lire chaque conversation.
Ce que j’ai changé
J’ai ajouté à l’environnement de l’agent des mods qui montrent son état d’un coup d’œil. Ils ne changent pas ce que fait l’agent ; ils me donnent de la visibilité sur lui.
landingÉcrit les tests de la nouvelle sectionEn cours
webDemande avant de lancer une migrationVous attend
mobileTous les contrôles passent, branche prêteTerminé
EnsuiteRelisez le plan web, puis lancez les contrôles avant de committer.
L’état de chaque session
En cours, vous attend, terminé ou en erreur. Je n’interviens que là où l’on a besoin de moi.
Plan et tâches
La liste de tâches de l’agent et des sous-agents qu’il lance. Je peux suivre un long travail sans lire chaque message.
Contexte restant
Une barre par session. Quand le contexte s’épuise, je démarre une nouvelle session avant que la qualité ne baisse.
Conseils et prochaine étape
Après chaque tour, une courte note sur ce qu’il vient de faire et une suggestion pour la suite.
Pourquoi ça marche
Travailler avec un agent, c’est avant tout décider quand intervenir. Plus tôt je vois une session se bloquer ou dériver, moins il y a de travail à défaire. La visibilité fait tenir la supervision en un coup d’œil.
Leçon 5
Des couches claires indiquent à l’agent où va chaque pièce.
Ce qui s’est passé
Quand le projet n’avait pas de structure explicite, l’agent mettait le code là où c’était le plus pratique. La logique métier finissait mélangée à l’accès aux données et à l’interface. Chaque changement touchait de nombreux fichiers, et personne, ni l’agent ni moi, ne pouvait dire avec certitude ce qu’il allait casser.
Ce que j’ai changé
J’ai construit des dépôts de base avec une architecture stricte déjà définie : backend, mobile, web et landing. Les noms des couches changent selon le projet, mais l’idée reste toujours la même. Les dépendances pointent toujours vers le domaine, jamais dans l’autre sens, et chaque module ou feature reste isolé : une feature n’en importe jamais une autre directement.
L’entrée et l’infrastructure sont à l’extérieur ; chaque dépendance pointe vers l’intérieur, vers le domaine.
Entrée
Ce qui reçoit le monde extérieur : un écran, une route HTTP, une commande. Elle traduit et délègue ; elle ne décide pas.
Application
Les cas d’usage. Elle coordonne le travail, mais les règles n’y vivent pas.
Domaine
Les règles métier. Il ne sait rien des bases de données, des frameworks ni du réseau.
Infrastructure
Bases de données, services externes, fichiers. Elle implémente ce dont le domaine a besoin.
Chaque flèche pointe vers le domaine. L’infrastructure dépend du domaine, et non l’inverse.
Interdit : le domaine importe l’infrastructure
Pourquoi ça marche
Pour l’agent, l’architecture est une carte : pour chaque changement, il sait dans quelle couche il va et ce qu’il peut importer. Pour moi, chaque changement reste circonscrit et plus facile à relire. Et comme la règle est simple (« les flèches pointent vers l’intérieur »), un outil peut la vérifier à chaque build.
Leçon 6
Une règle ne compte que si l’enfreindre casse le build.
Ce qui s’est passé
J’avais des règles à trois endroits différents : certaines seulement écrites, d’autres vérifiées sur ma machine, d’autres uniquement en intégration continue. Celles qui n’étaient qu’écrites étaient justement celles que l’agent finissait par enfreindre.
Ce que j’ai changé
Désormais, chaque règle gravit une échelle de trois échelons, et chaque projet vérifie les cinq mêmes choses, même si l’outil exact change selon le langage.
01
Écrite
Elle figure dans les instructions du projet, là où l’agent la lit en premier. Elle explique le pourquoi, pas seulement le quoi.
02
Branchée
Un linter, un test ou un hook la vérifie sur chaque machine, avant chaque commit ou push.
03
Imposée
L’intégration continue refuse la fusion si elle est enfreinte, quel que soit l’auteur, personne ou agent.
RéussiTypesDu code qui compile « par hasard » ou qui utilise des données de la mauvaise forme.
ÉchecArchitectureDes imports qui franchissent les couches, ou des cycles entre modules.
RéussiLint strictDes modèles dangereux, comme insérer des données en HTML plutôt qu’en texte.
RéussiCouverture minimaleUn nouveau comportement sans test qui le prouve.
RéussiSecretsDes clés ou des mots de passe sur le point d’être poussés dans le dépôt.
Un contrôle échoue. L’agent lit le nom de la règle, déplace l’import et relance tout.
Pourquoi ça marche
La ligne rouge est la plus utile. Elle arrête le changement, nomme la règle, et l’agent sait quoi corriger. Un projet où tout est vert parce que rien n’est vérifié ne protège rien.
Leçon 7
Quatre pratiques qui rendent l’architecture difficile à casser par accident.
Avoir des règles qui échouent, c’est le début. Ces quatre pratiques sont celles qui m’ont le plus aidé à faire en sorte que ces règles continuent de protéger dans la durée, quel que soit l’auteur du code.
Tout interdire par défaut, et tester l’interdiction.
Au début, mes règles de couches listaient ce qui était interdit, si bien que tout ce qui manquait à la liste était permis sans que personne l’ait décidé. Désormais, la règle interdit tout import qui n’est pas explicitement autorisé, et un petit projet de test prouve que chaque import interdit échoue vraiment. Si quelqu’un affaiblit la règle, ce test passe au rouge.
Résultat Une règle qu’on ne peut pas affaiblir en silence.
Écrire les règles d’architecture comme des tests.
« Le domaine n’importe rien de l’extérieur » peut être une phrase dans un document ou un test qui s’exécute avec le reste de la suite. Le second s’exécute sur chaque machine et en intégration continue, et son message d’erreur explique la règle mieux que n’importe quel document.
Résultat La règle s’exécute partout où les tests s’exécutent.
Deux outils qui se recouvrent volontairement.
L’un vérifie couche contre couche. L’autre examine tout le graphe de dépendances : cycles, modules orphelins, un domaine qui importe ce qu’il ne devrait pas. Chacun attrape ce que l’autre manque, et si l’un est mal configuré, l’autre est toujours là.
Résultat Un outil défaillant n’ouvre pas de brèche.
Documenter quel contrôle attrape chaque règle.
Je tiens un tableau « attrapé par » qui associe chaque règle d’architecture à l’outil qui l’impose. Une règle sans contrôle ressort aussitôt comme la prochaine à brancher.
Résultat La prochaine règle à brancher est toujours visible.
Chaque outil attrape ce que l’autre manque, et les deux attrapent la règle la plus importante.
Leçon 8
Cinq habitudes qui rendent un agent sûr à utiliser.
Un agent qui lit, écrit et exécute des commandes a plus d’accès que beaucoup de personnes dans une équipe. Ces habitudes s’appliquent à la fois au flux de travail de l’agent et à l’application qu’il construit, et chacune s’appuie sur un contrôle, pas seulement sur une phrase.
L’extérieur
Commentaires et issues
Pages web
Documentation téléchargée
Lu comme donnée, jamais comme ordre
L’agent
Lit le code
Lance les contrôles
Modifie sur une branche
Lire les secrets : refusé
Irréversible : une personne décide
Une personne
Supprime
Publie
Fusionne
Le texte extérieur n’entre que comme donnée. L’agent travaille dans ses permissions, et tout ce qui est irréversible attend une personne.
Le texte extérieur est une donnée, pas un ordre.
Les commentaires, les issues, les descriptions de pull request, les pages web et la documentation téléchargée informent l’agent. Mais n’importe qui peut y écrire, et certains peuvent essayer de lui donner des instructions. La règle, c’est que je suis le seul à donner des ordres, et tout ce qu’un texte extérieur demande est d’abord vérifié.
Appuyé par Instructions du projet et revue humaine
Le moindre accès nécessaire.
L’agent ne reçoit que les permissions dont la tâche a besoin. La lecture des secrets est refusée, et tout ce qui est irréversible (supprimer, publier, fusionner) attend une personne.
Appuyé par Règles de permissions et listes de refus
Épinglez vos dépendances.
Des lockfiles avec des versions exactes et des sommes de contrôle, des actions d’intégration continue épinglées par commit, et un délai d’attente avant d’installer une version fraîchement publiée. Une attaque de la chaîne d’approvisionnement est généralement découverte en quelques jours ; attendre coûte peu.
Appuyé par Installations figées et âge minimal des versions
Les secrets restent dehors.
Chaque commit est analysé avant d’être créé, puis à nouveau en intégration continue. Les fichiers d’environnement sont ignorés, sauf celui d’exemple, qui ne contient aucune vraie valeur.
Appuyé par Deux scanners de secrets indépendants
Les données sont affichées en texte.
Rien de ce qui vient d’un utilisateur ou d’une API n’est inséré en HTML. Le lint rejette ces opérations, et une politique de sécurité du contenu bloque tout script que le build n’a pas enregistré.
Appuyé par Le lint et une politique de sécurité du contenu
Leçon 9
Ce qui demande de l’attention, dans un seul panneau.
Ce qui s’est passé
Les problèmes qui ne cassent pas le build s’accumulent en silence : des dépendances qui vieillissent, des vulnérabilités publiées dans des bibliothèques que j’utilise, des tâches que l’agent a laissées « pour plus tard », une branche en retard sur le dépôt distant. Je m’en rendais compte tard, généralement en revue ou quand quelque chose échouait déjà.
Ce que j’ai changé
J’ai ajouté un mod qui garde l’état du projet à côté de la conversation avec l’agent. Il montre cinq choses.
Carte du travail
Chaque outil utilisé par l’agent, avec une marque là où un contrôle automatique lui a dit non.
Mises à jour
Ce qui est obsolète dans chaque écosystème, et la difficulté de la mise à niveau.
Vulnérabilités
Les avis de sécurité connus pour mes dépendances, chacun avec un lien.
En attente
Les tâches que l’agent laisse pour plus tard, dans une seule liste que je peux vider.
État de la branche
Un avertissement quand je suis en retard sur le dépôt distant, avant de construire sur du code périmé.
Pourquoi ça marche
L’agent et moi voyons la même chose. Je peux lui demander de traiter un avertissement précis avant qu’il ne devienne un problème, au lieu de le découvrir en revue.
Ce que je retiens
L’IA ne m’a pas enlevé mon travail. Elle l’a changé.
J’ai cessé d’écrire la plus grande partie du code et j’ai commencé à concevoir l’environnement où il s’écrit : les couches, les règles qui échouent, l’ordre du travail, la porte avant la fusion et la visibilité sur ce qui se passe. Plus cet environnement est strict, plus je peux laisser de liberté à l’agent, car ce qui ne va pas ne passe pas.
Si je ne devais garder qu’une idée : n’essayez pas de rendre l’agent parfait. Faites en sorte que le projet remarque quand il ne l’est pas.
Développeur full-stack avec plus de 8 ans d’expérience, spécialisé dans la fintech et les paiements sécurisés. Je travaille sur des terminaux de paiement (TPE) et des fonctions de paiement pour Android et iOS chez une passerelle de paiement colombienne. Je travaille avec l’IA depuis 2022, et avec des agents depuis la mi-2025. J’habite à Bogotá.