Introduction : Pourquoi cet article ?
Depuis plusieurs mois, nous orchestrons jusqu'à 10 sessions agents simultanées sur CriloCom — un projet Next.js 16 avec Firebase, BigQuery, et une architecture complexe. Nos agents (JULES pour le backend, l'assistant d'ingénierie pour les audits, Nexus pour le maillage) traitent des dizaines de PRs par semaine.
Cet article n'est pas un guide théorique. C'est un retour d'expérience brut, forgé dans les tranchées du développement réel. Voici ce qui marche… et ce qui casse.
1. Le Prompt est votre Langage de Programmation
Un prompt pour un agent IA n'est pas une simple instruction. C'est un programme que l'agent interprète. Comme tout programme, il peut avoir des bugs, des effets de bord, et des interprétations inattendues.
| À faire | À éviter |
|---|---|
| "Ajoute une fonction getStagiaireByEmail dans features/stagiaires/data.ts qui fait une requête BQ et retourne un Stagiaire ou null" | "Ajoute une fonction pour chercher un stagiaire" |
| "Utilise les mêmes patterns que getStagiaireById (ligne 50)" | "Fais-le proprement" |
| "Respecte la convention 'use server' en tête de fichier" | "Utilise les bonnes pratiques" |
La règle d'or : plus votre prompt est structuré comme un cahier des charges, plus le résultat est prévisible. Un prompt vague = un résultat créatif (et souvent imprévisible).
2. Le Contexte est Roi (et la Mémoire est Payante)
Les agents IA ont une fenêtre de contexte limitée — même à 1M de tokens. Chaque mot que vous écrivez dans votre prompt occupe de l'espace qui pourrait être utilisé par l'agent pour raisonner.
Notre solution : le fichier AGENTS.md
Nous avons centralisé toutes les règles, conventions et décisions d'architecture dans un AGENTS.md à la racine du projet :
- Conventions de code (TypeScript strict, pas de any)
- Standards techniques (Next.js App Router, CSS variables)
- Workflow de déploiement (pas de CI, push direct sur main)
- Règles absolues (zéro erreur TypeScript, zéro warning ESLint)
- Checklist de revue (SQL BQ, layouts imbriqués, doublons de merge)
Ce fichier est injecté en préfixe de chaque prompt. Résultat : les agents produisent un code 2× plus conforme du premier coup.
⚠️ Piège fréquent : Ne mettez pas tout dans AGENTS.md. Trop de règles = l'agent ignore les plus importantes. Priorisez. Notre AGENTS.md fait ~200 lignes, pas 2000.
3. Diviser pour Régner : le Pattern de Tâches Atomiques
Notre plus grande erreur au début : donner des tâches trop larges.
❌ "Implémente la gestion complète des stagiaires avec CRUD, recherche, export, et notifications"
Un agent qui reçoit ça va :
- Passer 30 minutes à tout écrire
- Introduire 15 bugs
- Produire un code que vous allez devoir réécrire à 50%
La solution : la décomposition atomique
| Mauvaise approche | Bonne approche |
|---|---|
| "Fais le module facturation" | Session 1 : Types et schémas BQ |
| Session 2 : CRUD data.ts | |
| Session 3 : Pages admin | |
| Session 4 : Tests |
20-30 minutes max par session — au-delà, l'agent perd en cohérence et la facture grimpe.
4. La Revue Systématique (Checklist)
Jamais un merge sans revue. Notre checklist avant chaque merge JULES :
- npx tsc --noEmit : 0 erreurs — obligatoire
- npm run lint : 0 erreurs — obligatoire
- Vérification des doublons : chaque fichier .tsx ne doit avoir qu'un seul 'use client'
- Vérification des tailles de fichiers : si un fichier double de taille, c'est une concaténation de merge
- Validation BigQuery : pas de sous-requêtes corrélées imbriquées, types DATE vs TIMESTAMP cohérents
Astuce : Nous avons automatisé 90% de cette checklist avec npm run validate-pr.
5. Le Pattern des 3 Tentatives
Un constat empirique : un agent IA donne son meilleur résultat à la 2ᵉ ou 3ᵉ tentative.
- 1ˢᵗ tentative : 60% de ce qu'on veut (structure correcte, mais beaucoup d'ajustements)
- 2ᵉ tentative : 85% (les erreurs grossières sont corrigées)
- 3ᵉ tentative : 95% (le code est propre et suit les conventions)
Ne jugez jamais un agent sur sa première réponse. Donnez-lui au moins 2 itérations.
6. Le Fichier de Référence : Votre Meilleur Ami
Avant de demander à un agent de créer un nouveau composant, montrez-lui un existant similaire.
"Crée un FormateurProfilClient.tsx en suivant le même pattern que StagiaireDetailClient.tsx"
Les agents excellent à l'imitation. Donnez-leur un exemple concret plutôt qu'une description abstraite.
7. Gérer les Conflits entre Sessions
Avec 10 sessions parallèles, les conflits sont inévitables. Notre stratégie :
- Un fichier = une session à la fois : deux sessions ne modifient jamais le même fichier simultanément
- PRs simples d'abord, complexes ensuite : les PRs qui touchent des fichiers isolés passent en premier
- Régénération du lock file : npm install après chaque merge (ne jamais merger package-lock.json manuellement)
- Branche propre : chaque session repart de main pour éviter les conflits chaînés
8. Le Coût Caché des Erreurs
Une erreur de build coûte cher. Notre règle : postmortem obligatoire dans l'heure pour tout build échoué :
- Qu'est-ce qui s'est passé ?
- Pourquoi ça n'a pas été détecté ?
- Comment éviter que ça se reproduise ?
- Quelle correction immédiate ?
- Quelle correction durable ?
Chaque postmortem enrichit notre AGENTS.md et notre checklist de validation.
9. La Souveraineté des Agents
Nous avons appris qu'il est contre-productif de sur-contrôler les agents. Avec JULES_SOUVERAIN=true, nous leur donnons :
- Un accès complet aux données (via mock profiles)
- La capacité de naviguer dans toutes les pages
- La liberté de suggestion
En retour, nous exigeons :
- Zéro erreur TypeScript
- Zéro warning ESLint
- Respect strict des conventions
C'est un contrat de confiance : l'agent a les clés, mais il doit rendre des comptes.
10. Le Résultat : 10× Plus Productif
Après 3 mois d'optimisation :
- Temps de développement : divisé par 3 à 5
- Qualité du code : meilleure (les agents sont plus rigoureux sur les conventions que les humains)
- Couverture fonctionnelle : 2× plus de fonctionnalités livrées
- Courbe d'apprentissage : un nouveau développeur monte en compétence en 2 semaines au lieu de 2 mois
Conclusion
Parler aux agents IA est un métier qui s'apprend. Ce n'est ni magique, ni évident. C'est une discipline d'ingénierie à part entière, avec ses patterns, ses anti-patterns, et ses bonnes pratiques.
Chez CriloCom, nous sommes passés de "l'IA va nous remplacer" à "l'IA est notre meilleur développeur junior" — puis à "l'IA est notre meilleur collègue". La différence ? La qualité de nos prompts et de notre processus de collaboration.
Le futur n'est pas aux agents seuls, ni aux humains seuls. Il est aux équipes hybrides qui savent orchestrer les uns et les autres.