Sysls avertit : surcharger Claude et Codex avec du contexte peut réduire les performances

Auteur : sysls

Traduction : Deep潮 TechFlow

Guide de Shenchao : Le développeur et blogueur sysls, suivi par 2,6 millions de personnes, a rédigé un article pratique et détaillé partagé par 827 personnes et aimé par 7 000 utilisateurs, dont le cœur réside en une seule phrase : vos plugins, systèmes de mémoire et diverses structures aident probablement plus qu’ils n’entravent. Cet article ne se contente pas de théories abstraites, mais présente des principes opérationnels tirés directement de projets réels — de la gestion du contexte et de la gestion des tendances d’obéissance de l’IA à la définition des conditions d’arrêt des tâches. C’est sans doute l’article le plus clair que nous ayons vu sur les pratiques d’ingénierie avec Claude/Codex.

Le texte complet est le suivant :

Vous êtes un développeur qui utilise quotidiennement Claude et Codex CLI, vous vous demandez chaque jour si vous avez vraiment exploité toute leur puissance. Parfois, vous voyez qu’ils font des choses absurdes, et vous ne comprenez pas pourquoi certaines personnes semblent construire des fusées avec l’IA, tandis que vous ne parvenez même pas à empiler deux pierres correctement.

Tu penses que c’est un problème de ton harness, de ton plugin, de ton terminal, etc. Tu as utilisé beads, opencode, zep, et ton fichier CLAUDE.md contient 26 000 lignes. Mais peu importe ce que tu essaies, tu ne comprends toujours pas pourquoi tu t’éloignes de plus en plus du paradis, tandis que les autres jouent avec les anges.

C'est l'article que vous attendiez depuis tout ce temps.

De plus, je n'ai aucun intérêt personnel. Je considère que CLAUDE.md inclut AGENT.md, et que Claude inclut Codex ; j'utilise intensivement les deux.

Au cours des derniers mois, j'ai observé un fait intéressant : presque personne ne sait vraiment comment maximiser les capacités d'un agent.

Cela ressemble à un petit groupe de personnes capables de faire construire le monde entier par des agents, tandis que les autres tournent en rond dans une mer d’outils, souffrant du syndrome du choix — pensant qu’en trouvant le bon package, les bonnes compétences ou la bonne combinaison de harness, ils pourront débloquer l’AGI.

Aujourd'hui, je veux tout briser et vous laisser cette phrase simple et honnête, puis nous partirons de là. Vous n'avez pas besoin du dernier proxy harness, pas besoin d'installer un million de packages, et vous n'avez absolument pas besoin de lire un million d'articles pour rester compétitif. En fait, votre passion est probablement plus nuisible que bénéfique.

Je ne suis pas là pour faire du tourisme — je l’utilise depuis que les agents étaient à peine capables d’écrire du code. J’ai testé tous les packages, tous les harness, tous les paradigmes. J’ai utilisé des usines d’agents pour écrire des signaux, des infrastructures et des pipelines de données, pas des « projets jouets », mais des cas d’utilisation réels en production. Après avoir fait tout cela…

Aujourd'hui, j'ai utilisé une configuration presque aussi simple qu'il est possible de l'être, uniquement les CLI de base (Claude Code et Codex), accompagnée d'une compréhension des quelques principes fondamentaux du génie des proxys, pour réaliser mon travail le plus novateur jusqu'à présent.

Premièrement, je dois dire que les entreprises de modèles de base sont en pleine course historique, et il est clair qu'elles ne ralentiront pas rapidement. Chaque amélioration de l'« intelligence d'agent » change la manière dont vous collaborez avec elles, car les agents sont conçus pour obéir de plus en plus volontiers aux instructions.

