Donner le bon contexte à l'IA

L'assistant ne lit pas votre dépôt comme vous le faites. Il prédit une sortie plausible à partir des tokens devant lui. Quand les bons tokens manquent, il ne s'arrête pas pour demander. Il comble le vide avec le code statistiquement le plus probable, qui semble généralement correct et suppose discrètement un monde qui n'est pas le vôtre.

Imaginez un développeur demandant à un assistant de corriger un analyseur de dates. Le prompt dit « parseDate retourne Invalid Date pour une mauvaise entrée, faites-le lancer une exception à la place. » Cela semble complet. Ce que le prompt a omis : la base de code a déjà une règle maison selon laquelle une entrée invalide lance un RangeError, et un appelant en aval intercepte exactement ce type. L'assistant, sans voir la règle ou l'appelant, écrit une correction propre qui lance une Error générique. Le test que le développeur surveillait passe au vert. Trois fichiers plus loin, la branche catch (e instanceof RangeError) cesse silencieusement de correspondre, et une vraie mauvaise date fait maintenant planter le gestionnaire de requêtes en production.

Rien dans cette histoire n'est un échec exotique du modèle. La sortie était plausible, le changement était mineur, et il a passé le seul test visible. Le défaut réside dans l'écart entre ce que le développeur savait et ce que le contexte contenait. Cet écart est la chose la plus coûteuse dans le codage assisté par IA, car une réponse plausible mais erronée survit à une lecture rapide d'une manière qu'une réponse manifestement incorrecte ne ferait jamais.

Le bénéfice de combler cet écart est concret. L'épine dorsale partagée de tout ce sujet est que l'assistant prédit à partir de son contexte, et votre contrôle provient de trois leviers : le contexte que vous fournissez, le plan que vous convenez avant qu'il n'écrive, et le diff que vous examinez avant de le conserver. Le contexte est le premier levier, et il fixe un plafond sur les deux autres. Un plan basé sur des faits manquants planifie la mauvaise chose, et un diff basé sur une mauvaise hypothèse est examiné comme correct. Le mécanisme qui vous permet de contrôler le contexte, le budget d'attention limité et où le modèle regarde réellement, est ce que la section suivante décompose.

Un modèle a un budget d'attention fixe qu'il dépense sur chaque token qu'il traite. Anthropic décrit une bonne ingénierie de contexte comme trouvant le plus petit ensemble possible de tokens à fort signal qui maximise la probabilité du résultat souhaité. Chaque token ajouté épuise ce budget, donc chaque token ajouté est un coût réel contre l'attention du modèle. Les parties que vous gérez sont les suivantes.

• Les artefacts. Les fichiers réels que le changement touche, les définitions de type et la configuration dont ils dépendent, et l'erreur ou le test échoué, collés tels quels pour que les numéros de ligne et les signatures survivent.
• Les contraintes. Ce qui ne doit pas changer, la convention à suivre, et à quoi ressemble le résultat final. Une contrainte est un contexte, car elle élimine une supposition que le modèle ferait autrement.
• Les règles permanentes. Les faits du projet qui ne changent jamais pour une tâche, conservés dans un fichier versionné que l'outil charge automatiquement plutôt que recollés à chaque fois.
• L'historique de la conversation. Tout ce qui a déjà été dit dans le fil, qui compte contre le budget qu'il soit encore pertinent ou non.

Deux faits sur la façon dont les modèles lisent déterminent si votre contexte est pris en compte. Le premier est la dégradation du contexte : chaque modèle de pointe testé devient moins précis à mesure que l'entrée grandit, car un transformateur doit suivre n carrés de relations par paires sur n tokens et l'attention s'étire. Les chercheurs ont constaté que la précision du modèle commence à baisser autour de 32 000 tokens même sur des modèles annoncés avec des fenêtres de millions de tokens. Une fenêtre plus grande n'est pas une raison pour coller plus.

Le second est la position. Les modèles prêtent fortement attention au début et à la fin du contexte et faiblement au milieu, un schéma documenté comme perdu au milieu par Liu et ses collègues en 2023. Leur étude a mesuré une baisse de précision de plus de 30 points de pourcentage lorsque le document de réponse est passé de la première position au milieu d'un contexte de vingt documents, entraîné par la position plutôt que par le contenu. Le geste pratique est de placer la contrainte porteuse et le fichier en cours de modification près du haut ou du bas de votre prompt, et de résister à l'envie de déposer un long bloc de faible valeur au milieu où l'élément important peut se cacher.

