Guillaume Duvernay

Votre agent n’a pas lu le contenu de votre dossier

7 min de lecture

agentscontextworkspaces

Quand on commence à travailler avec un agent dans un dossier, on suppose qu’il connaît tout ce qui s’y trouve. Vos notes, les fichiers de vos clients, le processus que vous avez consigné le mois dernier. Tout est là, alors il l’a forcément lu, non ?

Eh bien non. Quand vous ouvrez une nouvelle conversation, l’agent ne sait presque rien de ce que contient votre dossier. Il sait que le dossier existe et qu’il peut en consulter le contenu.

Ce qu’il a réellement au démarrage

À la première question, le modèle reçoit une courte liste d’éléments :

  • les instructions que l’application lui a fournies (comment se comporter, comment utiliser chaque outil),
  • la description des outils auxquels il peut faire appel,
  • un de vos fichiers, si vous en avez créé un : AGENTS.md,
  • et votre message.

Voilà tout ce qu’il a. Pour le reste du dossier, il doit chercher : afficher la liste des fichiers, lancer des recherches, ouvrir ceux qui semblent pertinents. Chacune de ces actions correspond à un appel d’outil, comme lorsqu’il effectue une recherche sur le Web.

Pendant mon atelier, je le montre avec un dossier contenant 20 fichiers de tâches. Dans une nouvelle conversation, je demande en quoi consiste la tâche 10. L’agent ne répond pas tout de suite. Il cherche dans le dossier, trouve le fichier, le lit, puis répond. Ça marche, mais il a dû aller chercher l’information.

Les tailles sont données à titre indicatif et varient selon l’application. L’essentiel, c’est ce qui manque : sur les 20 fichiers de tâches du dossier, seul celui qu’il a ouvert parvient jusqu’au modèle.

Pourquoi c’est une bonne chose

C’est frustrant au début. Ce serait pratique si l’agent savait tout, tout simplement.

Mais réfléchissez au coût. Chaque message que vous envoyez s’ajoute à tout ce que reçoit le modèle : les instructions de l’application, les descriptions des outils, vos fichiers et toute la conversation jusque-là. Si votre dossier était chargé à chaque fois, vous paieriez pour tout ce contenu à chaque message, et le modèle devrait retrouver le paragraphe qui vous intéresse au milieu de tout le reste.

Les modèles récents peuvent traiter énormément de contenu, jusqu’à environ un million de jetons pour certains. Mais avoir plus de place ne rend pas tout utile. Le texte en plus crée du bruit, et le modèle peut s’y perdre, comme vous. Je veille à ce que chaque jeton présent ait une bonne raison de l’être.

C’est donc parce que l’agent ne connaît pas votre dossier que vous gardez le contrôle. Vous choisissez ce qu’il doit toujours savoir, et vous organisez le reste pour qu’il trouve vite les informations.

AGENTS.md : votre emplacement garanti

AGENTS.md est un fichier texte brut, placé à la racine de votre dossier. L’application le lit au début de chaque conversation et l’ajoute au contexte du modèle, à côté de ses propres instructions. C’est le seul endroit où certaines informations sont toujours gardées en mémoire.

Mon test : ouvrez une nouvelle conversation et demandez « Qui suis-je ? ». Si votre rôle figure dans AGENTS.md, l’agent répond tout de suite, sans ouvrir le moindre fichier. Même chose pour une règle comme « Réponds toujours en trois puces ». Inscrivez-la là, et toutes ses réponses la respecteront.

Même conversation, deux questions. La première réponse vient d’AGENTS.md. Pour la seconde, il faut aller chercher l’information.

Auparavant, Claude Code ne lisait qu’un fichier nommé CLAUDE.md. Les versions récentes lisent aussi AGENTS.md, le nom utilisé par Codex et la plupart des autres outils. Un seul fichier suffit donc pour tous. Si le vôtre ne semble pas être pris en compte, demandez à l’agent quelles instructions il a chargées. J’explique aussi comment utiliser un seul fichier pour tous les outils dans garder vos dépôts indépendants de l’environnement d’exécution.

Ce qu’il faut y mettre, et ce qu’il ne faut pas y mettre

Ma règle est simple : si une information n’est pas utile pour presque chaque message, elle n’a pas sa place dans AGENTS.md. Un fichier trop long consomme des tokens à chaque message et noie les règles importantes.

AGENTS.md tient sur une page. Son rôle est d’indiquer ce qui est toujours vrai et où trouver le reste.

La deuxième colonne n’est pas moins importante. Elle n’a simplement pas besoin d’être consultée à chaque message. AGENTS.md y renvoie (« pour toute question concernant un client, consultez d’abord son fichier information.md »), et l’agent l’ouvre quand la tâche le nécessite. C’est ce qui permet de travailler efficacement dans un dossier volumineux.

À vous d’essayer

Ouvrez une nouvelle conversation dans votre dossier et demandez : « Qui suis-je et quelles instructions avez-vous chargées au début de cette conversation ? »

Si la réponse est vague, soit votre fichier AGENTS.md est absent, soit il ne contient pas les informations importantes. Demandez à l’agent de vous aider à le rédiger. Puis limitez-le à une page.