Il y a à peine quelques générations, si vous écriviez dans CLAUDE.md : « Lisez READTHISBEFOREDOINGANYTHING.md avant de faire quoi que ce soit », il avait 50 % de chances de vous répondre « Allez vous faire voir » puis d’agir selon ses propres désirs. Aujourd’hui, il obéit à la plupart des instructions, y compris des instructions complexes et imbriquées — par exemple, vous pouvez dire : « Lisez d’abord A, puis B, et si C, alors lisez D » ; dans la plupart des cas, il acceptera volontiers de suivre.

What does this mean? The most important principle is to recognize that each new generation of agents forces you to reconsider what the optimal solution is, which is precisely why less is more.

Lorsque vous utilisez de nombreuses bibliothèques et des harness différents, vous vous enfermez dans une « solution », mais ce problème pourrait tout simplement ne pas exister face aux agents de la prochaine génération. Savez-vous qui sont les utilisateurs les plus enthousiastes et les plus gros consommateurs d'agents ? C'est exactement cela : les employés des entreprises de pointe, qui disposent d'un budget infini en tokens et utilisent les modèles les plus récents. Comprenez-vous ce que cela signifie ?

Cela signifie que si un problème réel existe et qu'une bonne solution est disponible, les entreprises de pointe en seront les principaux utilisateurs. Et ensuite, que font-elles ? Elles intègrent cette solution dans leurs propres produits. Pensez-y : pourquoi une entreprise permettrait-elle à un autre produit de résoudre des douleurs réelles et de créer une dépendance externe ? Comment puis-je savoir que c'est vrai ? Regardez les compétences, le harness de mémoire, les sous-agents… Ce sont tous des « solutions » nées de la résolution de problèmes réels, éprouvées sur le terrain et démontrées comme véritablement utiles.

Ainsi, si quelque chose est véritablement révolutionnaire et permet d'étendre les cas d'utilisation des agents de manière significative, il sera inévitablement intégré au produit principal de l'entreprise de base. Croyez-moi, l'entreprise de base progresse à grande vitesse. Alors détendez-vous, vous n'avez pas besoin d'installer quoi que ce soit ni de dépendre à des dépendances externes pour accomplir votre meilleur travail.

Je prévois que les commentaires vont bientôt affluer avec des messages du type « SysLS, j'ai utilisé tel harness, c'est génial ! J'ai reconstruit Google en une journée ! » — à ce sujet, je dis : Félicitations ! Mais vous n'êtes pas le public cible ; vous représentez un groupe extrêmement minoritaire de la communauté qui a véritablement compris l'ingénierie des agents.

Vraiment. Le contexte est tout. Un autre problème avec l'utilisation de mille plugins et dépendances externes est que vous souffrez d'une « inflation du contexte » — c'est-à-dire que votre agent est submergé par trop d'informations.

Faisons un jeu de devinettes avec Python ? Facile. Attendez, quel est ce commentaire sur « la gestion de la mémoire » datant de 26 sessions précédentes ? Ah, l'utilisateur avait un écran bloqué il y a 71 sessions à cause de la création excessive de sous-processus. Faut-il toujours écrire des commentaires ? D'accord, pas de problème... Mais qu'est-ce que ça a à voir avec le jeu de devinettes ?

Tu comprends. Tu veux simplement fournir à l'agent les informations exactes nécessaires pour accomplir la tâche, ni plus ni moins ! Plus tu maîtrises cela, mieux l'agent performe. Dès que tu commences à introduire des systèmes de mémoire étranges, des plugins, ou trop de noms et d'appels de compétences confus, tu donnes à l'agent à la fois un manuel pour fabriquer une bombe et une recette de gâteau, alors que tu veux simplement qu'il écrive un poème sur une forêt de séquoias.

Alors, je prêche à nouveau — éliminez toutes les dépendances, puis...

Décrire précisément les détails de mise en œuvre

Remember that context is everything?

Do you remember that you wanted to inject into the agent exactly the information needed to complete the task, no more and no less?

La première méthode pour y parvenir consiste à séparer la recherche de la mise en œuvre. Vous devez être extrêmement précis sur ce que vous demandez à l'agent de faire.