C'est pourquoi la distinction entre le contexte persistant et le contexte par tâche est importante. Les règles permanentes vont dans un fichier que l'outil lit à chaque session. CLAUDE.md est le fichier que Claude Code lit au début de la session. AGENTS.md est la norme ouverte inter-outils, donnée par OpenAI et lue nativement par Cursor, GitHub Copilot, Codex, Gemini CLI, et d'autres à travers 60 000 dépôts ou plus. Claude Code ne lit pas AGENTS.md par lui-même, donc une équipe utilisant plusieurs outils y pointe avec une seule ligne d'importation @AGENTS.md en haut de CLAUDE.md. Les faits par tâche vont dans le prompt. Garder les deux séparés empêche le fichier permanent de gonfler en un mur de contexte intermédiaire qui déclenche la dégradation. Avec le mécanisme en main, la section suivante parcourt un changement de bout en bout.

Maya, une développeuse, reprend le bug exact de la première section. L'utilitaire parseDate retourne Invalid Date pour un mois hors de portée, et un test échoué s'attend maintenant à ce qu'il lance une exception. Son premier réflexe est le prompt d'une ligne, « faire en sorte que parseDate lance une exception sur une mauvaise entrée. » Elle se reprend et construit plutôt le contexte.

1. Énoncer l'objectif et le comportement de réussite. Elle l'écrit en une phrase : « Faire en sorte que parseDate('2026-13-01') lance une exception au lieu de retourner Invalid Date, pour que le test échoué passe. »
2. Attacher uniquement ce que le changement touche. Elle mentionne src/util/parseDate.ts et parseDate.test.ts, ce qui intègre le contenu exact des fichiers dans le contexte. Elle ne colle pas le reste de src/util. Parce qu'elle utilise Claude Code, la lecture des fichiers dans ce sous-arbre fait également apparaître le CLAUDE.md imbriqué là, qui indique déjà la règle de lancer un RangeError.
3. Coller l'erreur telle quelle. Elle copie l'assertion réelle, AssertionError: expected [Function] to throw an error, plutôt que de la retaper. Le texte exact indique au modèle que le test vérifie une exception, pas une valeur de retour.
4. Mettre la contrainte en avant. En haut du prompt, elle écrit : garder la signature parseDate(input: string): Date, lancer un RangeError pour correspondre au style maison, et ne pas ajouter de bibliothèque de dates. La règle la plus porteuse est placée là où le modèle la lit le mieux.
5. Demander d'abord une reformulation. Elle termine par « reformulez la tâche et listez vos hypothèses avant de modifier. » L'assistant confirme qu'il lancera un RangeError et demande si le 29 février d'une année non bissextile compte également comme hors de portée. Cette question de clarification vaut plus que le code, car Maya n'y avait pas pensé.
6. Revoir et valider. Le diff retourné fait neuf lignes, lance le bon type, n'ajoute aucune dépendance, et le test passe au vert. Elle exécute la suite, confirme que le catch en aval correspond toujours, et valide.

Le avant et après est toute la leçon. Le prompt d'une ligne aurait produit un throw new Error(...) générique, un test vert, et le crash silencieux en production de la première section. Le contexte construit a coûté à Maya peut-être quatre-vingt-dix secondes et un échange de clarification, et il a produit une correction qui respectait une règle qu'elle n'avait même pas besoin de se rappeler, car elle vivait dans le fichier. Maya et ce même changement parseDate se poursuivent dans les pièges ci-dessous.

Chacun de ces pièges donne l'impression de donner plus au modèle pour travailler, tout en rendant discrètement la sortie pire.

• Coller tout le dépôt. Déverser chaque fichier semble exhaustif, mais cela enterre les lignes pertinentes sous des milliers de tokens et déclenche la dégradation du contexte. La solution est d'attacher le fichier en cours de modification plus ses dépendances directes, et de laisser l'outil récupérer le reste à la demande via la recherche ou les mentions @.
• Décrire au lieu de montrer. Retaper un bug avec vos propres mots fait perdre les numéros de ligne, les noms de champs exacts, et l'ordre des cadres de pile. Collez l'artefact réel. La trace verbatim est le contexte à plus fort signal que vous avez pour une tâche de débogage.
• Le fil sans fin. Une longue conversation garde chaque message précédent dans la fenêtre, donc une hypothèse obsolète d'il y a vingt tours oriente toujours la réponse. Quand les réponses commencent à dériver, commencez une nouvelle session avec un contexte propre et ciblé plutôt que d'en ajouter plus par-dessus.
• Laisser le résultat implicite. Si vous ne dites pas à quoi ressemble le succès, le modèle optimise pour un code qui semble plausible plutôt que pour votre résultat réel. Énoncez le comportement de réussite et les contraintes qui doivent tenir, comme l'a fait Maya.

