Travailler dans un gros dépôt sans saturer le contexte

1Mesurer avant d'optimiser

Avant de changer quoi que ce soit, regarde ce qui remplit réellement le contexte. La commande /context affiche l'occupation courante sous forme de grille, avec la répartition par poste. /cost renvoie la consommation de la session.

La surprise est fréquente : ce n'est souvent pas le code lu qui pèse le plus. Les définitions d'outils des serveurs MCP branchés, un CLAUDE.md qui a grossi sans qu'on le relise, et le résultat d'une seule commande trop bavarde occupent régulièrement plus de place que les fichiers utiles.

2Écrire la carte une fois pour toutes

Un agent qui ne sait pas où vivent les choses les cherche, et chercher coûte du contexte. Une carte de vingt lignes économise cette exploration à chaque session.

Fais-la produire, puis relis-la et corrige-la : c'est le seul document du dépôt qui doit être exact.

Explore le depot et rends une carte de 30 lignes maximum :
- les dossiers de premier niveau, avec une phrase de role chacun ;
- les points d'entree de l'application ;
- ou vivent les tests, les migrations, la configuration ;
- les 5 fichiers les plus modifies ces six derniers mois ;
- les zones generees ou vendorisees, qu'on ne lit jamais.
Pas de description de code, seulement l'emplacement des choses.

Deux commandes aident à la produire sans tout ouvrir :

git ls-files | cut -d/ -f1 | sort | uniq -c | sort -rn | head -20
git log --since="6 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20

La deuxième est la plus utile : dans un gros dépôt, une petite fraction des fichiers concentre l'essentiel de l'activité. C'est là que se passent les tâches, et c'est ce que la carte doit pointer.

Cette carte a sa place dans CLAUDE.md, à condition qu'elle reste courte. Un CLAUDE.md long est chargé à chaque session, donc payé à chaque session.

3Chercher, puis lire une plage

La lecture de fichiers entiers est la principale source de gaspillage. Dans la plupart des cas, on cherche une définition ou un appel, pas un fichier.

Avant d'ouvrir un fichier, localise avec ripgrep.
Puis ne lis que la plage de lignes concernee, pas le fichier entier.
Si tu ne sais pas quoi chercher, dis-le et propose trois motifs de
recherche au lieu de parcourir l'arborescence.

Trois recherches qui remplacent beaucoup de lectures :

rg -l "createInvoice"
rg -n --type ts "export (function|const) createInvoice"
git log -S "createInvoice" --oneline

La troisième, souvent oubliée, retrouve les commits où le nombre d'occurrences d'une chaîne a changé. C'est le moyen le plus direct de savoir quand et pourquoi un comportement est apparu, sans lire l'historique du fichier.

4Déléguer la recherche

Le meilleur usage d'un sous-agent dans un gros dépôt n'est pas d'écrire du code, c'est d'absorber la lecture. Il ouvre quarante fichiers, remplit son propre contexte, et ne renvoie que la conclusion. Ton fil principal reçoit quinze lignes au lieu de quarante fichiers.

La qualité du résultat tient au format de retour, qui doit être imposé.

Lance un agent de recherche en lecture seule.
Question : ou est implemente le calcul de TVA, et par qui est-il appele ?
Il rend au maximum :
- une liste de chemins avec numeros de ligne ;
- 5 lignes de synthese ;
- ce qu'il n'a pas trouve.
Il ne recopie aucun extrait de code de plus de 5 lignes, et il ne
propose aucune modification.

Le plafond sur les extraits est ce qui fait la différence. Sans lui, un sous-agent renvoie des pages entières, et tu as juste déplacé le problème.

5Ce qu'on ne fait jamais lire

Certains fichiers n'apportent jamais rien et coûtent beaucoup. Ils se reconnaissent à une propriété commune : ils sont générés, donc leur contenu ne contient aucune décision humaine.

• les fichiers de verrouillage de dépendances, package-lock.json, pnpm-lock.yaml, poetry.lock, Cargo.lock ;
• les répertoires de dépendances et de build : node_modules, dist, build, .next, target, vendor ;
• les fichiers minifiés, transpilés, et les cartes de source ;
• les instantanés de tests et les jeux de données de test volumineux ;
• les migrations déjà appliquées, sauf celle qu'on regarde ;
• les binaires, images, PDF et archives ;
• les secrets et les fichiers d'environnement, pour une autre raison : ce n'est pas une question de coût.

Claude Code n'utilise pas de fichier d'exclusion dédié. Le blocage se déclare dans les permissions, où les règles de refus l'emportent sur les autorisations :

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./node_modules/**)",
      "Read(./dist/**)",
      "Read(./**/*.lock)"
    ]
  }
}

Une exception mérite d'être nommée : un fichier de verrouillage se consulte parfois, pour connaître la version résolue d'un paquet. La bonne façon est une recherche ciblée sur une clé, jamais une lecture.

6Tenir la session propre

Le contexte se dégrade avec le temps, pas seulement avec le volume. Une conversation qui a traité trois sujets contient deux sujets de bruit.

• /clear entre deux tâches sans rapport. C'est gratuit, et c'est le geste le plus rentable de la liste.
• /compact avec une consigne de focalisation quand la tâche est longue mais continue, pour orienter ce que le résumé conserve.
• --add-dir plutôt qu'un dépôt monolithique ouvert en entier, quand ton travail porte sur deux ou trois sous-projets seulement.