Aller au contenu

Ce que j’ai appris

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.

L’idée en une phrase

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.

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.

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.

Distance à la conceptionDes règles dans un documentLa conception12345SessionDes règles qui s’exécutentLa conceptionRejeté par un contrôle12345Session
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.

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.

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.

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.

  1. Autoriser
  2. Explorer
  3. Lever les doutes
  4. Classer
  • Petite : directement au code

    1. Implémenter
  • Grande : suivie d’abord

    1. Suivre
    2. 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.
  1. 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.

  2. 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à.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

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.

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.

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.

  1. L’agent écrit et teste en local
  2. Il ouvre la pull request
  3. Une personne ajoute l’étiquette
  4. L’intégration continue s’exécute
  5. Vert : la fusion est possible. Rouge : l’étiquette est retirée et le travail revient à l’agent

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.

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.

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.

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.

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.

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.

EntréeInfrastructureApplicationDomaineLes dépendances pointent vers l’intérieur
L’entrée et l’infrastructure sont à l’extérieur ; chaque dépendance pointe vers l’intérieur, vers le domaine.
  1. 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.

  2. Application

    Les cas d’usage. Elle coordonne le travail, mais les règles n’y vivent pas.

  3. Domaine

    Les règles métier. Il ne sait rien des bases de données, des frameworks ni du réseau.

  4. 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

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.

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.

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.

  1. Écrite

    Elle figure dans les instructions du projet, là où l’agent la lit en premier. Elle explique le pourquoi, pas seulement le quoi.

  2. Branchée

    Un linter, un test ou un hook la vérifie sur chaque machine, avant chaque commit ou push.

  3. 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.

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.

Règles decouchesUne featureimporte unefeatureUn écran litla baseGraphe desdépendancesCyclesd’importsModulesorphelinsLe domaineimportel’infrastructure
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.

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à.

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é.

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.

Photo de Hernán David Figueroa

À propos du développeur

Hernán David Figueroa

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á.

J’écris et maintiens Guardrail seul. Voir mon profil de développeur