Configurare Claude Code in un monorepo o in un codebase di grandi dimensioni

Configura Claude Code per monorepo e codebase a singolo albero di grandi dimensioni con file CLAUDE.md annidati, worktree sparse, code intelligence e skills per pacchetto in modo che Claude rimanga focalizzato sul codice su cui stai lavorando.

Un codebase di grandi dimensioni può essere un repository con milioni di righe o un monorepo con molti pacchetti. Claude Code funziona a qualsiasi dimensione, ma man mano che il codebase cresce, i valori predefiniti ottimizzati per progetti più piccoli possono riempire la finestra di contesto con istruzioni e letture di file non correlate al compito, consumando token e degradando le prestazioni di Claude.

Questa guida mostra ai singoli sviluppatori e ai team di ingegneria come limitare Claude alla parte del codebase che un compito tocca. Ogni sezione nota se un'impostazione è personale per la tua macchina o impegnata nel repository.

Cosa copre questa guida

La tabella sottostante elenca ogni impostazione e cosa realizza. L'albero dei file dopo di essa è il monorepo di esempio a cui si riferiscono tutti gli esempi di codice su questa pagina.

Settings on this page

Ogni impostazione sottostante è indipendente. Si stratificano piuttosto che si sostituiscono a vicenda, quindi applica quelle che si adattano al tuo repository. Scegli dove avviare Claude determina dove vivono i tuoi file di impostazioni, quindi leggilo per primo. Mettilo insieme mostra tutti loro combinati.

[!TIP]

Per tecniche di workflow che mantengono il contesto piccolo in qualsiasi repository, vedi Best practice per Claude Code. Un esempio è eseguire l'esplorazione in un subagent in modo che le letture di file rimangano fuori dalla conversazione principale. Per distribuire una configurazione di base a ogni sviluppatore nella tua organizzazione, vedi Configurare Claude Code per la tua organizzazione.

The example monorepo

Gli esempi in questa pagina si riferiscono a un monorepo con tre pacchetti. Gli stessi modelli funzionano in un codebase a singolo albero di grandi dimensioni: dove un esempio usa packages/api/, sostituisci con la tua directory di sottosistema come src/backend/ o lib/core/.

monorepo/
  CLAUDE.md                     # istruzioni radice
  packages/
    api/
      CLAUDE.md                 # istruzioni specifiche dell'API
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # istruzioni specifiche del frontend
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # istruzioni della libreria condivisa
      src/

Scegli dove avviare Claude

Dove avvii claude determina quali file Claude può leggere e modificare senza una concessione di autorizzazione aggiuntiva, quali file CLAUDE.md si caricano nel contesto all'avvio e quali impostazioni di progetto si applicano.

Le impostazioni di progetto in .claude/settings.json non vengono ereditate dalle directory padre come fanno i file CLAUDE.md. Per sapere quale directory .claude/settings.json una sessione legge, vedi dove Claude Code cerca ogni file.

Ogni sezione sottostante afferma se il suo file di impostazioni appartiene alla radice del repository o alla sottodirectory da cui avvii, e se è impegnato o mantenuto localmente.

Stratifica file CLAUDE.md per directory

In un codebase di grandi dimensioni, un singolo CLAUDE.md alla radice del repository tende a crescere per coprire le convenzioni di ogni sottosistema, consumando contesto su istruzioni non correlate al compito attuale, o rimanere troppo generico per essere utile. Dividere le istruzioni tra file per directory significa che Claude carica le regole a livello di repository più solo le convenzioni per il codice su cui stai lavorando.

Claude Code carica ogni file CLAUDE.md dalla tua directory di lavoro e da ogni directory padre all'avvio, quindi carica il file di ogni sottodirectory su richiesta. Un file radice imposta regole a livello di repository e ogni sottodirectory aggiunge la sua.

Una divisione comune è due livelli:

• Root CLAUDE.md: istruzioni che si applicano ovunque, come standard di codifica e convenzioni di commit
• Per-sottodirectory CLAUDE.md: convenzioni specifiche dello stack di quell'area. In un monorepo è uno per pacchetto. In un albero singolo di grandi dimensioni è uno per sottosistema come src/db/ o src/api/

Impegna questi file nel repository in modo che i compagni di squadra li ereditino. Il proprietario di ogni directory in genere mantiene il suo file.