Deux véritables cas limites se situent au-delà des règles simples. Le fait qui vit hors écran. Parfois, la cause est une valeur dans un fichier d'environnement ou un comportement dans une dépendance que vous ne penseriez jamais à attacher. Ici, l'approche juste-à-temps bat le pré-chargement : donnez à l'agent la capacité de rechercher et de lire, et un pointeur léger ("le délai est défini dans config/http.ts"), plutôt que de deviner à l'avance quel fichier contient la réponse.

La dépendance hallucinée. Un problème qui est encore présent en 2026 : les modèles inventent des packages qui n'existent pas. Une étude de USENIX Security 2025 a généré 576 000 échantillons de code et a trouvé que les modèles commerciaux hallucinaient des noms de packages à environ 5 % et les modèles open-source près de 22 %, et plus de la moitié de ces noms inventés réapparaissaient à travers les exécutions, ce qui est exactement ce qui rend le slopsquatting une attaque de chaîne d'approvisionnement viable. Un attaquant enregistre le nom plausible que le modèle continue de suggérer, et attend que quelqu'un l'installe. Ajouter une contrainte comme « ne pas ajouter de nouvelles dépendances sans demander » à votre fichier de règles permanentes ferme la plupart de ces cas, et toute nouvelle importation dans le diff mérite une vérification délibérée que le package est réel avant de l'installer. Garder ces gardes cohérents à travers une équipe est là où l'échelle entre en jeu.

Un développeur peut garder les conventions en tête et les recoller au besoin. Dès qu'une deuxième personne, une deuxième machine ou un deuxième mois est impliqué, cette habitude doit vivre dans un artefact versionné, sinon chaque prompt s'éloigne un peu plus de la façon dont le projet fonctionne réellement.

L'artefact durable est un fichier de règles enregistré que l'outil charge automatiquement. CLAUDE.md est lu au début de chaque session Claude Code. AGENTS.md est devenu la norme inter-outils, lue nativement par Cursor, GitHub Copilot, Codex, et d'autres, donc un seul fichier peut servir une équipe utilisant plusieurs outils. Claude Code lit son propre CLAUDE.md plutôt que AGENTS.md, donc le modèle commun est un AGENTS.md avec une ligne d'importation @AGENTS.md en haut de CLAUDE.md, ce qui garde les deux outils pointés vers la même source de vérité. Gardez le fichier court et à fort signal : la stack, les conventions de nommage et de gestion des erreurs, et un petit bloc ## Préféré / ## À éviter avec du code réel, qui est l'une des choses les plus efficaces qu'un fichier de contexte puisse contenir. Élaguer-le lorsqu'une défaillance de l'agent révèle un écart, et résistez à le laisser croître en un mur de contexte intermédiaire qui annule le but.

Une responsable, Priya, possède la partie que le fichier individuel ne peut pas. Elle ajoute deux lignes au modèle de demande de tirage : quel assistant a produit le changement et le prompt ou la tâche qui l'a motivé. Cet enregistrement transforme une vague inquiétude du réviseur en une question concrète, car examiner la sortie de l'IA signifie demander « quelles hypothèses ce code fait-il, et sont-elles sûres ? » plutôt que « cela semble-t-il raisonnable ? ». Elle garde également les demandes de tirage petites, sous environ 400 lignes, car la capacité de révision est maintenant le goulot d'étranglement, avant le volume de code, et un diff serré est le seul type qu'un humain peut réellement vérifier par rapport aux contraintes.

L'échelle déplace également l'origine du contexte. Les règles permanentes vont dans le fichier versionné, le test échoué et l'erreur restent par tâche dans le prompt, et les connaissances partagées dont le modèle a besoin à l'exécution passent derrière des outils que l'agent peut interroger, plutôt que d'être collées dans chaque conversation. La séparation garde chaque surface légère.

Le principe durable à garder, quelle que soit la taille de l'équipe : l'assistant n'est aussi bon que le contexte à fort signal qu'il peut voir, et votre travail est de réduire ce contexte au minimum à fort signal. Commencez par une petite chose. Déplacez les trois conventions que vous retapez le plus souvent dans un CLAUDE.md ou AGENTS.md aujourd'hui, et arrêtez de les coller à la main.