Claude Code nei monorepo può perdere accuratezza quando il repository è enorme. Scopri come definire confini, riassunti locali e workflow ripetibili per mantenere le risposte precise.
Claude Code nei monorepo può risultare imprevedibile per una ragione semplice: il repository è più grande di quanto il modello possa tenere in memoria contemporaneamente.
Il "contesto" è l'insieme di file, frammenti, note e istruzioni che sono stati mostrati a Claude per questo compito, oltre a ciò che può inferire da essi. Quando mancano dettagli chiave, Claude riempie i vuoti con supposizioni. In un grande repo succede più spesso.
Tre modalità di errore ricorrono frequentemente:
Primo: file mancanti. Una modifica che sembra sicura in una cartella dipende in realtà da un tipo condiviso, una regola di configurazione o uno step di build definiti altrove. Se quella dipendenza non è nel contesto, Claude può modificare la cosa sbagliata con sicurezza o fermarsi perché non vede la vera fonte di verità.
Secondo: falsi simili. I monorepo spesso contengono più pacchetti che si assomigliano: due moduli auth, tre client API o diverse app React con strutture di cartelle simili. Claude può mescolare pattern tra di loro, aggiornare un helper nel pacchetto sbagliato o importare dal modulo col nome “quasi giusto”.
Terzo: deriva temporale. Le codebase grandi in genere mantengono modi vecchi e nuovi di fare la stessa cosa. Se Claude vede solo file più vecchi, può copiare pattern obsoleti (opzioni di config deprecate, API legacy) anche se il team è già passato a soluzioni diverse.
Un esempio reale comune: chiedi una piccola modifica all'interfaccia di fatturazione e Claude modifica un componente payments condiviso usato da altre app perché non ha visto il wrapper specifico dell'app che avrebbe dovuto essere modificato.
L'obiettivo non è mostrare a Claude l'intero monorepo. L'obiettivo è fornire input piccoli e intenzionali che rispondano alla domanda: il package che stai cambiando, le sue dipendenze dirette e una o due “fonti di verità” per tipi e configurazioni. Indica anche le aree “non toccare” (altre app, infra, codice generato) e conferma quale package possiede il comportamento.
L'accuratezza dipende meno dalla quantità di codice che incolli e più da quanto chiaramente descrivi il lavoro.
Inizia dall'obiettivo che vuoi raggiungere: una correzione specifica, un refactor o una risposta. Una “domanda sul codice” può restare ad alto livello. Una richiesta di “fare una modifica” richiede confini, input e criteri di successo.
Prima di condividere qualsiasi cosa, scrivi una frase che completi questa espressione: “Dopo che avrai finito, dovrei essere in grado di…”. Per esempio: “eseguire i test unitari del package X senza errori” o “vedere il nuovo campo nella risposta API per l'endpoint Y.” Quella frase diventa la stella polare quando il repo è enorme.
Per le modifiche, condividi il set minimo di artefatti che possa provare che la modifica è corretta: i punti di ingresso, i tipi/interfacce o lo schema rilevante, un test che fallisce o un passo di riproduzione con il risultato atteso, e qualsiasi configurazione che influisca su questo percorso (routing, feature flag, build o regole di lint). Se aiuta, aggiungi una breve mappa delle cartelle del package in modo che Claude capisca a cosa serve ogni directory.
Sii esplicito su cosa non guardare. Dì: “Ignora file generati, cartelle vendor, output di build, snapshot e lockfile a meno che non lo chieda.” Questo evita tempo sprecato e modifiche in posti che non rivedrai.
Imposta anche le aspettative sull'incertezza. Chiedi a Claude di segnalare ipotesi e punti non noti invece di indovinare. Per esempio: “Se non puoi vedere dove questa funzione è chiamata, dillo e proponi 2 modi per individuarla.”
In un grande monorepo l'accuratezza cala quando il modello inizia a “aiutare” tirando dentro codice vicino che non fa parte del compito. La soluzione è semplice: definisci cosa è in-scope e cosa è out-of-scope prima di chiedere modifiche.
Inizia con un confine che rispecchi come è organizzato il repo: un package, un servizio, un'app o una libreria condivisa. Se la modifica è “aggiorna l'interfaccia di checkout”, il confine è probabilmente il package dell'app, non ogni posto in cui appare la parola “checkout”.
Segnali che aiutano Claude a restare nel posto giusto includono convenzioni di cartelle (apps/, services/, packages/, libs/), manifest di package (exports e dependencies), punti di ingresso pubblici (file index, componenti esportati, handler) e test (spesso rivelano l'area di superficie prevista). Un README dentro la cartella può essere il marcatore di confine più veloce.
I confini funzionano meglio quando nomini i ponti tra essi. Indica le interfacce specifiche che Claude può toccare e tratta tutto il resto come off limits. I ponti tipici sono contratti API HTTP, topic/eventi e payload, tipi condivisi o un piccolo insieme di funzioni esportate.
Nomina anche le zone “non toccare” ogni volta che la modifica non deve influenzarle. Quelle comuni sono configurazioni di infrastruttura e deployment, logica di sicurezza e auth, fatturazione e pagamenti, migrazioni dati e schemi di produzione, e librerie condivise usate da molti team.
Un dettaglio di prompt concreto che aiuta:
“Modifica solo dentro packages/cart/ e i suoi test. Puoi leggere i tipi condivisi in packages/types/ ma non modificarli. Non editare infra, auth o billing.”
L'accuratezza migliora quando fornisci una mappa piccola e stabile dell'area che vuoi cambiare. Un “riassunto locale” è quella mappa: abbastanza breve da leggere in fretta, abbastanza specifico da evitare supposizioni.
Tieni ogni riassunto intorno alle 10–20 righe. Scrivilo come se passassi il codice a un nuovo collega che deve toccare solo questo confine, non tutto il repo. Usa linguaggio semplice e nomi reali dal codice: cartelle, package, funzioni esportate.
Un riassunto utile risponde a cinque domande:
Aggiungi una riga “gotchas”. Qui previeni errori costosi: cache nascosta, feature flag, passi di migrazione e qualsiasi cosa che fallisca silenziosamente.
Ecco un template compatto che puoi copiare:
Local summary: <package/service name>
Purpose: <1 sentence>
Scope: <what to touch> | Not: <what not to change>
Entry points: <files/routes/commands>
Public surface: <exports/endpoints/events>
Data sources: <tables/collections/queues/caches>
Conventions: errors=<how>, logging=<how>, tests=<where/how>
Gotchas: <flags/caching/migrations/edge cases>
Example: se stai modificando un package di billing, annota la funzione esatta che crea le fatture, i nomi delle tabelle su cui scrive e la regola per gli errori retryable. Così Claude può concentrarsi su quel confine invece di vagare in auth condivisa, config o package non correlati.
Il riassunto migliore è quello che Claude vede quando ne ha bisogno. Mettilo accanto al codice che descrive in modo che sia difficile ignorarlo e facile da aggiornare. Per esempio, tieni un breve SUMMARY.md (o una sezione di README.md) dentro ogni package, servizio o directory app invece di un unico documento enorme alla radice.
Una struttura semplice e ripetibile aiuta. Mantienila abbastanza corta perché le persone la aggiornino:
YYYY-MM-DD - <what changed in one sentence>I riassunti diventano obsoleti per ragioni prevedibili. Tratta gli aggiornamenti come parte del lavoro: aggiornare il riassunto quando un refactor cambia struttura o nomi, un nuovo modulo diventa il modo principale di fare qualcosa, un API/event/schema cambia, i confini tra package si spostano o una dipendenza viene rimossa/sostituita.
Una pratica utile: quando mergi una modifica, aggiungi una riga “Last updated” che spieghi cosa è cambiato. Strumenti come Koder.ai possono aiutare a muoversi più velocemente sul cambiamento di codice, ma il riassunto è ciò che mantiene accurate le modifiche future.
L'accuratezza spesso dipende da come scandisci la conversazione. Fai guadagnare a Claude il contesto a piccoli pezzi invece di fargli indovinare da un enorme snapshot.
Prima di qualsiasi modifica, chiedi a Claude di descrivere ciò che vede e cosa gli serve. Una buona mappa è breve: pacchetti coinvolti, punto di ingresso del flusso e dove vivono test o tipi.
Prompt:
“Create a map of this change: packages involved, main flow, and likely touch points. Do not propose code yet.”
Scegli una fetta stretta: una feature, un package, un user flow. Indica il confine chiaramente (per esempio: “Modifica solo packages/billing-api. Non toccare shared-ui o infra.”).
Un workflow che ti mantiene in controllo:
Se a Claude manca qualcosa, deve dirlo. Chiedigli di scrivere: (1) le ipotesi che sta facendo, (2) cosa le falsificherebbe, e (3) i file successivi necessari per confermare.
Esempio: devi aggiungere un campo alla risposta Invoice in un package. Claude richiede l'handler, la definizione DTO/tipo e un test. Condividi solo quelli. Se usi un builder chat-based come Koder.ai, vale la stessa regola: fornisci il set minimo di file, poi espandi solo quando davvero serve.
La tua miglior difesa contro modifiche errate è un piccolo “contratto” scritto nel prompt: cosa Claude può toccare, come giudicherai il successo e quali regole deve seguire.
Inizia con un confine facile da rispettare e verificare. Sii esplicito su dove sono permessi gli edit e nomina le zone “do not touch” così non c'è tentazione di vagare.
Template di contratto:
packages/payments/.packages/auth/, infra/ o config condivisi.Poi definisci i controlli di accettazione. Senza di essi, Claude può produrre codice che sembra corretto ma viola le regole reali del repo.
I vincoli di stile contano. Dì a Claude quali pattern seguire e quali evitare, basandoti su ciò che il codebase fa già. Per esempio: “Usa gli helper di errore esistenti in questo package; non aggiungere nuove dipendenze; mantieni i nomi delle funzioni in camelCase; non introdurre un nuovo layer architetturale.”
Infine, richiedi un breve piano prima di qualsiasi modifica:
“Prima di editare, elenca i 3–5 file che prevedi di toccare e il cambiamento di comportamento esatto. Aspetta l'approvazione.”
Esempio:
“Fix rounding in invoice totals. Only edit packages/billing/src/ and tests under packages/billing/test/. Acceptance: pnpm -C packages/billing test and typecheck. Follow existing money utils; do not rewrite API types. Provide a 4-step plan first.”
Il modo più veloce per ottenere modifiche errate in un monorepo è dare a Claude troppo materiale insieme. Quando incolli una grande quantità di codice, spesso ricade su pattern generici invece del design specifico che il tuo repo usa.
Un'altra trappola è lasciarlo indovinare l'architettura. Se non mostri i veri punti di ingresso, potrebbe scegliere il primo file che sembra plausibile e collegare la logica lì. In pratica, l'accuratezza viene da un piccolo numero di file “fonte di verità” (moduli di ingresso, router, registry di servizi, documenti di confine del package). Se quelli non sono nel contesto, il modello riempie i vuoti.
I nomi possono anche ingannare. I monorepo spesso hanno package come ui, ui-kit, shared-ui, o helper duplicati come date.ts in due posti. Se mescoli frammenti di entrambi, Claude potrebbe patchare un file mentre ragiona sull'altro. Esempio: chiedi di cambiare uno stile di bottone, modifica packages/ui/Button.tsx, ma l'app importa packages/ui-kit/Button.tsx. Il diff sembra a posto, ma in produzione nulla cambia.
La configurazione è un'altra fonte di deriva silenziosa. Il comportamento può dipendere da variabili d'ambiente, feature flag, impostazioni di build o tooling di workspace. Se non le menzioni, Claude può togliere un controllo “strano” che invece è necessario quando un flag è attivo, o aggiungere codice che rompe uno step di build.
Segnali di allarme che stai deragliando:
Tratta gli import cross-package come una decisione, non come default. Mantieni le modifiche locali a meno che tu non espanda intenzionalmente lo scope.
Il modo più veloce per ottenere modifiche corrette è partire da limiti, non da volume. Un buon prompt è un po' severo: dice a Claude dove guardare, cosa ignorare e cosa significa “fatto”.
Prima di incollare codice, scrivi un breve preambolo che fissi il lavoro in un punto del repo. Nomina il package, la cartella esatta e l'obiettivo specifico. Poi includi un riassunto locale (scopo, dipendenze chiave, convenzioni importanti) e il file di ingresso che ancora la modifica.
Checklist:
\u003cpackage\u003e/\u003cpath\u003e. Goal: \u003cone sentence\u003e. Ignora tutto il resto a meno che non lo chieda.\u003c5-10 lines\u003e. Entry file: \u003cpath/to/file\u003e.\u003c...\u003e. Non modificare: \u003cfolders/files or APIs\u003e. Mantieni comportamento: \u003cwhat must stay true\u003e.Se Claude propone modifiche fuori dal tuo confine, trattalo come un segnale: o stringi il prompt, o espandi lo scope intenzionalmente e ridefiniscilo chiaramente.
Supponiamo che il tuo monorepo abbia apps/web-store (un'app React) e packages/ui-kit (botttoni, input e stili condivisi). Vuoi una piccola feature: aggiungere un pulsante “Save for later” nella pagina del carrello, usando una nuova SaveIcon da ui-kit. Nulla altro deve cambiare.
Prima di chiedere edit, crea due riassunti locali che agiscano da confine. Tienili corti, specifici e opinabili su cosa conta.
# 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
Poi tieni il loop corto:
CartPage e alle icone di ui-kit. Nessuna modifica a checkout/auth.”CartPage, useCart, icone ui-kit, index ui-kit).Dopo la modifica, documentala così il contesto futuro resta piccolo:
Se funziona per una persona ma non per il resto del team, il pezzo mancante è di solito la ripetibilità. Fai diventare la “buona igiene del contesto” il default, non un'abitudine personale.
Salva un prompt scheletro che tutti possono copiare e compilare. Tienilo breve ma rigido. Includi l'obiettivo (cosa significa “fatto”), lo scope permesso, confini fissi (e perché), un riassunto locale e un contratto di output (piano prima, poi diff-style ed test).
Evita grandi revisioni mensili che nessuno fa. Associa l'aggiornamento dei riassunti al lavoro normale: quando una modifica altera comportamento, dipendenze o API, aggiorna il riassunto nello stesso PR.
Una regola semplice: se un collega chiederebbe “dove vive questo?” o “cosa dipende da questo?”, il riassunto è ormai obsoleto.
Se preferisci un workflow chat-first, Koder.ai può aiutare a rendere questo stile di iterazione più sicuro. La planning mode aiuta a concordare scope e confini prima delle modifiche, e gli snapshot con rollback permettono di provare cambiamenti senza rimanere bloccati quando una supposizione risulta sbagliata.
Claude diventa meno accurato quando non può "vedere" la vera fonte di verità.
In un grande monorepo il modello spesso manca un file di dipendenza, confonde due pacchetti simili o copia un pattern più vecchio perché è quello presente nel contesto.
Non cercare di includere l'intero repository. Parti dal set più piccolo che possa dimostrare che la modifica è corretta.
Un buon punto di partenza è:
Condividi ciò che ancora ancorà il comportamento, non tutto ciò che ha lo stesso nome.
Un set pratico è:
Scegli un confine che corrisponda a come è organizzato il repo: un package, un'app o un servizio.
Poi dichiaralo esplicitamente, compreso ciò che è fuori scope. Esempi di vincoli:
packages/cart/ e i suoi test.”Perché i monorepo spesso contengono moduli che si somigliano (ui, ui-kit, shared-ui) e helper duplicati (date.ts in più posti).
Claude può applicare l'idea giusta al pacchetto sbagliato o importare da un nome di modulo “quasi giusto”. Preveni questo nominando il pacchetto esatto e i punti di ingresso che intendi.
Un riassunto locale è una mappa breve dell'area esatta che vuoi modificare, di solito 10–20 righe.
Includi:
Mettilo vicino al codice che descrive in modo che sia facile da trovare e aggiornare.
Un default semplice:
SUMMARY.md o una piccola sezione nel README.md del packageDì a Claude di segnalare ipotesi e incognite invece di indovinare.
Una regola utile:
Usa un ciclo serrato che costringa il contesto a essere acquisito a piccoli passi:
Scrivi un mini “contratto” nel prompt e rendilo vincolante:
Questo rende più facile la revisione e riduce modifiche accidentali cross-package.