Per ridurre un file già archiviato, esegui il controllo /doctor. Il root CLAUDE.md contiene le regole che si applicano in ogni pacchetto:

Esegui gli script del pacchetto dalla directory del pacchetto, non dalla radice del monorepo.
Prefissa i soggetti dei commit con il nome del pacchetto, ad esempio `api: add rate limiting`.
Non modificare mai i file sotto packages/*/generated/. Esegui `npm run codegen` nel pacchetto invece.

Il CLAUDE.md di ogni sottodirectory, qui packages/api/CLAUDE.md, aggiunge le convenzioni specifiche di quell'area:

Copia `.env.example` in `.env` prima di eseguire qualsiasi cosa. I test e il server dev falliscono senza di esso.
Scrivi le query del database con il query builder Knex. Non mettere mai stringhe SQL grezze nei gestori di route.
Non modificare mai una migrazione dopo che ne è stato fatto il merge. Aggiungi una nuova migrazione invece.

Quando avvii Claude da packages/api/, carica sia packages/api/CLAUDE.md che il root CLAUDE.md. Claude vede le istruzioni locali insieme alle regole a livello di repository, senza istruzioni da packages/web/ nel contesto. Lo stesso vale per qualsiasi sottodirectory in un albero non-monorepo. Per confermare quali file sono stati caricati, esegui /context all e controlla l'elenco sotto Memory files.

Alcuni modi per mantenere i file attuali man mano che il codebase e i modelli cambiano:

• Rivedi nelle pull request: tratta le modifiche CLAUDE.md come qualsiasi altro cambio di documentazione in modo che le convenzioni tracciino il codice
• Rivedi dopo i rilasci di modelli principali: le istruzioni che hanno aggirato una limitazione di un modello più vecchio possono diventare overhead una volta che un modello più nuovo gestisce il caso da solo. Ad esempio, una regola che forza refactor a file singolo può essere eliminata una volta che la limitazione è scomparsa
• Aggiungi un hook Stop che propone aggiornamenti: un Stop hook riceve il percorso della trascrizione della sessione quando Claude finisce di rispondere, quindi uno script può rivedere la sessione e proporre aggiornamenti CLAUDE.md mentre il divario che ha esposto è fresco

Per ulteriori informazioni su come i file CLAUDE.md si caricano e interagiscono, vedi Memory e istruzioni di progetto.

Scegli tra per-directory CLAUDE.md e regole con ambito di percorso

I file CLAUDE.md per directory e le regole con ambito di percorso sotto .claude/rules/ ti permettono entrambi di indirizzare le istruzioni a parte dell'albero. Differiscono in dove vive il file e quando si carica.

Per un confronto che copre anche le skills, vedi Confronta funzionalità simili.

Escludi file CLAUDE.md irrilevanti

Quando avvii Claude dalla radice del repository, il CLAUDE.md di ogni sottodirectory può caricarsi su richiesta durante la sessione. L'impostazione claudeMdExcludes salta file specifici per percorso o modello glob in modo che non si carichino mai.

Usalo per directory in cui non lavori mai, come pacchetti di altri team, codice legacy o sottoalberi venduti. L'elenco di esclusione è statico, non un interruttore per compito. Per focalizzarsi su un pacchetto oggi e un altro domani, avvia Claude da quella directory del pacchetto invece di modificare le esclusioni.

Se vuoi solo queste esclusioni per te, metti l'impostazione in .claude/settings.local.json. Claude Code aggiunge quel file al tuo gitignore globale quando salva un'impostazione lì. Poiché lo stai creando a mano qui, aggiungilo al tuo gitignore tu stesso. I modelli usano la sintassi glob abbinata ai percorsi di file assoluti, quindi inizia i modelli in stile relativo con **/ per abbinare ovunque nell'albero. L'esempio sottostante esclude un pacchetto di proprietà di un altro team:

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

Questo salta ogni CLAUDE.md e file di regole sotto quel pacchetto. Il root CLAUDE.md e i pacchetti su cui lavori ancora si caricano normalmente.

Questi modelli coprono altri casi comuni:

• "**/packages/*/CLAUDE.md": esclude il CLAUDE.md di ogni pacchetto mantenendo la radice
• "**/packages/legacy-*/**": esclude ogni pacchetto il cui nome corrisponde al glob, incluse le regole
• "/home/user/monorepo/legacy/CLAUDE.md": esclude un file specifico per percorso assoluto

