Six mois d'évolution d'usages d'agents IA comme Claude Code dans mon quotidien de dev

Depuis le début de l’année 2026, j’ai commencé à développer au quotidien avec Claude Code.

Comme beaucoup de devs, j’ai commencé à tester sur plusieurs projets personnels. Dans mon cas :

• un moteur de calcul de DPE
• un SaaS de gestion locative
• une application de patrimoine personnel

Chaque projet a reçu son fichier d’instructions pour l’agent IA (CLAUDE.md, puis AGENTS.md). Puis au fur et à mesure du temps, en revenant dans ces fichiers, je me suis rendu compte qu’ils racontent une histoire.

Celle de ma façon de travailler avec une IA et qui a pas mal évolué depuis 🙂.

Cet article retrace quatre étapes que j’ai synthétisé, et ce que j’en retiens !

Étape 1 · Les « règles d’or » (avril 2026)

Le premier fichier, sur le moteur de calcul DPE, ressemblait à ça :

## Golden Rules

- Always propose a short plan before implementing
- Keep things SIMPLE
- Avoid over-engineering
- Prefer fewer files, fewer abstractions
- Business logic MUST stay outside UI
- Tests are mandatory for meaningful logic

## Forbidden unless explicitly asked

- Microservices
- CQRS heavy setups
- Event sourcing by default
- Massive refactoring

Une liste de préférences, en somme, ce qui marchait plutôt bien : le « propose un plan avant d’implémenter » m’a souvent évité d’aller beaucoup trop vite.

Mais la vraie valeur venait d’une seule ligne :

For each new feature, check the calculation reference at `doc_methode_calcul_dpe/docs`

J’avais transcrit en Markdown l’annexe de l’arrêté qui définit la méthode de calcul 3CL (25 sections, quatre arrêtés consolidés). Et Claude disposait ainsi d’une source de vérité métier lisible, et pas seulement de consignes de style.

👉 Première leçon : un agent code bien ce qu’il peut vérifier. Lui donner la référence métier vaut plus que dix règles de style.

La limite de ce fichier : il disait comment coder, mais jamais quand s’arrêter ni quoi faire quand on ne sait pas.

Étape 2 · « Ne devine jamais »

Sur le SaaS de gestion locative, j’ai ajouté la règle qui a le plus changé mon quotidien :

Ne devine jamais. Si tu ne sais pas (règle métier, intention produit, format attendu, valeur par défaut, choix de design ouvert…), demande-moi explicitement avant de coder. Mieux vaut une question courte qu’un patch fait sur une supposition incorrecte.

Puis une deuxième, juste au-dessus : documentation avant code. Toute nouvelle fonctionnalité commence par une SPEC (contexte, persona, vocabulaire, comportement attendu, questions ouvertes), et aucun plan d’implémentation n’est proposé tant que les questions ouvertes ne sont pas résolues avec MON aide.

Le fichier contenait aussi le vocabulaire piège du domaine. Par exemple, Copropriete (les lots qu’un propriétaire possède dans un immeuble) n’est pas Syndicat (l’immeuble entier, avec tous ses copropriétaires). Sans cette précision, l’agent IA étendait naturellement le concept existant, ce qui était exactement le mauvais choix.

Le piège : deux fichiers qui divergent

C’est sur ce projet que j’ai fait l’erreur la plus instructive. Il y avait un CLAUDE.md et un AGENTS.md (pour les autres agents), écrits au départ avec le même contenu.

Plus tard, une ADR a acté qu’on sortait de l’event sourcing pour la plupart des agrégats (j’y reviendrai dans un autre article). J’ai mis à jour le CLAUDE.md. Pas l’AGENTS.md, qui affirme toujours :

- Event sourcing strict (agrégats + events)

Un agent qui lit ce fichier défend avec conviction une architecture que j’ai abandonnée.

👉 Deuxième leçon : une seule source de vérité.

Depuis, mon CLAUDE.md ne contient plus qu’une ligne, @AGENTS.md, et tous les agents lisent le même fichier.

Étape 3 · La philosophie avant les règles (juillet 2026)

Sur l’application de patrimoine personnel, j’ai changé d’approche. Au lieu d’une liste de règles, j’ai d’abord écrit un PROJECT_PHILOSOPHY.md : l’intention du produit, pourquoi je voulais faire cela.

Un petit extrait ci-dessous :

L’IA est un assistant de conception et d’exécution, jamais le décideur métier.

Lorsqu’un choix est ambigu ou a des conséquences métier significatives, l’IA demande une clarification. Lorsqu’un choix est mécanique, réversible et cohérent avec les documents, elle peut agir en indiquant brièvement son hypothèse.

Cette distinction entre choix ambigu et choix mécanique a réglé un problème que j’avais à l’étape 2 : à force de « ne devine jamais », Claude posait parfois des questions sur des détails, qui me “perdaient” un peu et m’amenaient beaucoup trop loin à certains moments.

Trois autres idées sont apparues à ce moment-là.

Distinguer faits, hypothèses et décisions. L’agent IA doit dire ce qui est écrit quelque part, ce qu’il en déduit, et ce qui reste inconnu. Et ne jamais transformer une hypothèse en règle par défaut.

Ne plus seulement écrire des tests, mais aussi les lancer. Au début, je demandais surtout à Claude de rédiger des tests. Puis au fur et à mesure des mois, j’ai commencé à avoir plus confiance, et je lui ai demandé d’effectuer lui-même des tests d’intégration, contre une vraie base PostgreSQL (et pas un mock de l’ORM !).

