# Carte du code pour agents IA : trouver sans grep

URL: https://agentvera.dev/fr/blog/codebase-map-for-ai-agents/ · Publié: 2026-10-24

Une carte du code pour agents IA : un index local des fichiers, symboles, imports et tests aide Claude Code et Codex à trouver le bon code en lisant moins.

**En bref:**

- Sans carte, les agents explorent avec grep et en lisant des fichiers entiers. Chaque fichier lu entre dans la fenêtre de contexte et est repayé à chaque tour suivant.
- La carte de projet d’AgentVera indexe fichiers, symboles, imports, tests liés et fichiers qui changent ensemble, construite en local avec tree-sitter : la construire ne coûte aucun token.
- Les agents l’interrogent via MCP : map_related pour les fichiers d’une tâche, map_outline avant de lire, map_usages avant de modifier, map_api pour l’API réelle d’un paquet installé.

**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 :

1. `grep -r "checkout"` et obtenir 200 résultats
2. Ouvrir les fichiers qui semblent prometteurs, souvent en entier
3. Suivre les imports en lisant d’autres fichiers
4. 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](/fr/blog/claude-code-token-usage/ "Réduire de 61 % 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](/fr/features/project-map/ "Carte du 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-files` et respecte `.gitignore`. Elle ignore `node_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 comme `src`, `lib`, `app` et `packages/*/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 :**

```text
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 tests
```

**Avec la carte :**

```text
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 tests
```

L’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](/fr/features/smart-tools/ "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](/fr/blog/claude-code-hooks-guide/ "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.

1. Ouvrez **Settings → Token savings** et trouvez l’interrupteur **Project map**. Il est activé sauf si vous l’avez coupé.
2. 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.
3. 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](/fr/blog/shared-memory-for-ai-coding-agents/ "Mémoire partagée pour agents de code IA") pour que les agents sachent à la fois où se trouve le code et pourquoi il est ainsi, et [téléchargez AgentVera](/fr/download/) pour l’essayer sur votre plus gros dépôt.

## Questions fréquentes

**Qu’est-ce qu’une carte du code pour agents IA ?** Un index d’un dépôt qu’un agent peut interroger au lieu de chercher à l’aveugle : quels fichiers existent, quels symboles ils définissent, qui les importe, quels tests les couvrent et quels fichiers changent habituellement ensemble.

**Une carte du code réduit-elle les tokens de Claude Code ?** Elle peut le faire. Chaque fichier lu par un agent reste dans son contexte et est relu aux tours suivants. Si l’agent demande d’abord un plan ou une liste de fichiers classés, il lit moins de choses, et plus petites. L’économie dépend du dépôt et de la tâche.

**Quels langages la carte de projet d’AgentVera comprend-elle ?** Elle lit les symboles de TypeScript, TSX, JavaScript, Python et Go, avec plages de lignes, signatures et première phrase du commentaire de documentation. Une trentaine d’autres langages sont indexés par chemin.

**Construire la carte coûte-t-il des tokens ?** Non. La carte est construite sur votre ordinateur avec tree-sitter et git, et tenue à jour quand les fichiers changent et que des commits arrivent. Seules les réponses demandées par un agent entrent dans son contexte.

**Quels agents peuvent utiliser la carte de projet ?** Tous les agents CLI d’AgentVera qui acceptent des serveurs MCP, comme Claude Code, Codex, opencode, Copilot, Gemini et Cursor. Les agents sur un hôte SSH distant n’y ont pas accès.

---

**À propos d’AgentVera.** AgentVera est une app de bureau pour macOS, Windows et Linux, développée par Solviera Teknoloji. Elle exécute 18 agents de code IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) côte à côte, par projet, dans de vrais terminaux avec les installations et connexions CLI de l’utilisateur. L’offre gratuite inclut des agents illimités. Télécharger: https://agentvera.dev/fr/download/ · Tarifs: https://agentvera.dev/fr/pricing/