Chapitre 6.2 — Respecter les conventions existantes

⏱️ TL;DR — Sur un projet existant, les conventions sont souvent implicites — dans le code, pas dans un document. L’agent, lui, a ses défauts et risque de les imposer, créant une couche incohérente avec l’existant. La parade : lui faire inférer les conventions du code puis les respecter (« écris comme le code autour »), et rétro-installer un CLAUDE.md en lui faisant proposer un premier jet à partir du repo, que tu corriges. On rend explicite ce qui était implicite.

🎯 Objectifs

Comprendre pourquoi l’agent « casse le style » d’un projet existant.
Lui faire inférer les conventions à partir du code.
Imposer le principe « écris comme le code autour ».
Rétro-installer un CLAUDE.md sur un projet qui n’en a pas.

Pourquoi l’agent casse le style

Un projet mûr a mille micro-conventions : comment on nomme, comment on structure un module, comment on gère les erreurs, où vont les types. La plupart ne sont écrites nulle part — elles vivent dans le code. Or l’agent, s’il ne les voit pas, applique ses défauts (souvent bons dans l’absolu, mais différents des tiens). Résultat : sa contribution est correcte isolément mais détonne — un nouveau style au milieu de l’ancien. C’est la même incohérence que P2/P4, mais héritée d’un existant.

Le but, sur du legacy : que la contribution de l’agent soit indiscernable de l’existant (dans le bon sens — même style, mêmes patterns). Un bon changement sur un projet mûr ne se remarque pas.

Faire inférer les conventions

L’agent est très bon pour déduire des conventions à partir d’exemples. Sers-t’en avant de coder :

« Avant de modifier quoi que ce soit : lis 3-4 fichiers représentatifs de src/features/ et déduis les conventions de ce projet (nommage, structure d’un module, gestion des erreurs, data-fetching, style de composant). Liste-les. Je veux que tu écrives du code indiscernable de l’existant. »

Deux bénéfices : (1) tu vérifies qu’il a bien capté le style (s’il se trompe, tu corriges avant qu’il code) ; (2) ces conventions déduites deviennent la matière de ton CLAUDE.md rétroactif (ci-dessous).

💡 Réflexe d’architecte — « Écris comme le code autour » est l’instruction la plus rentable sur du legacy. Ancre chaque tâche sur un fichier voisin représentatif (« suis exactement le style de orders/service.ts »). Tu transformes une convention implicite en modèle explicite, sans avoir à la documenter d’abord.

Le piège inverse : ne pas « moderniser » à la sauvage

⚠️ Piège — L’agent (zélé) qui « améliore » l’existant au passage : remplace une lib, réécrit un pattern « plus proprement », introduit sa façon de faire. Sur un projet mûr, c’est destructeur : tu te retrouves avec deux styles, et des changements hors périmètre à démêler. Consigne explicite : « Respecte les conventions existantes, même si tu ferais autrement. Ne modernise/refactore rien sans que je le demande. » La cohérence avec l’existant prime sur ta préférence esthétique.

Si une convention existante est vraiment mauvaise, c’est une décision séparée (un refactor cadré, P11), pas un « tant que j’y suis » glissé dans une feature.

Rétro-installer un CLAUDE.md

Un projet sans CLAUDE.md te fait re-payer l’onboarding à chaque session. Installe-le rétroactivement, en deux temps :

Faire proposer : « À partir des conventions que tu viens de déduire et de la structure du repo, propose un CLAUDE.md court (stack, conventions tranchables, façon de vérifier). Priorise, reste sous 40 lignes. »
Corriger et adopter : tu relis, tu enlèves le descriptif déductible (3.2), tu ajoutes ce que le code ne dit pas (tes intentions, tes interdits), tu commits.

Tu as transformé un savoir implicite (fragile, dans les têtes) en mémoire explicite (versionnée, partagée). C’est exactement « aider l’IA — et l’équipe — à continuer le projet ».

🧭 Sur TaskFlow — TaskFlow a eu son CLAUDE.md dès le kickoff (le cas idéal). Mais la méthode « déduire → proposer → corriger » est ce que tu appliqueras sur tes anciens projets et sur les repos d’équipe : une heure d’investissement qui rend chaque reprise future beaucoup plus rapide et cohérente.

✏️ Exercices

Exercice 1 — Déduis puis vérifie. Sur un projet existant, fais déduire les conventions à l’agent (prompt ci-dessus). Corrige ce qu’il a mal capté. As-tu découvert une convention que tu suivais sans l’avoir jamais formulée ?

✅ Solution

Très souvent, l’agent formule des conventions que tu appliquais « à l’instinct » (un pattern de nommage, une façon de structurer). Les voir écrites te permet de les valider et de les rendre explicites. S’il en invente une fausse, c’est le signal qu’il faut l’ancrer sur un fichier-modèle avant de le laisser coder.

Exercice 2 — CLAUDE.md rétroactif. Fais proposer un CLAUDE.md à partir de ton code, corrige-le (élague le descriptif, ajoute tes interdits), commit. Reprends le projet le lendemain : l’onboarding est-il plus court ?

✅ Solution

Avec le CLAUDE.md versionné, la reprise démarre déjà cadrée : l’agent recharge les conventions au lieu de les redécouvrir. Tu mesures le gain dès la session suivante. C’est l’investissement à plus fort levier sur un projet que tu comptes garder.

🧠 Quiz de révision

1. Pourquoi l’agent « casse le style » d’un projet existant ?

Parce que les conventions y sont souvent implicites (dans le code, pas écrites) : ne les voyant pas, l’agent applique ses défauts, corrects isolément mais détonnant avec l’existant.

2. Quel objectif viser sur du legacy ?

Que la contribution de l’agent soit indiscernable de l’existant : même style, mêmes patterns. Un bon changement sur un projet mûr ne se remarque pas.

3. Comment lui faire adopter les conventions implicites ?

Lui faire déduire les conventions de 3-4 fichiers représentatifs (et vérifier), puis ancrer chaque tâche sur un fichier voisin (« écris comme orders/service.ts »).

4. Quel piège avec un agent « zélé » sur du legacy ?

Qu’il modernise/refactore à la sauvage (change une lib, réécrit un pattern), créant deux styles et du hors-périmètre. Consigne : respecter l’existant, ne rien refactorer sans demande explicite.

5. Comment rétro-installer un CLAUDE.md ?

Faire déduire les conventions à l’agent, lui faire proposer un CLAUDE.md court à partir du repo, puis corriger (élaguer le descriptif, ajouter les interdits) et commiter. L’implicite devient explicite et versionné.

Chapitre suivant : Continuité entre sessions & personnes — reprendre sans perdre le fil, à plusieurs ou dans le temps.