Claude Code dans les monorepos : limiter le contexte et rester précis

Pourquoi les grands monorepos rendent Claude moins précis

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.

Commencez par définir la tâche, pas le dépôt

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. »

Définissez des frontières claires que Claude ne doit pas franchir

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."

Comment rédiger des résumés locaux utiles

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 :

• À quoi sert ce package/service, et à quoi il ne sert pas (périmètre)
• Où le travail commence (points d'entrée principaux comme fichiers clés, routes, commandes, ou composants)
• Ce qui est sûr d'être appelé depuis l'extérieur (API publiques, modules exportés, events, endpoints)
• De quoi il dépend (bases de données, queues, caches, config, services externes)
• Quelles règles importent ici (conventions de nommage, style d'erreur, logging, et comment les tests sont écrits)

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.

Où placer les résumés et comment les maintenir à jour

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 :

• Ce qu'est ce dossier (but en 1–2 phrases)
• Surface publique (points d'entrée principaux, modules exportés, ou APIs)
• Dépendances clés (internes et externes)
• Frontières (ce qu'il ne doit pas importer ou modifier)
• Comment tester (le contrôle local le plus rapide)
• Last updated: YYYY-MM-DD - \u003cwhat changed in one sentence\u003e

Les 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.

Un workflow pas à pas pour rester dans le bon contexte

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.

Étape 1 : Demandez d'abord une carte rapide

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."

Étape 2 : Commencez par une tranche et une frontière

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 :

• Définissez l'objectif et la frontière en une phrase.
• Exigez les hypothèses et inconnues (Claude doit les lister).
• Demandez les fichiers exacts dont il a besoin ensuite (limitez à 3–6).
• Fournissez seulement ces fichiers, puis répétez.
• Exigez un petit plan avant tout patch.

Étape 3 : Forcez les hypothèses explicites et les demandes de fichiers

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.

Utilisez des contraintes et des contrats dans vos prompts

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 :

• Modifier seulement les fichiers sous packages/payments/.
• Ne pas éditer packages/auth/, infra/, ou les configs partagées.
• Si vous avez besoin de changements hors-scope, arrêtez et demandez d'abord.
• Gardez les changements au minimum : corrigez le bug, évitez les refactors.

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.

• Lancer les tests unitaires du package (indiquez la commande que vous utilisez).
• Lancer lint/format (indiquez l'outil, ou dites « utilisez la config existante »).
• Lancer le typecheck/build pour le package.
• Confirmer que l'app démarre toujours (une simple commande run suffit).

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."

Pièges courants qui causent dérive et mauvais changements

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 :

• La réponse parle de « patterns typiques » sans nommer vos fichiers réels
• Il introduit un nouvel utilitaire partagé au lieu d'utiliser un existant
• Il change des imports entre packages
• Il ignore les feature flags ou les branches spécifiques à l'environnement
• Il propose d'ajouter une dépendance à un package core partagé

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.

Checklist rapide avant de demander quoi que ce soit à Claude

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 :

• Boundary : Travailler seulement dans \u003cpackage\u003e/\u003cpath\u003e. Objectif : \u003cone sentence\u003e. Ignorer tout le reste sauf si demandé.
• Context starter : Local summary : \u003c5-10 lines\u003e. Fichier d'entrée : \u003cpath/to/file\u003e.
• Constraints : Dossiers autorisés : \u003c...\u003e. Ne pas changer : \u003cfolders/files or APIs\u003e. Conserver le comportement : \u003cwhat must stay true\u003e.
• Demandes de fichiers d'abord : “Avant de proposer des changements, listez les fichiers minimums que vous devez voir (max 5) et pourquoi.”
• Format de sortie : “Répondez d'abord avec un court plan. Après ma confirmation, donnez des suggestions au format patch par fichier.”

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.

Exemple : faire un changement dans un package sans réveiller tout le monorepo

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 :

1. Carte : « Ce changement est limité à CartPage et aux icônes ui-kit. Pas d'édition du checkout/auth. »
2. Hypothèses : exigez une liste d'hypothèses et attendez la confirmation.
3. Demandes de fichiers : n'approuvez que les quelques fichiers dont il a vraiment besoin (CartPage, useCart, icônes ui-kit, index ui-kit).
4. Plan : confirmez qu'il respecte les frontières.
5. Modifs : faites le diff le plus petit, puis demandez des tests mis à jour.

Après la modification, documentez-la pour que le contexte futur reste petit :

• Mettez à jour les deux local summaries avec le nouvel export et les fichiers exacts touchés.
• Ajoutez une courte note dans l'en-tête du fichier cart page : ce que fait le bouton et où l'état est géré.
• Enregistrez les commandes de test qui ont réussi (et les snapshots éventuels mis à jour).

Prochaines étapes : rendre ça répétable pour votre équipe

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.

Transformez vos meilleurs prompts en modèle d'équipe

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).

Maintenez les résumés à jour avec une cadence légère

É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.