Quelles sont les conséquences d'une imprecision ? « Mettez en place un système d'authentification. » L'agent doit alors étudier : qu'est-ce qu'un système d'authentification ? Quelles sont les solutions possibles ? Quels sont leurs avantages et inconvénients respectifs ? Il doit désormais chercher en ligne une quantité d'informations dont il n'a en réalité pas besoin, saturant le contexte de détails d'implémentation possibles. Lorsqu'il vient réellement à l'implémentation, il est plus susceptible de se confondre ou de développer des hallucinations inutiles ou non pertinentes sur la solution d'implémentation choisie.

À l'inverse, si vous dites « implémenter l'authentification JWT avec un hachage de mot de passe bcrypt-12, un rotation des jetons de rafraîchissement et une expiration de 7 jours », il n'est pas nécessaire d'étudier d'autres solutions alternatives : on comprend exactement ce que vous voulez, ce qui permet de remplir le contexte avec les détails d'implémentation.

Bien sûr, vous ne saurez pas toujours les détails de mise en œuvre. Souvent, vous ne savez pas ce qui est correct, et parfois, vous souhaitez même déléguer la prise de décision sur les détails de mise en œuvre à un agent. Que faire dans ce cas ? C’est simple — créez une tâche de recherche pour explorer les différentes possibilités de mise en œuvre, que vous décidiez vous-même ou que vous laissiez l’agent choisir la méthode à utiliser, puis faites implémenter par un autre agent doté d’un nouveau contexte.

Une fois que vous commencez à penser ainsi, vous remarquerez les endroits où le contexte des agents pollue inutilement le flux de travail, puis vous pourrez établir des isolateurs dans le flux de travail des agents, en abstrayant les informations inutiles tout en conservant uniquement le contexte spécifique qui permet à l'agent d'exceller dans sa tâche. Rappelez-vous que vous avez un membre d'équipe très talentueux et intelligent, qui connaît tous les types de balles de l'univers — mais à moins que vous ne lui disiez que vous souhaitez concevoir un espace pour faire danser et profiter les gens, il continuera de vous parler des avantages des objets sphériques.

Limitations de conception liées à la tendance à plaire

Personne ne veut utiliser un produit qui ne cesse de vous critiquer, de vous dire que vous avez tort, ou d'ignorer complètement vos instructions. Ces agents s'efforcent donc de vous approuver et de faire ce que vous voulez.

Si vous lui demandez d'ajouter « heureux » après chaque trois mots, elle fera de son mieux pour obéir — la plupart des gens comprennent cela. Sa capacité à obéir est précisément ce qui en fait un produit si utile. Mais elle possède une caractéristique très intéressante : cela signifie que si vous dites « Aide-moi à trouver un bogue dans le dépôt de code », elle trouvera un bogue — même s'il faut le « créer ». Pourquoi ? Parce qu'elle veut extrêmement bien obéir à vos instructions !

La plupart des gens se plaignent rapidement que les LLM inventent des choses et créent des hallucinations, sans réaliser que le problème vient d'eux-mêmes. Vous lui demandez de trouver quelque chose, et il vous le fournit — même si cela nécessite de légèrement déformer les faits !

Alors, que faire ? J'ai constaté que les instructions neutres sont très efficaces, c'est-à-dire ne pas orienter l'agent vers un résultat spécifique. Par exemple, au lieu de dire « Aide-moi à trouver un bogue dans la base de données », je dis : « Analyse l'ensemble de la base de données, suis la logique de chaque composant et rends compte de toutes les découvertes. »

Ces notifications neutres peuvent parfois révéler des bugs, ou simplement décrire objectivement le fonctionnement du code. Mais elles ne biaisent pas l'agent vers une présumée présence de bugs.

Une autre façon de gérer la tendance à plaire est de la transformer en atout. Je sais que l’agent s’efforce de me plaire et de suivre mes instructions, je peux donc orienter cela dans un sens ou dans un autre.