Puoi impostare claudeMdExcludes in qualsiasi ambito di impostazioni: utente, progetto, locale o gestito. Gli array vengono combinati tramite merge tra gli ambiti, quindi un team può impostare i valori predefiniti a livello di progetto mentre i singoli aggiungono override locali. Se la tua organizzazione distribuisce un file CLAUDE.md gestito, un modello che vi corrisponde non lo esclude, qualunque sia l'ambito che imposta il modello.

Per la documentazione completa dell'esclusione, vedi Escludi file CLAUDE.md specifici.

Riduci quello che Claude legge

Le istruzioni sono solo parte di quello che finisce nel contesto di Claude. Le letture di file sono un altro costo che cresce con il codebase. Le impostazioni sottostanti bloccano le letture di percorsi irrilevanti e sostituiscono le scansioni esaustive con ricerche del language server.

Blocca le letture di codice generato e venduto

Le ricerche di contenuto di Claude rispettano .gitignore per impostazione predefinita, quindi i percorsi già elencati lì, come node_modules/, dist/ e build/, rimangono fuori dai risultati di ricerca senza configurazione aggiuntiva.

Per i percorsi che sono archiviati, come un SDK venduto o codice generato impegnato, aggiungi regole di negazione Read in permissions.deny per impedire a Claude di aprire quei file.

Le regole di negazione possono coprire tutti coloro che lavorano nel repository, solo voi, o ogni sessione sulla macchina, a seconda di quale file di impostazioni vi inserite:

• Tutti coloro che lavorano nel repository: impegnate le regole a .claude/settings.json, alla radice del repository se avviate Claude lì, o in ogni .claude/ del pacchetto se avviate da sottodirectory. Come altre impostazioni di progetto su questa pagina, quel file non viene ereditato dalle directory padre.

• Solo te: usa .claude/settings.local.json alla radice del repository. Si carica in ogni sessione CLI all'interno del repository indipendentemente dalla directory di avvio, tranne nei casi in cui Claude Code non utilizza la radice del repository, come su Windows.

  I pattern relativi come Read(./**/vendor/**/*) dell'esempio si ancorano comunque alla directory di lavoro corrente della sessione anziché alla radice del repository. Se avvii sessioni da sottodirectory, scrivi le regole in questo file come percorsi assoluti con //, come Read(//absolute/path/to/repo/**/vendor/**/*).

• Tutti, applicato in ogni sessione: impostate le regole in impostazioni gestite, che le impostazioni utente e progetto non possono ignorare.

L'esempio sottostante blocca gli artefatti di build e un SDK venduto. I suoi modelli di directory terminano con /**/* piuttosto che /** in modo che ogni regola copra tutto all'interno della directory ma non la directory stessa. Claude può quindi ancora elencare quelle directory o cambiarvi dentro, ad esempio con ls dist o cd build.

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

Le regole di negazione coprono gli strumenti di file integrati di Claude. In Bash, coprono i comandi di file che Claude Code riconosce, come cat, head, grep e find, quando un percorso negato appare come argomento, e il target di un reindirizzamento come < file. Claude Code fa anche un tentativo di massimo sforzo per lasciare i percorsi negati fuori dai risultati degli strumenti Grep e Glob integrati. Una ricerca Bash come grep -r o find su una directory che contiene file negati li include comunque nel suo output.

Le regole di negazione non coprono i sottoprocessi che aprono file da soli. Per la sintassi del modello completo, vedi Regole di autorizzazione Read e Edit.

Riduci le letture di file con code intelligence

In un codebase di grandi dimensioni, trovare dove un simbolo è definito o usato può costare molte letture di file e chiamate grep. I plugin di code intelligence collegano Claude a un language server in modo che possa saltare alle definizioni, trovare riferimenti e far emergere errori di tipo direttamente invece di scansionare l'albero.

Il marketplace ufficiale ha plugin per TypeScript, Python, Go, Rust e altri linguaggi comuni. Nell'estensione VS Code o nell'app desktop, installane uno seguendo Installare un plugin. In un terminale, avvia Claude Code eseguendo claude, quindi inserisci questo al suo prompt per installare il plugin TypeScript:

