Plan, grill-me, grill-with-docs : trois façons de cadrer un agent IA
Retour d'expérience sur la construction d'une plateforme TMA avec Cursor : pourquoi la qualité du code produit dépend moins du modèle que du mode de travail imposé à l'agent, avec trois cas réels et une grille de décision issue du terrain.
Le vrai problème n'est pas le modèle, c'est le mode de travail
Pendant ma formation d'ingénieur chez VOID, j'ai travaillé sur la conception et le développement d'une plateforme de génération et de suivi des rapports TMA : application web, moteur CLI, rapports PDF, workflows de validation, sondes de sécurité, exports. L'agent de reporting qui en est issu fait l'objet d'un article dédié sur VOID Insights (grounding, garde-fous, validation humaine).
Cet article ne parle pas de l'agent. Il parle de comment on l'a construit, et surtout de la façon dont le choix du mode de travail dans Cursor a influencé la qualité, la cohérence et la reproductibilité du code produit.
Très vite, j'ai utilisé Cursor pour accélérer la conception et l'implémentation. Le gain est réel : l'agent explore le code, propose des plans, liste les fichiers à modifier et découpe le travail en tâches. Mais plus le projet avance, plus un constat s'impose : la qualité du résultat dépend moins du modèle que du mode de travail imposé à l'agent.
Un agent IA peut produire beaucoup. Il peut aussi produire trop : des plans longs, des hypothèses non vérifiées, des choix techniques « évidents » mais fragiles, ou des règles métier inventées parce que le contexte n'est pas assez explicite. Au fil du projet, j'ai accumulé 35 fichiers .plan.md : architecture, base de données PostgreSQL, auth/RBAC, planification TMA, notifications cron, édition TipTap, export Word, preuves PDF, SSL, historique filtré, etc.
Ces plans ont aidé à avancer. Mais ils étaient aussi difficiles à réviser : chaque plan arrivait avec beaucoup de détails, parfois des décisions implicites, parfois un vocabulaire qui ne correspondait pas encore au langage métier du projet. Quand le sujet était borné, le mode Plan suffisait. Quand le sujet touchait à une intégration externe fragile ou à une règle métier spécifique, il orientait le travail vers une fausse bonne solution.
De quoi parle-t-on ? Le mode Plan est un mode natif de Cursor : l'agent conçoit une proposition complète avant d'écrire du code. grill-me et grill-with-docs sont des skills personnalisées (des instructions réutilisables qu'on ajoute à Cursor) : la première transforme l'agent en interviewer qui pose une question à la fois et laisse l'humain trancher ; la seconde ajoute une discipline de documentation : chaque décision alimente un glossaire et des ADR versionnés dans le repo.
C'est là que j'ai commencé à distinguer trois usages : Plan pour structurer, grill-me pour forcer la décision humaine, et grill-with-docs pour garder une mémoire durable des décisions.
Le raccourci à éviter. Laisser l'agent choisir seul la trajectoire technique dès qu'une contrainte métier est implicite. Le modèle produira une solution plausible, pas forcément la bonne.
Phase 1 : le mode Plan, utile pour structurer, dangereux quand le métier est flou
Au début du projet, je ne connaissais pas encore les skills comme grill-me ou grill-with-docs. Le réflexe était simple : décrire le besoin en mode Plan et laisser Cursor générer une proposition complète.
Pour des sujets bien bornés, c'était très efficace. Découper une première architecture, préparer une migration PostgreSQL, organiser des phases de développement : le mode Plan donnait une base de travail claire (contexte, fichiers concernés, tâches, risques, ordre d'exécution). Sur un projet proche d'un vrai contexte de production, c'était un accélérateur.
Mais le Plan a une limite structurelle : il cherche une trajectoire plausible à partir du contexte disponible. Si la contrainte métier est mal formulée, ou si le bon choix dépend d'un arbitrage que seul l'humain connaît, il choisit une solution séduisante mais incorrecte.
Cas 1. CVE MySQL : le Plan choisit la source officielle, pas la bonne source
Pour identifier les vulnérabilités entre deux versions de MySQL, le Plan a orienté l'approche vers le site officiel de MySQL. Sur le papier, c'est logique : source officielle, données liées au produit, documentation publique.
En pratique, le besoin était plus subtil : comparer une plage de versions (par exemple 8.4.0 → 8.4.9) et inclure les CVE des versions intermédiaires. L'approche par scraping s'est révélée instable et incomplète. Environ trois jours perdus à affiner les résultats, sans récupérer proprement toutes les versions intermédiaires et leurs CVE.
Une session de grilling a changé la question : au lieu de « comment scraper MySQL ? », elle a remis en cause la source elle-même. La solution proposée : l'API NVD, mieux adaptée à une recherche structurée de CVE par plage de versions.
https://services.nvd.nist.gov/rest/json/cves/2.0
La différence n'était pas seulement technique : c'est le mode de travail qui a déplacé la question de « comment implémenter cette idée ? » vers « est-ce la bonne idée ? ».
Cas 2. web-scanner : le Plan fige @latest, la prod casse
Dans un plan, l'agent a proposé d'appeler le scanner de vulnérabilités via :
npx @voidagency/web-scanner@latest
Le choix semblait simple : toujours utiliser la dernière version. Mais dans une chaîne de génération de rapport, cette simplicité devient un risque opérationnel. Après la publication du 11 juin, une nouvelle version du package a rendu --role obligatoire. Résultat : la génération a cassé alors que le code de la plateforme n'avait pas changé.
Une session de grill a ensuite poussé l'arbitrage : faut-il vraiment dépendre de @latest dans une chaîne de génération ? La discussion a abouti à pinner une release ou à intégrer le scanner en monorepo, deux options que le Plan n'avait pas envisagées. Le Plan avait produit une solution rapide ; le grilling a forcé la discussion sur la reproductibilité.
Ce qu'on en retient. Le mode Plan est excellent pour démarrer quand le périmètre est borné. Dès que la décision touche à une source de vérité, à une dépendance externe ou à une règle métier propre au projet, il faut ralentir l'agent et lui faire poser des questions.
Phase 2 : grill-me, on tranche mieux mais on oublie vite
La skill grill-me change le rapport à l'agent. Au lieu de produire un plan complet, l'agent pose une question à la fois et attend une décision humaine avant de continuer. Le rythme est plus lent. La qualité des arbitrages, elle, monte nettement.
Sur les deux cas précédents, le grilling a fait exactement ce que le Plan n'avait pas fait :
CVE MySQL : remettre en cause la source de données, pas seulement l'implémentation du scraping. Résultat : bascule vers l'API NVD.
web-scanner : remettre en cause @latest comme stratégie de déploiement. Résultat : discussion sur le pin de version ou l'intégration en monorepo.
Dans les deux cas, le grilling a réduit l'invention : l'agent ne part plus d'une solution « évidente », il confronte l'humain à un choix explicite. C'est précisément ce qu'on attend quand la contrainte métier est implicite ou qu'une dépendance externe est fragile.
Cas 3. Logique d'échéance TMA : bien implémentée, mal reprise
Un autre exemple concerne la planification TMA : calcul des échéances, périodes mensuelles/trimestrielles, retard, alignement calendrier. La règle métier est subtile : l'échéance est le dernier jour de la période, les trimestres ne sont pas forcément calendaires, les comparaisons se font en UTC, et le statut « envoyé » change l'affichage du retard.
Une session grill-me a permis d'implémenter cette logique correctement, en posant les bonnes questions sur les cas limites (février, trimestre décalé, période déjà envoyée). Le code s'est retrouvé réparti sur plusieurs fichiers : calculate-next-due-date.ts, reporting-period.ts, report-period-match.ts, check-send-period.ts, plus les composants UI qui affichent le suivi.
Le problème est apparu plus tard, quand il fallait corriger ou étendre cette logique dans une nouvelle session. L'agent devait parcourir une multitude de fichiers pour reconstituer le raisonnement complet. S'il en oubliait un (un helper de date, un test, un composant d'aperçu), il risquait de casser la logique existante en proposant un correctif localement cohérent mais globalement faux.
C'est typique de grill-me : la décision est bonne pendant la session, mais elle n'est pas externalisée. Elle vit dans le code dispersé et dans l'historique du chat, pas dans un glossaire ni un ADR.
La limite : la mémoire du chat
grill-me a un défaut structurel : tout reste dans la session. Les décisions prises, les termes affinés, les options écartées : tout vit dans l'historique du chat. Dès qu'on ouvre une nouvelle session, ou que le contexte est consommé, ce parcours disparaît. Concrètement, sur la logique d'échéance ou sur des règles comme le livrable altéré, cela veut dire :
Reparcourir une chaîne de fichiers : pour reconstituer une décision déjà prise.
Réinventer des variantes déjà écartées : mélanger statut workflow et badge altered, recalculer une échéance avec un mauvais fuseau…
Consommer des tokens à recharger le contexte : au lieu de l'exploiter pour avancer.
Le grilling réduit l'invention pendant la session. Il ne la réduit pas entre les sessions.
Le raccourci à éviter. Enchaîner des sessions grill-me sur un sujet complexe sans rien écrire. On gagne en clarté pendant l'interview, on perd tout en fermant le chat.
Phase 3 : grill-with-docs, la mémoire devient un fichier
C'est là qu'intervient grill-with-docs : la même logique d'interview, mais avec une discipline de documentation en parallèle. Chaque terme affiné alimente un glossaire (CONTEXT.md). Chaque décision difficile à inverser devient un ADR (Architecture Decision Record).
Sur le projet TMA, le glossaire a fini par contenir environ 200 termes : rapport, soumission pour validation, livrable altéré, période réservée, contenu modulaire sécurité, etc. Deux ADR ont figé des arbitrages qui auraient été perdus autrement :
ADR 0001 (Livrable altéré) : un PDF retouché hors plateforme remplace définitivement le PDF généré ; le badge altered est orthogonal au statut workflow ; la régénération est bloquée tant que le livrable altéré est actif.
ADR 0002 (Alerte génération longue) : signal unique quand une génération dépasse le seuil, avec notification technique distincte de l'envoi client.
Sans ces fichiers, chaque nouvelle session repartait de zéro. Avec eux, le comportement change :
L'agent scanne CONTEXT.md et les ADR au démarrage : pas besoin de tout recontextualiser à la main.
La compréhension est plus rapide : un terme comme « livrable altéré » a une définition canonique, pas cinq variantes selon la session.
La consommation de tokens se déplace : moins de tokens à réexpliquer le métier, plus de tokens à implémenter ou corriger.
Les décisions sont traçables : un ADR documente pourquoi on a écarté une option. Utile pour soi, pour l'équipe, et pour l'agent dans six mois.
Mémoire de l'agent vs mémoire du projet
grill-with-docs ne remplace pas grill-me : il le complète. On grille pour trancher, on documente pour ne pas retrancher deux semaines plus tard.
Bonus : la doc ne remplace pas la boucle de feedback
grill-with-docs règle la mémoire entre sessions. Elle ne règle pas la vérification du code produit.
Sur la logique d'échéance TMA, une session grill a implémenté le calcul. Mais sans tests automatisés, chaque correction dans une nouvelle session restait une loterie : l'agent pouvait proposer un fix localement cohérent qui cassait un cas limite (février, trimestre décalé, période déjà envoyée). C'est pourquoi on a ajouté des tests unitaires (calculate-next-due-date.test.ts, reporting-period.test.ts) : ils deviennent le signal objectif que l'agent peut consulter, et sur lequel il peut reboucler si la spec n'est pas respectée.
VOID formalise ce constat dans son article Harness Engineering : sans boucle de feedback automatisée, un agent qui corrige du code mais ne peut pas vérifier que ça marche fabrique des bombes à retardement. La règle : avant de parler d'agent IA, on audite et on remet à niveau le harness de tests : unitaires, intégration, et E2E (Playwright, Cypress).
En pratique, les trois couches se complètent :
Un agent qui lit CONTEXT.md mais ne peut pas lancer de tests reste un agent qui comprend mieux, pas un agent qui vérifie mieux.
Ce qu'on en retient. La documentation n'est pas de l'overhead : c'est la mémoire externe qui compense la mémoire limitée de l'agent. Sur un projet long, c'est souvent ce qui fait la différence entre « l'agent invente à nouveau » et « l'agent reprend exactement là où on s'était arrêté ». Mais la mémoire sans vérification, c'est de la confiance aveugle.
Grille de décision : quand utiliser quoi
Après plusieurs mois sur le projet TMA, voici la grille que j'utilise aujourd'hui :
Ce n'est pas un choix exclusif. Sur un projet long, on enchaîne les trois : Plan pour structurer, grill-me pour trancher, grill-with-docs pour figer.
Notre conviction. Le mode de travail n'est pas un détail d'outillage : c'est ce qui détermine si l'agent accélère le projet ou le déraille. Le modèle compte. Le cadrage compte davantage.
Questions fréquentes
Plan mode ou Agent mode : lequel choisir ?
grill-me remplace-t-il le Plan ?
Combien de tokens consomme grill-with-docs ?
Faut-il tout documenter dans CONTEXT.md ?
Peut-on utiliser grill-with-docs dès le début du projet ?
grill-with-docs suffit-il pour la production ?
Besoin de cadrer vos agents IA ?
Modes de travail, glossaires métier, ADR, harness de tests : nous aidons les équipes à mettre en place les méthodes qui rendent les agents IA productifs et fiables, du prototype à la production.
À propos de l’auteur
Achraf Ouahab
Ingénieur en formation
Ingénieur en formation chez VOID, Achraf a conçu une plateforme de génération et de suivi de rapports TMA (application web + moteur CLI). Il s'intéresse aux méthodes de cadrage des agents IA : modes de travail Cursor, interviews socratiques, glossaires métier et Architecture Decision Records.
Cet article vous a été utile ?
Partagez-le à votre réseau, en particulier aux équipes qui utilisent des agents IA sur des projets longs.
Aller plus loin
Un agent IA en production qui n'a pas le droit d'inventer
L'agent de reporting TMA issu de cette plateforme : grounding, garde-fous, validation humaine.
Harness Engineering : agents IA fiables
Pourquoi tout commence par la boucle de feedback automatisée.
Apprendre à l'ère de l'IA
Illusion de progrès, méthode socratique et friction volontaire.
Expertise IA & Automatisation
Agents IA, LLM, RAG et automatisation à forte valeur ajoutée.