J'ai donc demandé à un agent de détection de bogues d'identifier tous les bogues dans la base de données, en lui indiquant qu'un bogue à faible impact vaut +1 point, un bogue avec un impact modéré vaut +5 points, et un bogue grave vaut +10 points. Je sais que cet agent sera très enthousiaste à identifier tous les types de bogues (y compris ceux qui ne sont pas réellement des bogues), puis me rapportera un score de 104 points ou quelque chose du genre. Je considère cela comme le sur-ensemble de tous les bogues possibles.

Ensuite, j'ai fait intervenir un agent adversarial pour contester les bogues, en lui indiquant qu'il gagnait le score du bogue pour chaque contestation réussie, mais perdait deux fois le score du bogue en cas de contestation erronée. Cet agent s'efforce de contester le plus grand nombre possible de bogues, mais, en raison du mécanisme de pénalité, il reste prudent. Il continue néanmoins à contester activement les bogues (y compris les bogues réels). Je considère cela comme un sous-ensemble de tous les bogues réels.

Enfin, j'ai fait appel à un arbitre pour synthétiser les entrées des deux agents et leur attribuer des notes. J'ai informé l'arbitre que je possédais la réponse correcte réelle : il attribuait +1 point pour une réponse correcte et -1 point pour une erreur. L'arbitre a ensuite évalué séparément les agents « détection de bogue » et « agent adversarial » sur chaque « bogue ». Selon ce que l'arbitre déclarait comme vérité, je vérifiais. Dans la plupart des cas, cette méthode s'est révélée étonnamment fiable ; bien qu'elle commette parfois des erreurs, elle constitue désormais une opération quasi infaillible.

Vous pourriez trouver qu’il suffit de chercher des agents de détection de bugs individuels, mais cette méthode fonctionne très bien pour moi, car elle exploite la caractéristique innée de chaque agent — le désir de plaire.

Cette question semble complexe, comme si vous deviez approfondir vos connaissances et suivre en permanence les dernières avancées en IA, mais en réalité, elle est simple… Si OpenAI et Claude l’ont toutes deux implémentée ou ont acquis l’entreprise qui l’a mise en œuvre… alors elle est probablement utile.

Avez-vous remarqué que les « compétences (skills) » sont désormais omniprésentes et font partie de la documentation officielle de Claude et Codex ? Avez-vous remarqué qu’OpenAI a acquis OpenClaw ? Avez-vous remarqué que Claude a immédiatement ajouté des fonctionnalités de mémoire, de voix et de travail à distance ?

Comment se passe la planification ? Vous vous souvenez quand beaucoup de gens ont découvert que planifier avant d’implémenter était vraiment utile, et que cela est devenu une fonctionnalité essentielle ?

Oui, ceux-là sont utiles !

Souvenez-vous des stop-hooks interminables, extrêmement utiles parce que les agents refusaient catégoriquement d’effectuer des tâches de longue durée… puis Codex 5.2 est sorti, et ce besoin a disparu du jour au lendemain ?

C'est tout ce que vous devez savoir... Si quelque chose est vraiment important et utile, Claude et Codex le mettront en œuvre eux-mêmes ! Vous n'avez donc pas besoin de vous inquiéter trop de l'utilisation ou de la familiarisation avec les « nouvelles choses » ; vous n'avez même pas besoin de « rester à jour ».

Aide-moi un peu. Mets à jour occasionnellement ton outil CLI sélectionné et lis les nouvelles fonctionnalités ajoutées. C’est suffisant.

Certaines personnes utilisant un proxy tombent dans un piège énorme : parfois, il semble être la chose la plus intelligente sur Terre, et d'autres fois, vous ne pouvez pas croire qu'il vous a trompées.

Is this smart? This is fucking stupid!

La principale différence réside dans le fait que les agents sont ou non contraints de faire des hypothèses ou de « combler les lacunes ». Aujourd'hui, ils sont encore extrêmement mauvais pour « relier les points », « combler les lacunes » ou faire des hypothèses. Dès qu'ils le font, on le remarque immédiatement, et la qualité s'effondre clairement.