/plugin install typescript-lsp@claude-plugins-official

Se l'installazione fallisce, abbinate il messaggio che Claude Code segnala:

• Marketplace "claude-plugins-official" not found: aggiungete il marketplace con /plugin marketplace add anthropics/claude-plugins-official, quindi riprovate l'installazione.
• Plugin "<name>" not found in marketplace "claude-plugins-official": la tua copia locale del catalogo del marketplace potrebbe non essere aggiornata. Aggiornala con /plugin marketplace update claude-plugins-official, quindi riprova l'installazione. Se il nuovo tentativo stampa lo stesso messaggio, consulta Plugin not found in marketplace.

Per attivare un plugin per tutti nel repository, aggiungilo all'impostazione di progetto enabledPlugins. Ogni persona deve comunque installarlo.

I plugin di code intelligence richiedono il binario del language server del linguaggio su ogni macchina dello sviluppatore. Vedi quale binario richiede ogni linguaggio. L'installazione dal marketplace ufficiale richiede accesso di rete a GitHub, dove è ospitato il marketplace. Su una rete ristretta, aggiungete il marketplace da un host Git interno o da un percorso locale invece.

Questo si abbina bene con claudeMdExcludes e le regole Read di negazione sopra. Quelli mantengono il contenuto irrilevante fuori dal contesto, e code intelligence impedisce a Claude di leggere attraverso quello che rimane per individuare una definizione.

Limitare i worktree e l'accesso ai file

Queste impostazioni controllano cosa si trova su disco nei worktree e quali directory Claude può leggere e scrivere oltre il tuo punto di partenza.

Eseguire il checkout solo delle directory necessarie

Il flag --worktree avvia una sessione in un nuovo worktree git, in modo che le modifiche restino isolate dal tuo checkout principale. Per impostazione predefinita esegue il checkout dell'intero repository. In un repository di grandi dimensioni, l'impostazione worktree.sparsePaths usa lo sparse-checkout di git per scrivere su disco solo le directory elencate più i file a livello di root, così i worktree si avviano più velocemente e occupano meno spazio.

Se tutti coloro che lavorano in questa directory hanno bisogno degli stessi percorsi, fai il commit dell'impostazione in .claude/settings.json. Per aggiungere percorsi solo per te, usa .claude/settings.local.json: le liste vengono unite tra gli ambiti, quindi un file locale può aggiungere percorsi alla lista di cui è stato fatto il commit ma non rimuoverli.

Gli esempi JSON in questa pagina mostrano un'impostazione alla volta. Se il tuo .claude/settings.json contiene già altre chiavi, come le regole permissions.deny viste sopra, aggiungi la chiave worktree accanto a esse invece di sostituire il file. Mettere tutto insieme mostra il risultato combinato.

L'esempio seguente mostra il file di cui è stato fatto il commit:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

Quando Claude crea un worktree, esegue il checkout solo di .claude/, packages/api/ e packages/shared/ invece dell'intero albero. I percorsi in sparsePaths sono relativi alla root del repository, indipendentemente dalla sottodirectory da cui avvii Claude. Qui funziona qualsiasi percorso di directory, non solo le root dei package.

Questo è particolarmente utile per l'isolamento con worktree dei subagent. I subagent sono istanze parallele di Claude generate per le sottoattività, e ognuno di quelli eseguiti in un worktree ottiene un checkout leggero invece dell'intero albero. Tutti i worktree di una sessione condividono gli stessi sparsePaths, quindi se un subagent ha bisogno di packages/api/ e un altro di packages/web/, elencali entrambi.

Elenca directory in sparsePaths, non singoli file. I file a livello di root come package.json, tsconfig.base.json e i file di lock vengono sempre inclusi nel checkout insieme alle directory che elenchi. Le directory a livello di root invece no, quindi includi .claude nella lista se vuoi che .claude/settings.json o .claude/rules/ della root del repository siano disponibili all'interno del worktree. Per le skill, gli agenti e i comandi del progetto, consulta Cosa condividono i worktree con il checkout principale.

[!NOTE]

Lo sparse checkout richiede che git abiliti extensions.worktreeConfig nel file .git/config condiviso del repository finché esiste un worktree sparse. Claude Code rimuove quella voce dopo la rimozione dell'ultimo worktree, ma solo se è stato Claude Code ad aggiungerla.

