Claude Code dans les monorepos peut perdre en précision quand le dépôt est immense. Apprenez à définir des limites, des résumés locaux et des workflows répétables pour garder les réponses précises.
Claude Code dans les monorepos peut sembler imprévisible pour une raison simple : le dépôt est plus grand que ce que le modèle peut garder en mémoire de travail en une fois.
Le « contexte » est l'ensemble des fichiers, extraits, notes et instructions que Claude a vus pour cette tâche, plus ce qu'il peut en déduire. Quand des détails clés manquent, Claude comble les vides par des suppositions. Dans un grand repo, cela arrive plus souvent.
Trois modes d'échec reviennent régulièrement :
D'abord, des fichiers manqués. Un changement qui semble sûr dans un dossier dépend en réalité d'un type partagé, d'une règle de config ou d'une étape de build définie ailleurs. Si cette dépendance n'est pas dans le contexte, Claude peut modifier la mauvaise chose en toute confiance ou s'arrêter tôt parce qu'il ne voit pas la vraie source de vérité.
Ensuite, la fausse similarité. Les monorepos contiennent souvent plusieurs packages qui se ressemblent : deux modules d'auth, trois clients API, ou plusieurs apps React avec des structures de dossiers similaires. Claude peut mélanger les patterns entre eux, mettre à jour un helper dans le mauvais package, ou importer depuis un nom de module « presque correct ».
Enfin, la dérive temporelle. Les grosses bases de code ont généralement des façons anciennes et nouvelles de faire la même chose. Si Claude ne voit que des fichiers plus anciens, il peut recopier des patterns dépassés (options de config dépréciées, API legacy) alors que l'équipe a évolué.
Un exemple concret : vous demandez une petite modification de l'interface de facturation, et Claude modifie un composant payments partagé utilisé par d'autres apps parce qu'il n'a jamais vu le wrapper spécifique à l'app qui aurait dû être changé.
L'objectif n'est pas de montrer à Claude l'intégralité du monorepo. L'objectif est de fournir de petites entrées délibérées qui répondent à la question : le package que vous modifiez, ses dépendances directes, et une ou deux « sources de vérité » pour les types et la config. Indiquez aussi les zones « ne pas toucher » (autres apps, infra, code généré) et confirmez quel package possède le comportement.
La précision dépend moins de la quantité de code collée que de la clarté de la description du travail.
Commencez par le résultat voulu : une correction précise, un refactor, ou une réponse. Une « question sur le code » peut rester de haut niveau. Une demande « faire un changement » exige des limites, des entrées et des critères de réussite.
Avant de partager quoi que ce soit, écrivez une phrase qui termine cette expression : « Une fois fini·e, je devrais pouvoir… ». Par exemple : « lancer les tests unitaires du package X sans échecs » ou « voir le nouveau champ sur la réponse de l'API pour l'endpoint Y. » Cette phrase devient l'étoile polaire quand le repo est énorme.
Pour des modifications, partagez le plus petit ensemble d'artefacts qui peuvent prouver que le changement est correct : le(s) point(s) d'entrée, les types/interfaces ou schéma pertinents, un test qui échoue ou une étape de repro avec le résultat attendu, et toute config qui affecte ce chemin (routing, feature flags, build ou règles de lint). Si utile, ajoutez une courte carte des dossiers du package pour que Claude comprenne le rôle de chaque répertoire.
Soyez explicite sur ce qu'il ne faut pas regarder. Dites : « Ignorer les fichiers générés, les dossiers vendor, les sorties de build, les snapshots et les lockfiles sauf si je le demande. » Cela évite du temps perdu et des modifications là où vous ne ferez pas de revue.
Fixez aussi des attentes concernant l'incertitude. Demandez à Claude de signaler les hypothèses et les inconnues au lieu de deviner. Par exemple : « Si vous ne voyez pas où cette fonction est appelée, dites-le et proposez 2 façons de la localiser. »
Dans un grand monorepo, la précision baisse quand le modèle commence à « aider » en puisant du code voisin qui ne fait pas partie de la tâche. La solution est simple : définissez ce qui est dans le périmètre et ce qui est hors périmètre avant de demander des modifications.
Commencez par une frontière qui correspond à l'organisation du repo : un package, un service, une app, ou une librairie partagée. Si le changement est « mettre à jour l'UI de checkout », la frontière est probablement le package d'une app, pas tous les endroits où le mot « checkout » apparaît.
Les signaux qui aident Claude à rester à sa place incluent les conventions de dossiers (apps/, services/, packages/, libs/), les manifests de package (exports et dépendances), les points d'entrée publics (fichiers index, composants exportés, handlers), et les tests (ils révèlent souvent la surface prévue). Un README dans le dossier peut être le marqueur de frontière le plus rapide.
Les frontières fonctionnent mieux quand vous nommez les ponts entre elles. Indiquez les interfaces spécifiques que Claude peut toucher et traitez tout le reste comme hors limites. Les ponts typiques sont les contrats HTTP API, les topics d'événements et leurs payloads, les types partagés, ou un petit ensemble de fonctions exportées.
Nommez aussi les zones « ne pas toucher » quand le changement ne doit pas les affecter. Les plus courantes sont : la configuration d'infrastructure et de déploiement, la logique de sécurité et d'auth, la facturation et les paiements, les migrations de données et les schémas de production, et les bibliothèques partagées utilisées par plusieurs équipes.
Un détail de prompt concret qui aide :
"Make changes only inside packages/cart/ and its tests. You may read shared types in packages/types/ but do not modify them. Do not edit infra, auth, or billing."
La précision s'améliore quand vous fournissez une petite carte stable de la zone à modifier. Un « local summary » est cette carte : assez court pour être lu vite, assez précis pour éviter les suppositions.
Gardez chaque résumé autour de 10 à 20 lignes. Écrivez-le comme si vous remettiez le code à un·e nouveau·elle coéquipier·e qui n'a besoin de toucher que cette frontière, pas tout le repo. Utilisez un langage clair et des noms réels du code : dossiers, packages, fonctions exportées.
Un résumé local utile répond à cinq questions :
Ajoutez une ligne « gotchas ». C'est là que vous empêchez les erreurs coûteuses : cache caché, feature flags, étapes de migration, et tout ce qui casse silencieusement.
Voici un modèle compact que vous pouvez copier :
Local summary: \u003cpackage/service name\u003e
Purpose: \u003c1 sentence\u003e
Scope: \u003cwhat to touch\u003e | Not: \u003cwhat not to change\u003e
Entry points: \u003cfiles/routes/commands\u003e
Public surface: \u003cexports/endpoints/events\u003e
Data sources: \u003ctables/collections/queues/caches\u003e
Conventions: errors=\u003chow\u003e, logging=\u003chow\u003e, tests=\u003cwhere/how\u003e
Gotchas: \u003cflags/caching/migrations/edge cases\u003e
Exemple : si vous éditez un package de facturation, notez la fonction exacte qui crée les factures, les noms de table qu'elle écrit, et la règle pour les erreurs retryables. Ainsi Claude peut se concentrer sur cette frontière au lieu d'errer vers l'auth partagée, la config, ou d'autres packages non pertinents.
Le meilleur résumé est celui que Claude voit quand il en a besoin. Placez-le à côté du code qu'il décrit pour qu'il soit difficile à ignorer et facile à mettre à jour. Par exemple, gardez un court SUMMARY.md (ou une section dans README.md) à l'intérieur de chaque package, service ou dossier d'app plutôt qu'un énorme document à la racine du repo.
Une structure simple et répétable aide. Gardez-le assez court pour que les gens le maintiennent :
YYYY-MM-DD - \u003cwhat changed in one sentence\u003eLes résumés deviennent obsolètes pour des raisons prévisibles. Traitez les mises à jour comme la mise à jour d'une définition de type : partie intégrante de la finalisation du travail, pas une tâche séparée.
Mettez à jour le résumé quand un refactor change la structure ou les noms, quand un nouveau module devient le moyen principal de faire quelque chose, quand une API/event/schema change (même si les tests passent encore), quand les frontières entre packages bougent, ou quand une dépendance est supprimée ou remplacée.
Une habitude pratique : quand vous fusionnez un changement, ajoutez une ligne “Last updated” indiquant ce qui a été modifié. Des outils comme Koder.ai peuvent vous aider à aller plus vite sur le changement de code, mais le résumé est ce qui maintient les futurs changements précis.
La précision dépend souvent de la façon dont vous cadencez la conversation. Faites gagner le contexte à Claude en petites portions plutôt que de le laisser deviner à partir d'un énorme snapshot.
Avant toute modification, demandez à Claude de décrire ce qu'il voit et ce dont il a besoin. Une bonne carte est courte : packages impliqués, point d'entrée du flux, et où se trouvent les tests ou les types.
Prompt :
"Create a map of this change: packages involved, main flow, and likely touch points. Do not propose code yet."
Choisissez une tranche étroite : une fonctionnalité, un package, un flux utilisateur. Indiquez la frontière clairement (par exemple : « Modifier uniquement packages/billing-api. Ne touchez pas shared-ui ou infra. »).
Un workflow qui vous garde en contrôle :
Si quelque chose manque, Claude doit le dire. Demandez-lui d'écrire : (1) les hypothèses qu'il fait, (2) ce qui les invaliderait, et (3) les fichiers suivants nécessaires pour confirmer.
Exemple : vous devez ajouter un champ à une réponse Invoice dans un package. Claude demande le handler, la définition DTO/type, et un test. Vous partagez seulement ceux-ci. Si vous utilisez un builder chat comme Koder.ai, la même règle s'applique : fournissez le plus petit ensemble de fichiers source, puis étendez seulement si nécessaire.
Votre meilleure défense contre les mauvaises modifications est un petit « contrat » intégré au prompt : ce que Claude peut toucher, comment vous jugerez le succès, et quelles règles il doit suivre.
Commencez par une frontière facile à respecter et à vérifier. Soyez explicite sur où les modifications sont autorisées, et nommez les zones « ne pas toucher » pour qu'il n'y ait pas de tentation d'errance.
Modèle de contrat :
packages/payments/.packages/auth/, infra/, ou les configs partagées.Puis définissez les vérifications d'acceptation. Sans elles, Claude peut produire du code qui a l'air correct mais qui viole les règles réelles du repo.
Les contraintes de style comptent aussi. Indiquez à Claude quels patterns suivre et lesquels éviter, basés sur ce que votre codebase fait déjà. Par exemple : « Utilisez les helpers d'erreur existants dans ce package ; n'ajoutez pas de nouvelles dépendances ; gardez les noms de fonctions en camelCase ; n'introduisez pas une nouvelle couche d'architecture. »
Enfin, exigez un court plan de changement avant toute édition :
"Avant d'éditer, listez les 3–5 fichiers que vous pensez toucher et le changement de comportement exact. Attendez ma validation."
Exemple :
"Corriger l'arrondi dans les totaux de factures. Modifier uniquement packages/billing/src/ et les tests sous packages/billing/test/. Acceptation : pnpm -C packages/billing test et typecheck. Suivez les utilitaires money existants ; ne réécrivez pas les types API. Fournissez un plan en 4 étapes d'abord."
La façon la plus rapide d'obtenir de mauvaises modifications dans un monorepo est de donner trop à la fois. Quand vous collez une grosse masse de code, il a tendance à retomber sur des patterns génériques plutôt que sur le design spécifique de votre repo.
Un autre piège est de le laisser deviner l'architecture. Si vous ne montrez pas les vrais points d'entrée, il peut choisir le premier fichier plausible et y brancher la logique. En pratique, la précision vient d'un petit ensemble de fichiers « source of truth » (modules d'entrée, routers, registries de services, docs de frontières de package). Si ceux-ci ne sont pas en contexte, le modèle comble les vides.
Les noms peuvent aussi tromper. Les monorepos ont souvent des packages comme ui, ui-kit, shared-ui, ou des helpers dupliqués comme date.ts à plusieurs endroits. Si vous mélangez des extraits des deux, Claude peut patcher un fichier en se basant sur un autre. Exemple : vous demandez de changer un style de bouton, il modifie packages/ui/Button.tsx, mais l'app importe packages/ui-kit/Button.tsx. Le diff semble correct, mais rien ne change en production.
La config est une autre source de dérive silencieuse. Le comportement peut dépendre de vars d'environnement, feature flags, paramètres de build, ou tooling workspace. Si vous n'en parlez pas, Claude peut enlever un check « étrange » qui n'est utile que quand un flag est activé, ou ajouter du code qui casse une étape de build.
Signes que vous dérivez :
Considérez les imports cross-package comme une décision, pas une valeur par défaut. Gardez les modifications locales sauf si vous élargissez intentionnellement le périmètre.
La façon la plus rapide d'obtenir des modifications correctes est de commencer par des limites, pas par le volume. Un bon prompt est un peu strict : il indique où regarder, quoi ignorer, et ce que « fini » signifie.
Avant de coller du code, rédigez un court préambule qui ancre le travail dans un endroit précis du repo. Nommez le package, le chemin exact, et l'objectif spécifique. Puis incluez un local summary (but, dépendances clés, conventions importantes) et le fichier d'entrée qui ancre le changement.
Checklist :
\u003cpackage\u003e/\u003cpath\u003e. Objectif : \u003cone sentence\u003e. Ignorer tout le reste sauf si demandé.\u003c5-10 lines\u003e. Fichier d'entrée : \u003cpath/to/file\u003e.\u003c...\u003e. Ne pas changer : \u003cfolders/files or APIs\u003e. Conserver le comportement : \u003cwhat must stay true\u003e.Si Claude propose des changements hors de votre frontière, considérez cela comme un signal : resserrez le prompt, ou élargissez la frontière volontairement et redéfinissez-la clairement.
Supposons que votre monorepo ait apps/web-store (une app React) et packages/ui-kit (boutons partagés, inputs, styles). Vous voulez une petite fonctionnalité : ajouter un bouton « Save for later » sur la page panier, en utilisant une nouvelle SaveIcon de ui-kit. Rien d'autre ne doit changer.
Avant de demander des modifications, créez deux local summaries qui servent de frontières. Gardez-les courts, précis, et opinatifs sur ce qui compte.
# apps/web-store/LOCAL_SUMMARY.md
Purpose: Customer shopping UI.
Entry points: src/routes.tsx, src/pages/cart/CartPage.tsx
Cart rules: cart state lives in src/cart/useCart.ts
Do not touch: checkout flow (src/pages/checkout), payments, auth.
Tests: npm test -w apps/web-store
# packages/ui-kit/LOCAL_SUMMARY.md
Purpose: shared UI components.
Exports: src/index.ts
Icons: src/icons/*, add new icons by exporting from index.
Do not touch: theming tokens, build config.
Tests: npm test -w packages/ui-kit
Ensuite, gardez la boucle serrée :
CartPage et aux icônes ui-kit. Pas d'édition du checkout/auth. »CartPage, useCart, icônes ui-kit, index ui-kit).Après la modification, documentez-la pour que le contexte futur reste petit :
Si cela fonctionne bien pour une personne mais pas pour le reste de l'équipe, la pièce manquante est généralement la répétabilité. Faites de la « bonne hygiène de contexte » la valeur par défaut, pas une habitude personnelle.
Sauvegardez un squelette de prompt que tout le monde peut copier et remplir. Gardez-le court, mais strict. Incluez l'objectif (ce que « fini » signifie), le périmètre autorisé, les frontières strictes (et pourquoi), un local summary, et un contrat de sortie (plan d'abord, puis diffs et tests).
Évitez les grosses revues mensuelles que personne ne fait. Attachez les mises à jour de résumé au travail normal : quand un changement modifie le comportement, les dépendances, ou les API, mettez à jour le local summary dans la même PR.
Une règle simple : si un·e coéquipier·e devrait demander « où ça vit ? » ou « qui dépend de ça ? », alors le résumé est obsolète.
Si vous préférez un workflow centré sur le chat, Koder.ai peut vous aider à sécuriser ce style d'itération. Le mode planning vous aide à vous mettre d'accord sur le périmètre et les frontières avant d'éditer, et les snapshots avec rollback vous permettent d'essayer des changements sans rester bloqué·e quand une supposition s'avère fausse.
Claude devient moins précis quand il ne peut pas « voir » la vraie source de vérité.
Dans un grand monorepo, le modèle manque souvent un fichier de dépendance, confond deux paquets similaires, ou reproduit un ancien schéma parce que ce sont les fichiers vus en contexte.
N'essayez pas d'inclure tout le dépôt. Commencez par le plus petit ensemble d'éléments qui prouve que la modification est correcte.
Un bon point de départ :
Partagez ce qui ancre le comportement, pas tout ce qui porte un nom similaire.
Un ensemble pratique :
Choisissez une frontière qui correspond à l'organisation du dépôt : un package, une app, ou un service.
Ensuite, énoncez-la explicitement, en indiquant ce qui est hors-scope. Exemples de contraintes :
packages/cart/ et ses tests. »Parce que les monorepos contiennent souvent des modules qui se ressemblent (ui, ui-kit, shared-ui) et des utilitaires dupliqués (date.ts à plusieurs endroits).
Claude peut appliquer la bonne idée au mauvais package, ou importer depuis un nom de module « presque correct ». Prévenez cela en nommant le package exact et les points d'entrée que vous voulez.
Un « local summary » est une courte carte de la zone exacte que vous voulez modifier, généralement 10–20 lignes.
Incluez :
Placez-le à côté du code qu'il décrit pour qu'il soit facile à trouver et à mettre à jour.
Un défaut simple :
SUMMARY.md ou une petite section dans le README.md du packageDites à Claude dès le départ de signaler les hypothèses et les inconnues au lieu de deviner.
Une règle utile :
Utilisez une boucle courte qui oblige à gagner du contexte par petites étapes :
Écrivez un mini « contrat » dans votre prompt et rendez-le vérifiable :
Cela facilite la revue et réduit les modifications accidentelles entre packages.