L'une des règles les plus importantes dans CLAUDE.md concerne la manière d'obtenir le contexte et indique à l'agent de lire en premier cette règle à chaque fois qu'il lit CLAUDE.md (c'est-à-dire après chaque compression). Dans le cadre de la règle d'obtention du contexte, quelques instructions simples peuvent avoir un grand impact : relire le plan de tâche et relire (les fichiers liés à la tâche) avant de continuer.

Nous, les humains, avons une compréhension assez claire de ce que signifie « terminer » une tâche. Pour les agents, le plus grand problème actuel de l'intelligence artificielle est qu'ils savent comment commencer une tâche, mais pas comment la terminer.

Cela conduit souvent à des résultats très frustrants : l'agent termine en implémentant un ensemble de stubs.

Les tests constituent une excellente étape pour l'agent, car ils sont déterministes et permettent de définir des attentes très claires. À moins que ces X tests ne soient réussis, votre tâche n'est pas terminée ; et vous n'êtes pas autorisé à modifier les tests.

Ensuite, il vous suffit de vérifier les tests ; une fois tous les tests réussis, vous pourrez être serein. Vous pouvez également automatiser cela, mais l'essentiel est de se souvenir que « la fin d'une tâche » est naturelle pour les humains, pas pour les agents.

Savais-tu que quelque chose d'autre est devenu un point d'achèvement de tâche récent ? Capture d'écran + vérification. Tu peux demander à l'agent d'implémenter quelque chose jusqu'à ce que tous les tests réussissent, puis de prendre une capture d'écran et de vérifier le « design ou le comportement » sur la capture d'écran.

Cela vous permet de faire itérer l'agent et de l'orienter vers le design que vous souhaitez, sans craindre qu'il s'arrête après la première tentative !

La prolongation naturelle consiste à établir un « contrat » avec l'agent et à l'intégrer aux règles. Par exemple, ce fichier `{TASK}CONTRACT.md` définit les actions à accomplir avant que vous ne soyez autorisé à mettre fin à la session. Dans `{TASK}CONTRACT.md`, vous spécifierez les tests, captures d'écran et autres vérifications à effectuer avant de valider la fin de la tâche !

Une question que l'on me pose souvent est de savoir comment faire fonctionner un agent en continu pendant 24 heures tout en s'assurant qu'il ne dérive pas.

Il existe une méthode très simple : créez un stop-hook qui empêche l'agent de terminer la session tant que toutes les sections de `{TASK}_CONTRACT.md` ne sont pas terminées.

Si vous avez 100 contrats avec des spécifications claires contenant le contenu que vous souhaitez créer, stop-hook empêchera l'agent de s'arrêter jusqu'à ce que tous les 100 contrats soient terminés, y compris tous les tests et validations nécessaires !

Conseil professionnel : Je constate que les sessions de 24 heures prolongées ne sont pas optimales pour « accomplir des tâches ». En partie parce que cette approche structurellement impose un élargissement du contexte, puisque le contexte de contrats non liés entre eux est intégré dans la même session !

Je ne recommande donc pas de le faire.

Voici une meilleure méthode d'automatisation des agents — ouvrez une nouvelle session pour chaque contrat. Créez le contrat chaque fois que vous devez effectuer une action.

Établir une couche d'orchestration pour créer un nouveau contrat lorsqu'une action doit être effectuée, et créer une nouvelle session pour gérer ce contrat.

Cela va radicalement transformer votre expérience d'agent.

Vous avez embauché un assistant administratif : attendez-vous à ce qu’il connaisse votre emploi du temps dès le premier jour ? Ou comment vous prenez votre café ? Est-ce que vous dînez à 18h plutôt qu’à 20h ? Évidemment non. Vous établissez vos préférences progressivement avec le temps.

Il en va de même pour les agents. Commencez par la configuration la plus simple, oubliez les structures complexes ou les harness, et donnez une chance au CLI de base.

Ensuite, ajoutez progressivement vos préférences. Comment faire ?

Règles

Si vous ne voulez pas que l'agent fasse quelque chose, écrivez-le comme une règle. Ensuite, informez l'agent de cette règle dans CLAUDE.md. Par exemple : « Avant d'écrire du code, lisez `coding-rules.md`. » Les règles peuvent être imbriquées et peuvent être conditionnelles ! Si vous écrivez du code, lisez `coding-rules.md` ; si vous écrivez des tests, lisez `coding-test-rules.md`. Si vos tests échouent, lisez `coding-test-failing-rules.md`. Vous pouvez créer des règles avec des branches logiques arbitraires que l'agent suivra ; Claude (et Codex) accepteront volontiers de les suivre, à condition qu'elles soient clairement indiquées dans CLAUDE.md.

En fait, voici ma première recommandation concrète : traitez votre fichier CLAUDE.md comme un répertoire logique et hiérarchique qui indique où trouver le contexte dans des scénarios et résultats spécifiques. Il doit être aussi concis que possible, ne contenant que des logiques IF-ELSE du type « dans quelles circonstances chercher le contexte où ».

Si tu vois l'agent faire quelque chose que tu n'approuves pas, ajoute-le comme règle et dis-lui de lire cette règle avant de le refaire ; il ne le fera plus jamais.

Compétences

Les compétences (Skills) fonctionnent de manière similaire aux règles, mais elles sont mieux adaptées à la définition d'« étapes d'opération » qu'à une préférence de codage. Si vous avez une méthode spécifique pour accomplir une tâche, vous pouvez l'intégrer dans une compétence.

En réalité, les gens se plaignent souvent de ne pas savoir comment un agent résoudra un problème, ce qui crée de l'insécurité. Si vous souhaitez rendre cela plus prévisible, faites en sorte que l'agent étudie d'abord la manière dont il résoudra ce problème, puis rédige la solution sous forme de fichier de compétence. Vous pourrez ainsi anticiper la façon dont l'agent traitera le problème et corriger ou améliorer sa méthode avant qu'il ne le rencontre réellement.

Comment faire savoir à l'agent l'existence de cette compétence ? Exactement ! Tu l'écris dans CLAUDE.md : lorsque tu rencontres ce scénario et que tu dois gérer cela, lis ce fichier `SKILL.md`.

Règles et compétences de traitement

Vous voulez certainement continuer à ajouter des règles et des compétences à votre agent. C’est ainsi que vous lui donnez une personnalité et que vous mémorisez vos préférences. Presque tout le reste est superflu.

Une fois que tu commences à le faire, ton agent aura l'air magique. Il agira « exactement comme tu le souhaites ». Enfin, tu te sentiras vraiment « avoir compris » l'ingénierie des agents.

Then...

Vous verrez les performances commencer à décliner à nouveau.

Qu'est-ce qui se passe ?!

C’est très simple. Plus vous ajoutez de règles et de compétences, plus elles commencent à se contredire, ou plus l’agent souffre d’un élargissement contextuel sérieux. Si vous devez faire lire 14 fichiers Markdown à l’agent avant qu’il ne commence à programmer, il aura le même problème avec une quantité inutile d’informations.

Que faire ?

Nettoyez. Envoyez votre agent faire un « spa », intégrez les règles et les compétences, et éliminez les contradictions en indiquant vos préférences mises à jour.

Then it will feel like magic again.

C'est tout. C'est vraiment la clé. Gardez les choses simples, utilisez des règles et des compétences, traitez CLAUDE.md comme un tableau des matières, et faites attention avec sérieux à leur contexte et à leurs limites de conception.

Il n'existe pas de proxy parfait aujourd'hui. Vous pouvez déléguer beaucoup de travail de conception et d'implémentation au proxy, mais vous restez responsable du résultat.

Alors soyez prudent… et profitez bien !

C’est un plaisir de jouer avec les jouets du futur (tout en les utilisant visiblement pour des choses sérieuses) !