En effet, sans ça, un mapping cassé (par exemple une colonne EF Core silencieusement absente) passe inaperçu.

Exiger la preuve, couche par couche. C’est la section dont je suis le plus satisfait :

- UI : lancer réellement l'application et dérouler le scénario dans un vrai
  navigateur (Playwright ou équivalent). Un `curl` sur la page ne prouve que
  le rendu HTML initial, pas l'interactivité (Blazor Server tourne sur SignalR).
- Ne jamais rapporter une vérification comme faite sans l'avoir réellement
  exécutée. « Ça devrait marcher » n'est pas une vérification.
- Un test qui ne peut pas casser ne compte pas comme couverture.

Chaque ligne de cette section correspond à une fois où Claude m’a annoncé « c’est corrigé » alors que ce n’était pas le cas.

👉 Troisième leçon : expliquer le pourquoi permet à l’agent IA de trancher seul les cas que les règles n’ont pas prévus.

Étape 4 · Un kit réutilisable (octobre 2026)

Au bout de plusieurs projets, j’en ai eu assez de recopier et d’adapter à la main. J’ai donc restructuré mon dépôt de ressources en un kit de templates à copier dans un nouveau dépôt.

Le cœur du kit est une procédure en huit étapes. Celles marquées STOP terminent le tour de l’agent IA jusqu’à ce qu’un humain réponde :

#	Étape	Ce que fait l’agent IA
1	Lire	AGENTS.md, la SPEC, les ADR applicables, le code concerné
2	Trier	Sépare faits, hypothèses et inconnues
3	Spécifier	Rédige ou complète la SPEC si le comportement métier change
4	Demander · STOP	Pose les questions dont la réponse change le résultat
5	Planifier · STOP	Approche, fichiers touchés, impacts. Attend une validation explicite
6	Implémenter	Le plus petit changement qui satisfait la SPEC
7	Vérifier	Lance les contrôles et lit leur sortie
8	Rendre compte · STOP	Changements, hypothèses, contrôles réellement lancés, message de commit

Une demande triviale (faute de frappe, renommage demandé explicitement) peut passer directement à l’étape 6, à condition de signaler l’hypothèse faite.

Quelques choix qui ont été mis en place :

• Les mots-clés de la RFC 2119 (MUST, SHOULD, MAY). Ça paraît scolaire, mais un agent fait clairement la différence entre une recommandation et une interdiction.
• L’agent IA ne commite jamais. Il prépare le diff et propose le message, c’est moi qui commite. Approuver un plan approuve l’implémentation, pas le commit.
• Toujours demander pour la sécurité, les données personnelles, la suppression ou la migration de données et la production, même quand la réponse paraît évidente.
• Un ordre de priorité des sources : ADR > documentation d’architecture > SPEC > code. En cas de contradiction, l’agent IA la signale avant d’implémenter quoi que ce soit.
• Des couches : une base valable pour toute stack, puis une couche .NET, une couche GitHub, une couche Blazor. Les fichiers de conventions sont copiés sans modification, les règles propres au projet vont uniquement dans AGENTS.md. Je peux ainsi mettre à jour les conventions d’un projet sans rien perdre.

Bonus : empêcher l’agent IA de lire les images

Dans le cadre d’un projet où les images n’étaient pas produites par IA, l’équipe de création graphique souhaitait que l’on mette en place des restrictions pour empêcher l’IA de lire leur travail. En effet, dans le dépôt Git, nous avions des assets d’images, logos, etc. produits par des graphistes.

Ainsi, nous avons mis en place des indications dans le but d’interdire aux agents IA de lire les fichiers image. D’ailleurs, outre le fait que ça coûte cher en contexte, ça sert rarement à une tâche de code.

Côté Claude Code, ce sont des règles permissions.deny sur Read(./**/*.png) et consorts. Mais il faut être lucide :

• ça bloque les outils de lecture intégrés et les commandes shell reconnues (cat, head…) ;
• ça ne bloque pas un script qui ouvre les fichiers sans les nommer ;
• un fichier .claudeignore n’a aucun effet dans Claude Code.

D’où une règle écrite dans AGENTS.md qui interdit explicitement de contourner le blocage. Une règle écrite n’est pas une garantie technique, mais les deux se complètent.

Ce que je retiens

1. Donner la référence métier. Un agent avec une source de vérité vérifiable produit un meilleur code qu’un agent avec des règles de style.
2. Écrire le pourquoi. Les règles couvrent les cas prévus, la philosophie couvre les autres.
3. Une seule source de vérité. Un fichier d’instructions dupliqué finit toujours par mentir.
4. Des points d’arrêt explicites. « Propose un plan » ne suffit pas, il faut « propose un plan, puis attends ».
5. Exiger la preuve. « Ça devrait marcher » n’est pas une vérification, pour un agent comme pour un humain. Et avec la confiance, je lui demande aussi de lancer les tests d’intégration.
6. Le fichier vit avec le projet. Quand une ADR change l’architecture, le fichier d’instructions fait partie du même commit.

Au final, quand je me relis, rien de tout cela n’est spécifique à l’IA !

En effet, c’est ce que j’attendrais d’un développeur rigoureux qui rejoint l’équipe : lire avant d’agir, poser les bonnes questions, ne pas sortir du périmètre, et ne pas annoncer un résultat qu’il n’a pas vérifié.

La différence, c’est qu’avec un agent, il faut l’écrire noir sur blanc. Et ça m’a obligé à clarifier ma propre façon de travailler.

C’est d’ailleurs la suite logique de ma mise en place des ADR en équipe : documenter ses décisions sert autant aux humains qu’aux agents.