Une carte du code pour agents IA est un index local des fichiers, symboles, imports, tests et de l’historique des changements d’un dépôt, qu’un agent peut interroger pour trouver le bon code en quelques appels au lieu de faire des grep et de lire fichier après fichier. Moins de fichiers lus, c’est moins de choses dans la fenêtre de contexte, et moins de choses dans la fenêtre de contexte rend chaque tour suivant moins cher.
Cet article explique pourquoi les agents gaspillent des tokens à explorer, ce que contient une bonne carte, et comment la carte de projet d’AgentVera donne cet index à Claude Code, Codex et d’autres agents CLI via MCP.
Comment les agents explorent un dépôt sans carte
Donnez à un agent de code une tâche comme « ajouter un champ coupon au paiement » dans un dépôt inconnu, et il fait ce que vous feriez avec un simple terminal :
grep -r "checkout"et obtenir 200 résultats- Ouvrir les fichiers qui semblent prometteurs, souvent en entier
- Suivre les imports en lisant d’autres fichiers
- Chercher à nouveau le fichier de test
Chaque étape fait entrer du texte dans le contexte. Un fichier de 1 000 lignes lu une fois reste dans la conversation jusqu’à la fin de la session, et le modèle relit la conversation à chaque tour. Si les premières pistes étaient fausses, ces fichiers restent quand même là. C’est l’une des principales raisons pour lesquelles une session devient coûteuse bien avant que la vraie modification ne soit faite. Pour l’autre grande source, le contexte de base, voir réduire la consommation de tokens de Claude Code.
Ce que contient une carte du code utile
Une liste de fichiers ne suffit pas. Un agent doit pouvoir répondre à « où » et « qu’est-ce qui casse si je change ceci » sans lire de code. Une bonne carte contient :
| Couche | Répond à |
|---|---|
| Fichiers et modules | Que contient ce dépôt et comment est-il organisé ? |
| Symboles avec signatures | Où est applyCoupon et que prend-elle en paramètres ? |
| Imports | Qui utilise ce fichier, et qui utilise ceux-là ? |
| Tests liés | Quels tests couvrent ce code ? |
| Historique des changements conjoints | Quels fichiers changent habituellement avec celui-ci ? |
| Points d’entrée et commande de test | Où cela démarre-t-il et comment lancer les tests ? |
Les deux dernières couches comptent plus qu’il n’y paraît. L’historique git sait que checkout.ts, checkout.test.ts et pricing.ts changent souvent dans le même commit, même quand aucun import ne les relie.
Comment la carte de projet d’AgentVera est construite
AgentVera construit une carte de projet pour chaque dossier de projet :
- Symboles. tree-sitter lit les fonctions, classes, méthodes, interfaces, types, enums et constantes avec plages de lignes, signatures et première phrase du commentaire de documentation, pour TypeScript, TSX, JavaScript, Python et Go. Une trentaine d’autres langages sont indexés par chemin.
- Imports et tests. Les imports sont résolus vers des fichiers, et les tests sont liés au code qu’ils couvrent.
- Changements conjoints. Les fichiers qui ont changé ensemble dans au moins 2 des 500 derniers commits sont liés. Les commits qui touchent plus de 40 fichiers sont ignorés, pour qu’un gros renommage ne relie pas tout à tout.
- Ce qu’elle ignore. Elle part de
git ls-fileset respecte.gitignore. Elle ignorenode_modules,dist,build, les fichiers de plus de 1 Mo et les fichiers générés ou minifiés. Dans les dépôts de plus de 20 000 fichiers, elle n’indexe que les dossiers de sources commesrc,lib,appetpackages/*/src.
La carte est construite sur votre ordinateur et ne coûte aucun token. Elle surveille les changements de fichiers, recompte l’historique des changements conjoints à l’arrivée de commits, et revérifie un fichier quand un agent l’interroge. Une carte par dossier est partagée par tous les agents qui y travaillent : un projet et chacun de ses worktrees ont donc la leur. Elle est stockée compressée dans le dossier de données de l’application.
Les outils MCP utilisés par les agents
AgentVera ajoute à chaque agent un serveur MCP nommé agentvera-map. Ses instructions indiquent à l’agent de commencer une tâche par map_related, d’utiliser map_outline avant de lire un fichier et map_usages avant de modifier du code.
| Outil | Renvoie |
|---|---|
map_related | Les fichiers qu’une tâche concerne probablement, classés, avec les raisons (nom correspondant, imports, changés ensemble, tests) |
map_outline | Les symboles d’un fichier avec plages de lignes et signatures, ses imports, ses importeurs et ses tests |
map_usages | Qui appelle ou importe un symbole ou un fichier, à profondeur 2 les importeurs des importeurs, plus les tests qui le couvrent |
map_find | Symboles ou fichiers par nom approximatif, avec type, file:line et signature |
map_overview | Modules, tailles, points d’entrée et commande de test |
map_api | L’API réellement exportée d’un paquet installé, à la version présente dans node_modules, d’après ses déclarations de types |
map_related accepte une tâche en langage courant, dans n’importe quelle langue. Des mots turcs comme sepet, kupon ou ödeme correspondent à des noms de code anglais comme cart, coupon et payment.
map_api corrige une source discrète de bugs : un agent qui écrit des appels de mémoire pour une version de bibliothèque que vous n’avez pas. Il lit les fichiers .d.ts de la version réellement installée.
Les nouveaux agents reçoivent aussi dans leurs instructions un court résumé des modules, des points d’entrée et de la commande de test, pour ne pas passer leurs premiers tours à chercher comment lancer les tests.
Avant et après : la même tâche
Voici comment la tâche du coupon change. Les étapes sont typiques, pas un benchmark.
Sans carte :
grep -rn "checkout" src # 200 lines of hits
cat src/checkout/index.ts # whole file
cat src/checkout/summary.tsx # whole file, not the right one
cat src/pricing/total.ts # whole file
grep -rn "total(" src test # find callers and testsAvec la carte :
map_related "add a coupon field to checkout"
-> src/pricing/total.ts (name match, changed together with checkout)
-> src/checkout/CheckoutForm.tsx (imports total.ts)
-> test/pricing/total.test.ts (test)
map_outline src/pricing/total.ts # symbols and lines only
map_usages calculateTotal # callers and testsL’agent ne lit ensuite que les lignes dont il a besoin. La première version remplit le contexte de fichiers inutiles ; la seconde le remplit d’une liste classée et d’un plan.
Smart tools : quand l’agent lit quand même
Les agents ne consultent pas toujours la carte en premier. Pour Claude Code, les smart tools d’AgentVera interviennent via des hooks :
- La première lecture complète d’un fichier de plus de 800 lignes et 24 Ko renvoie à la place le plan issu de la carte de projet, pour que l’agent lise la partie dont il a besoin.
- Les relectures d’un fichier inchangé sont bloquées, puisque le contenu est déjà dans le contexte.
- Les exécutions de tests sont restreintes aux tests pertinents.
Pour comprendre le fonctionnement des hooks en général, lisez le guide des hooks Claude Code.
Activer et désactiver la carte
La carte de projet est activée par défaut et fait partie de l’offre gratuite.
- Ouvrez Settings → Token savings et trouvez l’interrupteur Project map. Il est activé sauf si vous l’avez coupé.
- Pour qu’un agent n’y ait pas accès, décochez sa case Project map dans la boîte de dialogue de modification de l’agent.
- Pour voir la carte, ouvrez la page Details du projet et l’onglet Project map. Elle dessine un graphe avec les imports en gris et les liens de changements conjoints en pointillés orange. Saisissez une tâche et appuyez sur Show pour voir ce que renverrait
map_related.
Si la carte n’est pas encore prête, par exemple juste après l’ouverture d’un gros dépôt, les outils répondent avec l’avancement de la construction. L’agent attend quelques secondes puis se rabat sur ses outils habituels.
Économise-t-elle vraiment des tokens ?
La réponse honnête : cela dépend du dépôt et de la tâche. Un petit dépôt où l’agent sait déjà où chercher y gagne peu. Un dépôt grand ou inconnu, où un agent lirait sinon une douzaine de mauvais fichiers, y gagne beaucoup.
Plutôt que de croire un chiffre, mesurez sur votre propre travail. L’onglet AI ROI a une carte Project map impact qui compare les conversations avec et sans carte selon la réussite, la réussite du premier coup, les tokens par tâche et les relances.
Limites à connaître
- Le détail des symboles concerne TypeScript, TSX, JavaScript, Python et Go. Les autres langages sont indexés au niveau des chemins.
- Les agents sur un hôte SSH distant n’ont pas la carte.
- Un agent ne lit que la carte de son propre dossier : un agent en worktree voit son worktree, pas le checkout principal.
- La fenêtre de carte du code dans la visite du projet d’AgentVera est une fonction distincte pour que vous exploriez le code ; c’est la carte de projet que les agents interrogent.
En résumé
Une carte du code pour agents IA remplace l’exploration aveugle par grep et lecture par quelques questions ciblées : quels fichiers, quels symboles, qui les utilise et quels tests les couvrent. La carte de projet d’AgentVera construit cet index en local avec tree-sitter et git, le tient à jour, et le fournit à tout agent compatible MCP via agentvera-map, tandis que les smart tools interceptent les lectures volumineuses et répétées dans Claude Code. Associez-la à une mémoire de projet partagée pour que les agents sachent à la fois où se trouve le code et pourquoi il est ainsi, et téléchargez AgentVera pour l’essayer sur votre plus gros dépôt.