Per evitare di duplicare directory di grandi dimensioni come node_modules tra i worktree, abbina sparsePaths a symlinkDirectories nello stesso .claude/settings.json:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

Questo crea un collegamento simbolico dalla directory node_modules/ di ogni worktree alla copia del repository principale invece di duplicarla su disco.

[!NOTE]

Le impostazioni sparsePaths e symlinkDirectories vengono lette dalla tua directory di partenza prima che il worktree venga creato. Dopo la creazione, la directory di lavoro della sessione è la root del worktree, non la sottodirectory da cui hai avviato Claude. Le impostazioni di progetto all'interno del worktree vengono quindi caricate dal .claude/settings.json della root del worktree, ovvero la copia sottoposta a checkout del file nella root del repository. Inserisci tutte le altre impostazioni di cui hai bisogno all'interno dei worktree, come regole di permesso o hook, nel .claude/settings.json della root del repository.

Per il riferimento completo delle impostazioni dei worktree, consulta Impostazioni dei worktree.

Concedere l'accesso tra package o repository

Questa sezione si applica quando avvii Claude da una sottodirectory, oppure quando un'attività coinvolge più checkout. Se avvii Claude dalla root del repository in un unico albero di grandi dimensioni, Claude ha già accesso a ogni file e puoi saltare questa parte.

Quando avvii Claude da packages/api/, può leggere e scrivere file all'interno di quella directory. Se un'attività richiede modifiche tra più package, come l'aggiornamento di un tipo condiviso importato sia da api sia da web, devi concedere l'accesso alla directory adiacente. Lo stesso meccanismo concede l'accesso a un repository di cui è stato eseguito un checkout separato.

L'impostazione additionalDirectories in .claude/settings.json dà a Claude accesso a directory esterne alla directory di lavoro. L'esempio seguente concede l'accesso a due package adiacenti:

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

I percorsi relativi vengono risolti rispetto alla directory da cui avvii Claude. Con questa configurazione, Claude può leggere e modificare file in packages/shared/ e packages/web/ mentre lavora da packages/api/.

Puoi anche concedere l'accesso in fase di esecuzione senza modificare le impostazioni, passando --add-dir quando avvii Claude:

claude --add-dir ../shared

In qualunque modo tu aggiunga una directory, Claude può leggere e modificare i file al suo interno. Il caricamento anche del CLAUDE.md, dei file .claude/rules/ e delle skill della directory dipende da come l'hai aggiunta:

Per caricare CLAUDE.md e i file delle regole da una directory aggiunta con --add-dir o /add-dir, imposta la variabile d'ambiente CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared

La variabile d'ambiente non ha alcun effetto sulle directory elencate nell'impostazione additionalDirectories. Consulta Caricare da directory aggiuntive per i dettagli.

Per le directory adiacenti di cui tutti in quest'area hanno bisogno, fai il commit di additionalDirectories in .claude/settings.json. Per una selezione personale o un accesso occasionale, usa .claude/settings.local.json oppure passa --add-dir all'avvio.

Aggiungere skills per directory

Qualsiasi sottodirectory può definire skill limitate al proprio stack. Una skill si carica su richiesta quando Claude determina che è rilevante.

Le skills si trovano sotto .claude/skills/ all'interno della directory. Eseguine il commit insieme al codice di quell'area in modo che chiunque cloni il repository le ottenga. In un monorepo questo può essere un set di skills per package. In un grande codebase a singolo albero è un set per sottosistema come src/db/.claude/skills/.

Crea una directory skill all'interno della sottodirectory:

mkdir -p packages/api/.claude/skills/api-testing

Quindi scrivi SKILL.md all'interno di quella directory, qui packages/api/.claude/skills/api-testing/SKILL.md. Questo esempio insegna a Claude i pattern di testing del package API:

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---

## Test structure

Tests are in `src/__tests__/` mirroring the `src/` directory structure.
Each route file has a corresponding `.test.ts` file.

## Running tests

- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`
- Watch mode: `npm test -- --watch`

## Test utilities

- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests
- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints

## Patterns

- Use `supertest` for HTTP assertions, not raw fetch
- Always wrap database tests in a transaction that rolls back
- Mock external services in `src/__tests__/mocks/`

Una diversa sottodirectory contiene diverse skill nello stesso modo: packages/web/.claude/skills/component-patterns/ descrive le convenzioni dei componenti del frontend invece del testing. Quando Claude lavora su un file in packages/api/, carica la skill api-testing. Quando lavora in packages/web/, carica component-patterns.

Puoi anche limitare una skill per pattern di file invece che per posizionamento. Il campo frontmatter paths accetta pattern glob, e Claude carica la skill automaticamente solo quando lavora con file corrispondenti. Usalo per una skill che si trova nella .claude/skills/ della radice del repository ma si applica solo a certi file, come una skill di migrazione del database limitata a **/migrations/**.

Per ulteriori informazioni sulla creazione e organizzazione delle skills, vedi Skills.

Mantieni le skills individuabili

Con skills sparse in molte directory, l'elenco da cui Claude sceglie può crescere molto. Claude sceglie una skill leggendo il nome e la descrizione di ogni skill scoperta, e solo il contenuto completo della skill scelta si carica nel contesto. Questa sezione spiega come mantenere quell'elenco piccolo.

Quali skills sono in ambito dipende da dove avvii Claude:

• Da una sottodirectory come packages/api/: skills da quella directory, ogni parent fino alla radice del repository, e i livelli utente e azienda
• Dalla radice del repository: skills della radice, più skills da ogni sottodirectory che Claude tocca durante la sessione, che possono accumularsi nelle centinaia
• Dopo aver aggiunto un sibling con --add-dir: le skills di quel sibling si caricano anche. L'impostazione additionalDirectories concede solo accesso ai file e non carica skills

I nomi si caricano sempre, ma quando ce ne sono molti, alcune skills perdono completamente le loro descrizioni, il che può eliminare le parole chiave che Claude usa per decidere se una skill si applica. Mantieni le descrizioni brevi e inizia con parole che una richiesta conterrebbe, come "writing or modifying tests in packages/api/".

Per skills che molte directory condividono, come convenzioni PR o una checklist di deploy, posizionale nella .claude/skills/ della radice del repository in modo che si carichino da qualsiasi directory di avvio. Quando le skills condivise hanno bisogno della propria cronologia delle versioni o devono funzionare tra repository, pacchettale come un plugin invece. Le skills dei plugin usano uno spazio dei nomi plugin-name:skill-name, quindi non collidono mai con le skills per directory. Un team di piattaforma può versionalizzarle e aggiornarle in un unico posto.

Per trovare quali skills rimangono inutilizzate, abilita l'esportatore di log OpenTelemetry e imposta OTEL_LOG_TOOL_DETAILS=1 in modo che i nomi delle skills siano registrati verbatim invece di essere redatti. L'evento skill_activated registra ogni invocazione nel suo attributo skill.name, e invocation_trigger registra se un comando, Claude, o una skill nidificata l'ha invocata, il che ti dice cosa consolidare o ritirare.

Centralizza le convenzioni quando la stratificazione smette di scalare

I file CLAUDE.md per directory possono diventare difficili da governare man mano che il codebase cresce. Le convenzioni si allontanano, i file diventano obsoleti, e nessuno possiede la radice. Risolvere questo in genere spetta al team che mantiene la configurazione di Claude Code del repository piuttosto che a ogni sviluppatore che lavora nella sua area.

Sposta le convenzioni e il contenuto di riferimento fuori da CLAUDE.md sempre caricato e in meccanismi che si caricano su richiesta:

• Skills: materiale di riferimento che Claude carica solo quando rilevante per il compito
• Plugin: bundle versionati di skill, hook e comandi che un team di piattaforma possiede centralmente e può installare per tutti tramite le impostazioni gestite
• MCP servers: se la tua organizzazione già esegue una ricerca di codice o un indice RAG sul repository, esponilo come uno strumento MCP in modo che Claude lo interroghi invece di leggere i file direttamente

Vedi impostazioni gestite dal server o gestite dall'endpoint per come i team di piattaforma possono applicare questi centralmente.

Consiglia il plugin giusto all'avvio della sessione

Una volta che le convenzioni vivono nei plugin, un compagno di squadra che avvia Claude in una parte sconosciuta dell'albero non ha segnale su quale plugin i proprietari di quell'area mantengono. Un SessionStart hook può colmare quel divario, poiché Claude Code aggiunge il testo semplice che l'hook stampa su stdout al contesto di Claude prima del primo prompt.

Ad esempio, puoi scrivere uno script che legge la directory di avvio dall'input dell'hook, la cerca in una mappa percorso-a-plugin impegnata al repository, e stampa la raccomandazione per Claude da trasmettere nella sua prima risposta. Vedi Automatizza azioni con hook per scrivere e registrare l'hook.

Mettere tutto insieme

La configurazione combinata di seguito utilizza il layout monorepo. Gli stessi file funzionano per qualsiasi sottodirectory in un grande albero singolo. Il .claude/settings.json di ogni sottodirectory deve essere autonomo piuttosto che stratificato su un file radice.

L'esempio esegue il commit di worktree, additionalDirectories e le regole di negazione Read in .claude/settings.json in modo che ogni sviluppatore in packages/api/ ottenga lo stesso accesso ai sibling, percorsi sparsi ed esclusioni. Il file di seguito è la configurazione per area impegnata per packages/api/:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  },
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)"
    ]
  }
}

Poiché questa sessione inizia da packages/api/, i file CLAUDE.md dei pacchetti sibling sono già fuori portata, quindi claudeMdExcludes non è necessario qui. Aggiungetelo invece al .claude/settings.local.json della radice del repository se avviate anche sessioni dalla radice.

La voce additionalDirectories si applica quando avviate Claude da packages/api/ direttamente. All'interno di un worktree creato da questa sessione, la directory di lavoro è la radice del worktree, quindi questo file di impostazioni non si carica. I pacchetti sibling sono già raggiungibili all'interno del worktree senza di esso, ma le regole di negazione hanno bisogno di una seconda copia nel .claude/settings.json della radice del repository in modo che le sessioni worktree le raccolgano, come la nota sulle impostazioni worktree descrive:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)"
    ]
  }
}

Dopo la configurazione, il repository ha questo layout:

monorepo/
  CLAUDE.md
  .claude/settings.json                           # deny rules for worktree sessions
  packages/
    api/
      CLAUDE.md
      .claude/settings.json                       # worktree, additionalDirectories, deny rules
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

Con questa configurazione, avviando Claude da packages/api/:

• Carica il CLAUDE.md radice e packages/api/CLAUDE.md, salta packages/web/CLAUDE.md
• Può leggere e modificare file in packages/api/ e packages/shared/
• Salta le letture dell'output di build sotto dist/ e build/ in packages/api/
• Ha la skill api-testing disponibile su richiesta
• Crea worktree contenenti .claude/, packages/api/, packages/shared/ e file a livello radice, con le regole di negazione applicate nel worktree dal file di impostazioni radice

Ambito e pianifica i cambiamenti che si estendono tra pacchetti

La configurazione sopra controlla cosa Claude vede. Quando un singolo cambiamento tocca diversi pacchetti, come aggiornare un tipo condiviso insieme a ogni sito di chiamata che lo usa, come scopi e sequenzi il compito influisce anche sul risultato.

Due tecniche aiutano a mantenere un cambiamento tra pacchetti coerente:

• Dai a Claude l'intero cambiamento in una sessione: consegnare la modifica condivisa e i suoi siti di chiamata insieme mantiene le decisioni dietro ogni modifica coerenti, piuttosto che derivarle di nuovo per pacchetto
• Pianifica prima di modificare: pianifica prima in plan mode, e Claude scrive il piano in un file. Una lunga sessione tra pacchetti compatta il suo contesto lungo il percorso. Claude Code reinietta il file del piano dopo ogni compattazione, quindi il piano sopravvive dove la cronologia della conversazione potrebbe non farlo

Passaggi successivi

Una volta che questa configurazione è in atto, puoi affinarla:

• Usa hooks per eseguire linter o type-checker per directory dopo che Claude modifica i file
• Rivedi Gestisci i costi in modo efficace per capire come la dimensione del codebase influisce sull'utilizzo dei token e come impostare i limiti di spesa prima di un rollout più ampio
• Leggi Come Claude Code funziona nei codebase di grandi dimensioni sul blog di Claude per i modelli di rollout organizzativo e i modelli di proprietà che si trovano sopra la configurazione per repository su questa pagina