Comment fonctionne Claude Code dans les grandes bases de code, par Anthropic
Comment fonctionne Claude Code dans les grandes bases de code : par où commencer et bonnes pratiques pour les équipes d'ingénierie qui développent avec Claude Code à l'échelle de l'entreprise
Les déploiements de Claude Code les plus réussis partagent un ensemble de modèles reconnaissables en matière de configurations, d'outils et de structure organisationnelle. Cet article fait partie de « Claude Code à grande échelle », une nouvelle série consacrée aux meilleures pratiques pour les équipes d'ingénierie qui développent avec Claude Code à l'échelle de l'entreprise.
Claude Code est utilisé en production dans des monorepos de plusieurs millions de lignes, des systèmes hérités vieux de plusieurs décennies, des architectures distribuées couvrant des dizaines de dépôts, ainsi que dans des organisations comptant des milliers de développeurs. Ces environnements présentent des défis que les bases de code plus petites et plus simples ne posent pas, qu'il s'agisse de commandes de compilation différentes dans chaque sous-répertoire ou de code hérité réparti dans des dossiers sans racine commune.
Cet article présente les modèles que nous avons observés et qui ont conduit à l'adoption réussie de Claude Code à grande échelle. Nous utilisons le terme « base de code volumineuse » pour désigner un large éventail de déploiements : des monorepos de plusieurs millions de lignes, des systèmes hérités construits sur des décennies, des dizaines de microservices répartis dans des dépôts distincts, ou toute combinaison de ces éléments. Cela inclut également les bases de code fonctionnant sur des langages que les équipes n’associent pas toujours aux outils de codage IA, tels que C, C++, C#, Java, PHP. (Claude Code offre de meilleures performances que ce à quoi la plupart des équipes s’attendent dans ces cas-là, en particulier depuis les dernières versions du modèle.) Si chaque déploiement de base de code volumineuse est façonné par son contrôle de version spécifique, la structure de son équipe et les conventions accumulées, les modèles présentés ici s’appliquent de manière générale à toutes ces situations et constituent un bon point de départ pour les équipes qui envisagent d’adopter Claude Code.
Comment Claude Code explore les grandes bases de code
Claude Code explore une base de code comme le ferait un ingénieur logiciel : il parcourt le système de fichiers, lit les fichiers, utilise grep pour trouver exactement ce dont il a besoin et suit les références à travers la base de code. Il fonctionne localement sur la machine du développeur et ne nécessite pas la création, la maintenance ou le téléchargement d’un index de la base de code sur un serveur.
Les outils de codage IA basés sur RAG fonctionnent en intégrant l’intégralité de la base de code et en récupérant les segments pertinents au moment de la requête. À grande échelle, ces systèmes peuvent échouer car les pipelines d’intégration ne parviennent pas à suivre le rythme des équipes d’ingénieurs en activité. Au moment où un développeur interroge l’index, celui-ci reflète l’état de la base de code tel qu’il existait des semaines, des jours, voire des heures auparavant. La recherche renvoie alors une fonction que l’équipe a renommée il y a deux semaines, ou fait référence à un module supprimé lors du dernier sprint, sans aucune indication que l’un ou l’autre est obsolète.
La recherche agentique évite ces modes de défaillance. Il n'y a pas de pipeline d'intégration ni d'index centralisé à maintenir alors que des milliers d'ingénieurs valident du nouveau code. L'instance de chaque développeur fonctionne à partir de la base de code en direct.
Mais cette approche présente un compromis : elle fonctionne mieux lorsque Claude dispose d'un contexte de départ suffisant pour savoir où chercher. Cela signifie que la qualité de la navigation de Claude dépend de la qualité de la configuration de la base de code, qui superpose le contexte à l'aide de fichiers CLAUDE.md et de compétences. Si vous lui demandez de trouver toutes les occurrences d’un motif vague dans une base de code d’un milliard de lignes, vous atteindrez les limites de la fenêtre de contexte avant même que le travail ne commence. Les équipes qui investissent dans la configuration de la base de code obtiennent de meilleurs résultats.
Le harnais est aussi important que le modèle
L’une des idées fausses les plus courantes concernant Claude Code est que ses capacités sont uniquement définies par le modèle utilisé. Les équipes se concentrent sur les benchmarks d’un modèle et sur ses performances lors des tâches de test. En pratique, c’est l’écosystème construit autour du modèle — le harnais — qui détermine les performances de Claude Code plus que le modèle seul.
Le harnais est constitué de cinq points d’extension — les fichiers CLAUDE.md, les hooks, les compétences, les plugins et les serveurs MCP — chacun remplissant une fonction différente. L’ordre dans lequel les équipes les construisent est important, car chaque couche s’appuie sur ce qui l’a précédée. Deux capacités supplémentaires, les intégrations LSP et les sous-agents, complètent la configuration. Ci-dessous, nous expliquons le rôle de chacun de ces composants et capacités :
Les fichiers CLAUDE.md sont prioritaires. Il s'agit de fichiers de contexte que Claude lit automatiquement au début de chaque session : un fichier racine pour la vue d'ensemble, et des fichiers dans des sous-répertoires pour les conventions locales. Ils fournissent à Claude les connaissances sur la base de code dont il a besoin pour bien accomplir toutes ses tâches. Comme ils se chargent à chaque session, quelle que soit la tâche, le fait de les axer sur ce qui s'applique de manière générale évitera qu'ils ne deviennent un frein aux performances.
Les hooks permettent à la configuration de s'améliorer d'elle-même. La plupart des équipes considèrent les hooks comme des scripts qui empêchent Claude de commettre des erreurs, mais leur utilité la plus précieuse réside dans l'amélioration continue. Un hook d'arrêt peut analyser ce qui s'est passé pendant une session et proposer des mises à jour de CLAUDE.md tant que le contexte est encore frais. Un hook de démarrage peut charger dynamiquement le contexte spécifique à l'équipe afin que chaque développeur dispose de la configuration adaptée à son module sans configuration manuelle. Pour les vérifications automatisées telles que le linting et le formatage, les hooks appliquent les règles de manière déterministe et produisent des résultats plus cohérents que si l'on comptait sur Claude pour se souvenir d'une instruction.
Les compétences permettent de disposer de l'expertise adéquate à la demande sans alourdir chaque session. Dans une base de code volumineuse comportant des dizaines de types de tâches, toutes les compétences ne doivent pas nécessairement être présentes à chaque session. Les compétences résolvent ce problème grâce à une divulgation progressive, en déchargeant les workflows spécialisés et les connaissances métier qui, autrement, se disputeraient l'espace de contexte, et en ne les chargeant que lorsque la tâche l'exige. Par exemple, une compétence de révision de sécurité se charge lorsque Claude évalue le code à la recherche de vulnérabilités, tandis qu’une compétence de traitement de documentation se charge lorsqu’une modification du code est effectuée et que la documentation doit être mise à jour.
Les compétences peuvent également être limitées à des chemins spécifiques afin qu’elles ne s’activent que dans la partie pertinente de la base de code. Une équipe responsable d’un service de paiement peut lier sa compétence de déploiement à ce répertoire, de sorte qu’elle ne se charge jamais automatiquement lorsque quelqu’un travaille ailleurs dans le monorepo.
Les plugins diffusent ce qui fonctionne. L’un des défis liés aux bases de code volumineuses est que les bonnes configurations peuvent rester cloisonnées. Un plugin regroupe des compétences, des hooks et des configurations MCP dans un seul paquet installable ; ainsi, lorsqu’un nouvel ingénieur installe ce plugin dès son premier jour, il dispose immédiatement du même contexte et des mêmes capacités que ceux qui utilisent déjà Claude. Les mises à jour des plugins peuvent être diffusées à l’ensemble de l’organisation via des marketplaces gérées.
Par exemple, une grande entreprise de vente au détail avec laquelle nous travaillons a développé une compétence reliant Claude à sa plateforme d’analyse interne afin que les analystes métier puissent extraire des données de performance sans quitter leur flux de travail. Elle l’a distribuée sous forme de plugin avant son déploiement à grande échelle dans l’entreprise.
Les intégrations du protocole de serveur de langage (LSP) offrent à Claude la même navigation dont dispose un développeur dans son EDI. La plupart des EDI gérant des bases de code volumineuses disposent déjà d’un LSP, qui permet d’utiliser les fonctions « aller à la définition » et « rechercher toutes les références ». En intégrant cela à Claude, on lui confère une précision au niveau des symboles : il peut suivre un appel de fonction jusqu’à sa définition, tracer les références à travers les fichiers et distinguer les fonctions portant le même nom dans différents langages. Sans cela, Claude effectue une correspondance de motifs sur le texte et peut aboutir au mauvais symbole. Une entreprise de logiciels avec laquelle nous avons travaillé a déployé des intégrations LSP à l’échelle de l’organisation avant le déploiement de Claude Code, spécifiquement pour rendre la navigation en C et C++ fiable à grande échelle. Pour les bases de code multilingues, c’est l’un des investissements les plus rentables.
Les serveurs MCP étendent tout. Les serveurs MCP permettent à Claude de se connecter à des outils internes, des sources de données et des API auxquels il ne pourrait pas accéder autrement. Les équipes les plus avancées ont développé des serveurs MCP exposant la recherche structurée comme un outil que Claude peut appeler directement. D’autres connectent Claude à la documentation interne, aux systèmes de tickets ou aux plateformes d’analyse.
Les sous-agents séparent l’exploration de l’édition. Un sous-agent est une instance isolée de Claude dotée de sa propre fenêtre de contexte qui prend en charge une tâche, effectue le travail et renvoie uniquement le résultat final au parent. Une fois le harnais en place, certaines équipes lancent un sous-agent en lecture seule pour cartographier un sous-système et consigner les résultats dans un fichier, puis demandent à l'agent principal d'effectuer l'édition en disposant d'une vue d'ensemble.
Aperçu de la couche d'extension de Claude Code.
Le tableau ci-dessous résume le rôle de chaque composant, le moment où il se charge et les erreurs les plus courantes que nous observons pour chacun d'entre eux :
Trois modèles de configuration issus de déploiements réussis
La manière dont vous configurez Claude Code pour une base de code volumineuse dépend fortement de la structure de cette base. Néanmoins, trois modèles sont revenus systématiquement dans les déploiements que nous avons observés.
Rendre la base de code navigable à grande échelle
La capacité de Claude à aider dans une grande base de code est limitée par sa capacité à trouver le bon contexte. Trop de contexte chargé à chaque session dégrade les performances, tandis que trop peu de contexte laisse Claude naviguer à l'aveuglette. Les déploiements les plus efficaces investissent dès le départ pour rendre la base de code lisible par Claude. Quelques modèles reviennent systématiquement :
- Garder les fichiers CLAUDE.md légers et structurés en couches. Claude les charge de manière additive à mesure qu’il parcourt la base de code : le fichier racine pour la vue d’ensemble, les fichiers des sous-répertoires pour les conventions locales. Le fichier racine ne doit contenir que des pointeurs et des pièges critiques ; tout le reste devient du bruit.
- Initialiser dans les sous-répertoires, et non à la racine du dépôt. Claude fonctionne mieux lorsqu’il est limité à la partie de la base de code qui est réellement pertinente pour la tâche. Dans les monorepos, cela peut sembler contre-intuitif car les outils supposent souvent un accès root, mais Claude remonte automatiquement l'arborescence des répertoires et charge tous les fichiers CLAUDE.md qu'il trouve en chemin, de sorte que le contexte au niveau racine n'est jamais perdu.
- Limiter les commandes de test et de lint à chaque sous-répertoire. Exécuter la suite complète lorsque Claude a modifié un seul service entraîne des délais d'expiration et gaspille du contexte sur des résultats non pertinents. Les fichiers CLAUDE.md au niveau des sous-répertoires doivent spécifier les commandes qui s’appliquent à cette partie du code. Cela fonctionne bien pour les bases de code orientées services où chaque répertoire possède ses propres commandes de test et de build. Dans les monorepos en langage compilé présentant des dépendances inter-répertoires profondes, la limitation par sous-répertoire est plus difficile à mettre en œuvre et peut nécessiter des configurations de build spécifiques au projet.
- Utilisation de fichiers . ignore pour exclure les fichiers générés, les artefacts de compilation et le code tiers. En commettant les règles permissions.deny dans .claude/settings.json, les exclusions sont gérées par le contrôle de version, ce qui permet à tous les développeurs de l'équipe de bénéficier de la même réduction du bruit sans avoir à la configurer eux-mêmes. Dans certaines bases de code, les fichiers générés font eux-mêmes l'objet d'un travail de développement. Les développeurs travaillant sur des générateurs de code peuvent remplacer les exclusions au niveau du projet dans leurs paramètres locaux sans affecter le reste de l'équipe.
- Créer des cartes de base de code lorsque la structure de répertoires ne suffit pas. Pour les organisations où le code n'est pas regroupé dans une structure de répertoires conventionnelle, un fichier Markdown léger à la racine du dépôt, répertoriant chaque dossier de niveau supérieur avec une description d'une ligne de son contenu, fournit à Claude une table des matières qu'il peut analyser avant d'ouvrir les fichiers. Pour les bases de code comportant des centaines de dossiers de niveau supérieur, cette approche fonctionne mieux par couches : le fichier racine décrit uniquement la structure de plus haut niveau, et les fichiers CLAUDE.md des sous-répertoires fournissent le niveau de détail suivant, se chargeant à la demande à mesure que Claude parcourt l'arborescence. Dans les cas plus simples, mentionner avec @ les fichiers ou répertoires spécifiques que Claude doit référencer peut faire l'affaire.
- Exécuter des serveurs LSP pour que Claude effectue ses recherches par symbole, et non par chaîne de caractères. Une recherche Grep sur un nom de fonction courant dans une base de code volumineuse renvoie des milliers de résultats, et Claude gaspille du contexte en ouvrant des fichiers pour déterminer lesquels sont pertinents. LSP ne renvoie que les références pointant vers le même symbole, de sorte que le filtrage s'effectue avant que Claude ne lise quoi que ce soit. La mise en place de cette fonctionnalité nécessite l'installation d'un plugin d'intelligence de code pour votre langage et du binaire du serveur de langage correspondant ; la documentation Claude Code couvre les plugins disponibles et le dépannage.
Une mise en garde : il existe des cas limites où même l'approche hiérarchique CLAUDE.md échoue, par exemple les bases de code comportant des centaines de milliers de dossiers et des millions de fichiers, ou les systèmes hérités utilisant un contrôle de version autre que Git. Nous aborderons ces défis dans les prochains articles de cette série.
Maintenir activement les fichiers CLAUDE.md à mesure que l'intelligence du modèle évolue
À mesure que les modèles évoluent, les instructions écrites pour votre modèle actuel peuvent nuire à un futur modèle. Les fichiers CLAUDE.md qui guidaient Claude à travers des schémas avec lesquels il avait auparavant des difficultés peuvent devenir soit inutiles, soit une contrainte active lorsque le prochain modèle sera disponible. Par exemple, une règle CLAUDE.md qui demande à Claude de décomposer chaque refactorisation en modifications sur un seul fichier a peut-être aidé un modèle antérieur à rester sur la bonne voie, mais empêcherait un modèle plus récent d’effectuer des modifications coordonnées entre plusieurs fichiers, qu’il gère pourtant bien.
Les compétences et les hooks développés pour pallier les limites spécifiques d’un modèle, qu’il s’agisse du raisonnement du modèle ou des outils propres à Claude Code, deviennent superflus dès lors que ces limites disparaissent. Un hook qui interceptait les écritures de fichiers pour imposer l’utilisation de p4 edit dans une base de code Perforce, par exemple, est devenu inutile dès que Claude Code a intégré un mode Perforce natif.
Les équipes doivent prévoir de procéder à un examen approfondi de la configuration tous les trois à six mois, mais il est également utile d'en effectuer un dès que les performances semblent stagner après des mises à jour majeures du modèle.
Attribution de la responsabilité de la gestion et de l'adoption de Claude Code
La configuration technique à elle seule ne suffit pas à favoriser l'adoption. Les organisations qui ont réussi ont également investi dans la couche organisationnelle.
Les déploiements qui se sont généralisés le plus rapidement ont bénéficié d'un investissement dédié en infrastructure avant d'être largement accessibles. Une petite équipe, parfois même une seule personne, a mis en place les outils nécessaires pour que Claude s'intègre d'emblée aux workflows des développeurs dès leur première utilisation. Dans une entreprise, deux ingénieurs ont développé une suite de plugins et de MCP disponibles dès le premier jour. Dans une autre, une équipe entière dédiée à la gestion des outils de codage IA avait mis en place l'infrastructure avant même le début du déploiement. Dans les deux cas, la première expérience des développeurs s'est avérée productive plutôt que frustrante, et l'adoption s'est répandue à partir de là.
Les équipes qui s'occupent de ce travail aujourd'hui relèvent généralement du département « expérience développeur » ou « productivité développeur », qui est généralement chargé de l'intégration des nouveaux ingénieurs et de la mise en place des outils de développement. Un nouveau rôle fait son apparition dans plusieurs organisations : celui de responsable d’agent, une fonction hybride entre chef de projet et ingénieur dédiée à la gestion de l’écosystème Claude Code. Pour les organisations ne disposant pas d’une équipe dédiée, la version minimale viable est un DRI : une personne chargée de la configuration de Claude Code, ayant le pouvoir de prendre des décisions concernant les paramètres, la politique d’autorisations, la boutique de plugins et les conventions CLAUDE.md, et ayant la responsabilité de les maintenir à jour.
Une adoption ascendante suscite l’enthousiasme mais peut se fragmenter si personne ne centralise ce qui fonctionne. Il faut qu’une personne ou une équipe rassemble et promeuve les bonnes conventions Claude Code (telles qu’une hiérarchie CLAUDE.md standardisée ou un ensemble sélectionné de compétences et de plugins). Sans ce travail, les connaissances resteront cloisonnées et l’adoption stagnera.
Dans les grandes organisations, en particulier celles des secteurs réglementés, des questions de gouvernance se posent très tôt, telles que : qui contrôle les compétences et les plugins disponibles, comment empêcher des milliers d’ingénieurs de recréer indépendamment la même chose, comment s’assurer que le code généré par l’IA passe par le même processus de révision que le code généré par des humains ? Pour y répondre dès le début, nous suggérons de commencer par un ensemble défini de compétences approuvées, des processus de révision de code obligatoires et un accès initial limité, puis d’élargir ces possibilités à mesure que la confiance s’installe.
Nous avons observé que les déploiements les plus fluides ont lieu dans les organisations qui mettent en place très tôt des groupes de travail interfonctionnels en réunissant des représentants de l'ingénierie, de la sécurité de l'information et de la gouvernance afin de définir ensemble les exigences et d'élaborer une feuille de route de déploiement.
Appliquer ces modèles à votre organisation
Claude Code est conçu pour les environnements d'ingénierie logicielle classiques où les ingénieurs sont les principaux contributeurs au code, le dépôt utilise Git et le code suit des structures de répertoires standard. La plupart des bases de code volumineuses correspondent à ce modèle, mais les configurations non traditionnelles, telles que les moteurs de jeux comportant d'importants actifs binaires, les environnements avec un contrôle de version non conventionnel ou la contribution de non-ingénieurs au code, nécessitent un travail de configuration supplémentaire. Nos recommandations partent d'une configuration classique et les modèles que nous avons décrits ont fait leurs preuves chez bon nombre de nos clients. Toute complexité résiduelle nécessite un jugement spécifique à votre base de code, à vos outils et à votre organisation. C'est là que l'équipe Applied AI d'Anthropic travaille directement avec les équipes d'ingénierie pour traduire ces modèles en exigences spécifiques à votre organisation.
Remerciements : Nous tenons à remercier tout particulièrement Alon Krifcher, Charmaine Lee, Chris Concannon, Harsh Patel, Henrique Savelli, Jason Schwartz, Jonah Dueck et Kirby Kohlmorgen, de l'équipe Applied AI d'Anthropic, pour avoir partagé leur expérience du déploiement à grande échelle de Claude Code, ainsi qu'Amit Navindgi, de Zoox, pour ses commentaires sur cet article.
Source : How Claude Code works in large codebases : Best practices and where to start
Et vous ?
Pensez-vous que cette présentation est crédible ou pertinente ?
Voir aussi :
Répondre avec citation
Envoyé par Anthropic
Partager