La qualité du code produit par un agent de développement dépend moins de la longueur du prompt que de ce qu'il connaît du projet.
Un agent qui dispose des bonnes règles, des bonnes sources et d'un plan clair peut travailler avec précision. Sans ce contexte, même un modèle performant doit deviner, et chaque supposition devient une source potentielle d'erreur.
Le context engineering consiste précisément à sélectionner, structurer et maintenir ces informations. L'objectif n'est pas de remplir la fenêtre de contexte du modèle, mais de lui fournir le plus petit ensemble d'informations à fort signal, au bon moment.
Dans mon article du passage du vibe coding à l'agentic engineering, j'expliquais pourquoi le contexte devient une infrastructure du développement logiciel. Voici maintenant comment je le construis dans la pratique, avec AGENTS.md, CLAUDE.md, des specs Markdown, des skills, des outils et MCP.
Context engineering et prompt engineering ne résolvent pas le même problème
Le prompt engineering améliore la manière de formuler une instruction. Le context engineering organise tout ce que le modèle peut utiliser pour interpréter et exécuter cette instruction.
| Prompt engineering | Context engineering |
|---|---|
| Que dois-je demander ? | Que doit savoir l'agent pour agir correctement ? |
| Travaille surtout la consigne | Travaille la consigne, les connaissances, les exemples, les outils, la mémoire et les garde-fous |
| Se concentre souvent sur une réponse | Gère une tâche qui évolue sur plusieurs étapes |
| Cherche une meilleure formulation | Cherche le meilleur contexte au meilleur moment |
Prenons une demande concrète : « ajoute dans Begonia.pro mon SaaS de local SEO un audit de visibilité locale sur Bing, pour mesurer ce canal en complément de Google ».
Le besoin métier est clair, mais cette phrase ne dit rien de l'architecture existante, des règles du produit, des données disponibles, des composants à réutiliser ni de la définition de « terminé ». C'est ce contexte qui permet à l'agent de transformer une bonne idée en fonctionnalité cohérente.
Anthropic définit le context engineering comme la sélection et la maintenance de l'ensemble optimal de tokens disponibles pendant l'inférence. Cette définition contient le point essentiel : optimal ne veut pas dire maximal.
Mon cas réel : faire évoluer un SaaS sans réexpliquer le projet
Sur mes projets comme Begonia.pro ou Fude.md, une fonctionnalité traverse le besoin utilisateur, l'interface, la logique métier, le stockage, les services externes et les tests. Pour produire une implémentation cohérente plutôt qu'un code seulement plausible, l'agent doit comprendre :
- le résultat attendu pour l'utilisateur et ce qui reste hors périmètre ;
- les composants, types et parcours existants à réutiliser ;
- les règles métier et les décisions produit qui ne sont pas visibles dans le code ;
- les contrats actuels des services externes et les permissions nécessaires ;
- les conventions du projet, les garde-fous et les zones à préserver ;
- les états d'interface, les langues et les critères de validation avant livraison.
Je ne place pas tout cela dans un prompt géant. Je répartis le contexte entre une couche statique, disponible dès le départ, et une couche dynamique, récupérée quand la tâche le demande.
Mon architecture : un socle statique, puis du contexte dynamique
Le contexte statique donne les règles du jeu. Le contexte dynamique apporte les informations propres à la tâche et à l'état actuel du projet.
| Contexte statique | Contexte dynamique |
|---|---|
AGENTS.md, CLAUDE.md et règles du dépôt | Fichiers trouvés pendant l'exploration |
| Architecture et conventions durables | Skill chargée pour une technologie précise |
| Documentation durable du projet | Spec Markdown de la fonctionnalité en cours |
| Commandes de validation | Résultats de tests et erreurs du terminal |
| Garde-fous de sécurité | Données récupérées via un outil ou MCP |
| Exemples canoniques | Documentation externe pertinente à cet instant |
Les specs Markdown occupent une place particulière : elles restent dans le projet, mais l'agent ne charge que celle de la fonctionnalité en cours. Je les construis au fil de mes échanges avec Codex ou Claude Code et les relis dans Fude. Elles rassemblent le problème, le périmètre, les décisions et les critères d'acceptation, puis servent à la fois de contexte de référence et de plan d'implémentation. Je détaille ce workflow plus bas.
AGENTS.md et CLAUDE.md contiennent la carte, pas toute la bibliothèque
Le point d'entrée dépend de l'agent. Codex et d'autres agents utilisent AGENTS.md, tandis que Claude Code charge CLAUDE.md dans son contexte au début de chaque session. Ces fichiers doivent être précis, courts et maintenables.
Ils contiennent :
- la finalité du produit, sa stack et ses utilisateurs ;
- les dossiers importants et leur rôle ;
- les conventions qui ne se déduisent pas facilement du code ;
- les zones à ne pas modifier sans raison explicite ;
- les commandes de validation et la définition de « terminé ».
Un extrait volontairement simplifié du contexte projet serait plutôt de cette forme :
# Projet
Begonia.pro est un SaaS Nuxt de SEO local destiné aux entreprises et consultants.
## Règles produit
- Un audit doit expliquer ses constats, pas seulement afficher un score.
- Chaque résultat issu d'une source externe conserve sa source et sa date.
- Les parcours français et anglais évoluent ensemble.
## Règles techniques
- Réutiliser les types, composants et patterns d'audit existants.
- Effectuer les appels aux fournisseurs uniquement côté serveur.
- Ne jamais exposer une clé ni les données d'un autre client.
## Validation
- Lancer le lint, le typecheck et les tests concernés.
- Vérifier les états vide, chargement, résultat et erreur.
- Résumer les fichiers modifiés, les vérifications et les limites restantes.
Je ne duplique pas les mêmes règles dans deux fichiers qui finiraient par diverger. Mon CLAUDE.md peut importer le socle commun, puis ajouter seulement les instructions propres à Claude Code :
@AGENTS.md
## Claude Code
- Utiliser la spec Markdown active comme plan d'implémentation.
OpenAI recommande de maintenir un AGENTS.md pour aider Codex dans un dépôt. La documentation de Claude précise que Claude Code lit CLAUDE.md et peut y importer AGENTS.md.
La documentation explique les décisions durables
Le code montre ce que le produit fait aujourd'hui. Il n'explique pas toujours pourquoi une solution a été choisie, quelle alternative a été rejetée ou quelle contrainte client ne doit pas être cassée.
Je garde dans la documentation les informations qui survivront à plusieurs tâches :
- les specs produit et leurs critères d'acceptation ;
- les décisions d'architecture ;
- les contrats avec les services externes ;
- les procédures de déploiement ou de migration ;
- quelques exemples considérés comme canoniques.
Une documentation obsolète fait l'inverse : l'agent se fie à une décision devenue fausse. Je date les documents sensibles et supprime les instructions périmées au lieu d'empiler les exceptions.
Les skills apportent une méthode à la demande
Une skill est un paquet d'instructions spécialisé : comment écrire un contenu Nuxt, auditer une migration de base de données, relire une PR ou créer une intégration MCP. L'agent ne la charge que lorsque la tâche correspond.
Quand une skill officielle existe, je l'installe en priorité. J'utilise notamment la skill officielle de Nuxt, qui apporte à l'agent les conventions du framework, les fichiers à inspecter et les points d'attention liés à la version utilisée.
Je réserve mes propres skills aux méthodes spécifiques à mes projets. C'est plus précis qu'une règle globale comme « respecte les bonnes pratiques Nuxt » : j'encode une méthode une fois, puis je la réutilise avec plusieurs agents et modèles.
Les outils et MCP apportent l'état actuel du monde
Les fichiers du dépôt ne suffisent pas lorsque la réponse dépend d'une donnée vivante : volume de recherche, état d'un ticket, documentation mise à jour, contenu client ou résultat d'une API.
Les outils permettent à l'agent d'explorer son environnement et de ramener une information ciblée. MCP (Model Context Protocol) standardise l'accès à certaines de ces sources et actions. J'ai déjà détaillé ce que j'ai appris en construisant deux serveurs MCP pour mes SaaS.
Quand je reprends une pull request, le serveur MCP officiel de GitHub permet à l'agent de consulter sa description, les changements proposés, les commentaires de review et l'état de la CI. Je n'ai pas besoin de recopier tous ces éléments dans un prompt : l'agent récupère directement l'état actuel de la PR au moment de travailler dessus.
MCP complète ainsi le contexte statique du projet avec des informations qui évoluent en dehors du dépôt local : discussions, décisions de review et résultats des validations. L'agent accède au contexte utile lorsqu'il en a besoin, sans le charger systématiquement dans chaque conversation.
Mon workflow en sept étapes
1. Je construis la spec avec l'IA tout en la relisant dans Fude
Pour une fonctionnalité importante, j'échange d'abord avec l'IA dans Codex ou Claude Code. Ensemble, nous cadrons le problème, le résultat attendu, le périmètre, le hors-périmètre, les décisions et les critères d'acceptation. L'IA m'aide à produire et challenger une spec Markdown.
Pendant l'échange, je garde le fichier ouvert dans Fude, mon lecteur de fichiers Markdown. À chaque itération dans Codex ou Claude Code, je relis la spec dans cet environnement propre et design, repère les zones floues, puis poursuis la discussion avec l'IA.
La version validée joue deux rôles : contexte de référence pour comprendre la fonctionnalité et plan d'implémentation pour la construire. La fonctionnalité ne dépend donc pas d'un prompt perdu dans une conversation.
2. L'agent lit les règles du projet
Avec Codex, AGENTS.md fournit la stack, les conventions et les commandes. Avec Claude Code, ces informations passent par CLAUDE.md, qui peut importer le même socle commun. L'agent consulte ensuite la spec Markdown relue dans Fude et les documents indiqués sans tout charger « au cas où ».
3. Il explore avant de proposer
Je lui demande de trouver les composants, schémas, tests et fonctionnalités similaires. L'existant montre les noms, les abstractions et le niveau de qualité attendu.
4. Il charge la méthode spécialisée
Selon la tâche, l'agent charge une skill Nuxt, base de données, sécurité, contenu ou revue de code, sans alourdir les autres conversations.
5. Il récupère les données fraîches
Si une information manque ou peut avoir changé, l'agent utilise un outil ou MCP et ramène le résultat nécessaire avec sa source.
6. Il travaille par incréments vérifiables
Je préfère une petite modification suivie d'un test à une longue génération impossible à relire. Les erreurs du typecheck, les tests et le diff deviennent eux-mêmes du contexte pour l'étape suivante.
7. Il vérifie et laisse une trace
Le travail se termine par les commandes prévues, une revue du diff et un résumé des décisions, vérifications et limites. Cette trace aide la prochaine session sans conserver l'historique brut.
Les erreurs qui m'ont le plus appris
Donner trop de contexte
Joindre dix documents rassure, mais noie souvent la règle importante. Une grande fenêtre de contexte n'est pas une obligation de la remplir. Je commence avec le socle minimal, puis je laisse l'agent chercher ce qui manque.
Laisser cohabiter des instructions contradictoires
Une ancienne spec, un commentaire et un fichier de règles peuvent raconter trois versions du produit. Je définis une hiérarchie claire : règles explicites du dépôt, spec active, code et tests actuels, puis documentation de référence. En cas de contradiction, l'agent doit la signaler au lieu de choisir silencieusement.
Transformer la mémoire en source de vérité
La mémoire est utile pour conserver une préférence ou l'état d'une tâche longue. Elle ne remplace pas le dépôt, la base ou la documentation à jour. Une information critique doit pouvoir être vérifiée.
Ma checklist de context engineering
Avant de confier une tâche à un agent, je vérifie :
- Objectif : le résultat attendu et le hors-périmètre sont-ils explicites ?
- Autorité : quelle source fait foi en cas de contradiction ?
- Projet : l'agent connaît-il la stack, les dossiers et les contraintes non évidentes ?
- Exemples : existe-t-il une implémentation canonique à suivre ?
- Fraîcheur : certaines données doivent-elles être récupérées maintenant ?
- Outils : chaque tool a-t-il un rôle distinct et des permissions adaptées ?
- Garde-fous : secrets, données personnelles et actions risquées sont-ils protégés ?
- Validation : quelles commandes et quels scénarios prouvent que le résultat fonctionne ?
- Trace : que faut-il conserver pour la prochaine session ?
Ma question finale est simple : si je retire cette information, le comportement de l'agent risque-t-il réellement de changer ? Si la réponse est non, elle n'a probablement pas besoin d'entrer dans le contexte.
Questions fréquentes sur le context engineering
Le contexte est une partie du produit
Le context engineering n'est pas une astuce pour obtenir une meilleure réponse dans un chat. C'est un travail d'architecture : organiser ce qui doit être stable, ce qui doit être récupéré, ce qui doit être vérifié et ce qui ne doit jamais être exposé.
C'est ce qui sépare une démonstration d'un workflow répétable. Un meilleur modèle aide. Un meilleur contexte rend le résultat plus cohérent et les échecs plus faciles à comprendre.
C'est cette discipline que j'applique dans mes missions de Product Engineering : cadrer le besoin, structurer le contexte, construire, puis vérifier.
Et vous, quelle information manque le plus souvent à vos agents : les règles du projet, la connaissance métier ou les critères de validation ?
📌 Vous avez un projet web à lancer ou un produit existant à faire évoluer ? Je le conçois et le développe de bout en bout, en m'appuyant sur l'IA pour livrer plus vite. Découvrez mes services de Product Engineering.
Sources
- Google, « The New SDLC With Vibe Coding: From ad-hoc prompting to Agentic Engineering ».
- Anthropic, « Effective context engineering for AI agents ».
- OpenAI, « How OpenAI uses Codex ».
- OpenAI, « Recherche ChatGPT ».
- Claude Code, « How Claude remembers your project ».
- Model Context Protocol, documentation sur l'architecture de MCP.
- GitHub, serveur MCP GitHub officiel.