Skip to Content
Claude CodePartie 6 — Reprendre & continuer un projet existant6.4 — Les gros codebases

Chapitre 6.4 — Les gros codebases

⏱️ TL;DR — Sur un gros repo, « tout charger » est impossible et inutile. La stratégie : naviguer par la recherche (l’agent grep/glob au lieu de lire en masse), déléguer l’exploration à des subagents (contexte isolé, en parallèle), donner à l’agent des outils de navigation de code (LSP : aller-à-la-définition, trouver-les-références) et localiser les conventions avec des CLAUDE.md de sous-système. On travaille une zone à la fois, le contexte reste net même à grande échelle.

🎯 Objectifs

  • Naviguer un gros codebase par la recherche, pas la lecture brute.
  • Déléguer l’exploration à des subagents pour préserver le contexte.
  • Tirer parti des LSP (navigation de code précise).
  • Structurer conventions et travail par zone.

Le contexte ne scale pas, la recherche si

Un gros codebase dépasse de loin la fenêtre de contexte (1.3). La bonne nouvelle : l’agent n’a pas besoin de tout voir, il a besoin de trouver. Ses outils de recherche (grep, glob) lui permettent de localiser précisément « où est défini X », « qui appelle Y », « où sont les routes » — sans charger le repo entier. Sur du gros, tu pilotes vers la recherche ciblée, pas vers la lecture massive.

« Ne lis pas tout : cherche où PaymentService est défini et utilisé, ouvre uniquement ces fichiers, et dis-moi le flux. »

Déléguer l’exploration aux subagents

C’est ici que les subagents (Partie 8) brillent le plus. Une exploration coûteuse (« comprends comment le module de facturation interagit avec les commandes ») peut être confiée à un subagent (Explore) qui :

  • travaille dans son propre contexte (n’encombre pas le tien) ;
  • balaie largement et te renvoie une conclusion ;
  • peut tourner en parallèle d’autres explorations.

Tu obtiens une carte multi-zones sans avoir chargé le code de chaque zone dans ta session. C’est le contexte propre (5.2) appliqué à l’échelle.

💡 Réflexe d’architecte — Sur un gros repo, pense « délègue l’exploration, garde la décision ». Les subagents ramènent la matière brute digérée ; toi (et l’agent principal) gardes le contexte clair pour décider et agir. Empiler l’exploration dans ta session principale, c’est la saturer avant même de coder.

Les LSP : la navigation de code précise

Grep trouve du texte ; un serveur LSP (Language Server Protocol) comprend le code. Des plugins officiels ajoutent à Claude Code des capacités LSP par langage (typescript-lsp, pyright-lsp, rust-analyzer-lsp, gopls-lsp…) : aller à la définition, trouver toutes les références, diagnostics de types après une édition. Sur un gros codebase typé, c’est décisif :

  • « trouve toutes les références de createOrder » devient exact (pas approximatif au grep) ;
  • après une modif, l’agent voit immédiatement les erreurs de types propagées.

Ces plugins s’installent depuis la marketplace officielle (Partie 10) et requièrent le serveur de langage correspondant. Sur un projet sérieux, ils transforment la navigation de « je cherche du texte » à « je comprends le graphe du code ».

📚 Aller plus loin — Anthropic a publié des recommandations spécifiques au travail sur gros codebases (par où commencer, comment cadrer). L’idée-force recoupe ce chapitre : localise, délègue l’exploration, agis par zone — ne tente jamais d’« avaler » le repo.

Structurer par zone

Deux gestes rendent un gros repo « pilotable » :

  1. Des CLAUDE.md de sous-système (3.1) : chaque grande zone (facturation, auth…) a son contrat local, chargé quand l’agent y travaille. Les conventions sont localisées, pas noyées dans un CLAUDE.md racine géant.
  2. Travailler une zone à la fois : une intention par session (5.2), ancrée dans une zone. Tu ne demandes pas « touche à tout le monde » ; tu cadres « dans le module facturation, fais X ».

⚠️ Piège — Un CLAUDE.md racine qui tente de décrire tout le gros repo : il devient obèse (3.2), pèse sur chaque tâche, et personne ne le maintient. Sur du gros, distribue les conventions par zone (CLAUDE.md de dossier) et garde la racine minimale (les règles vraiment transverses).

🧭 Sur TaskFlow — TaskFlow est petit, mais la méthode se projette : à mesure qu’il grossirait (facturation, équipes, API publique), chaque domaine gagnerait son CLAUDE.md de dossier, on déléguerait l’exploration inter-domaines à des subagents, et on installerait typescript-lsp pour une navigation exacte. Les principes du petit projet scalent au gros.

✏️ Exercices

Exercice 1 — Recherche, pas lecture. Sur un gros repo, pose une question de navigation (« qui utilise X ? ») en interdisant la lecture massive. Observe : l’agent grep/glob-t-il et n’ouvre-t-il que le pertinent ?

✅ Solution

Bien piloté, l’agent localise par recherche et n’ouvre que les fichiers utiles — contexte préservé. S’il se met à lire des dossiers entiers, recadre (« cherche, n’ouvre que le pertinent »). Avec un LSP installé, « toutes les références » devient exact plutôt qu’approximatif.

Exercice 2 — Délègue une exploration. Confie à un subagent Explore la compréhension d’une interaction entre deux modules. Compare la propreté de ta session principale avec un scénario où tu aurais tout lu toi-même.

✅ Solution

Le subagent ramène la conclusion (flux, fichiers clés) sans charger le code des deux modules dans ta session. Ta session principale reste disponible pour décider et coder. À l’échelle, c’est la différence entre un contexte net et un contexte saturé avant d’avoir commencé.

🧠 Quiz de révision

1. Pourquoi « tout charger » échoue-t-il sur un gros repo ?

Parce que le repo dépasse la fenêtre de contexte, et l’entasser la sature. L’agent n’a pas besoin de tout voir, mais de trouver — d’où la navigation par recherche (grep/glob) ciblée.

2. Pourquoi déléguer l’exploration à des subagents ?

Parce qu’ils travaillent dans un contexte isolé, balaient largement, renvoient une conclusion, et peuvent tourner en parallèle — sans encombrer la session principale. On délègue l’exploration, on garde la décision.

3. Qu’apportent les plugins LSP sur un gros codebase ?

Une navigation de code (pas juste de texte) : aller-à-la-définition, toutes les références exactes, diagnostics de types après édition. Décisif sur un projet typé de grande taille.

4. Comment localiser les conventions sur un gros repo ?

Avec des CLAUDE.md de sous-système (chargés quand l’agent travaille dans la zone), plutôt qu’un CLAUDE.md racine géant. On distribue les conventions par zone et on garde la racine minimale.

5. Quelle discipline de travail à grande échelle ?

Une zone à la fois, une intention par session, ancrée dans un domaine. On ne demande pas « touche à tout » ; on cadre « dans le module X, fais Y ».

Chapitre suivant : Atelier — reprendre un projet — mettre bout à bout onboarding, conventions et première modif sûre.

6.3 — Continuité entre sessions & personnes6.5 — Atelier : reprendre un projet