SpyBara
Go Premium

large-codebases.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

511 added, 0 removed.

2026
Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Configurar Claude Code em um monorepo ou grande base de código

Configure Claude Code para monorepos e grandes bases de código de árvore única com arquivos CLAUDE.md aninhados, worktrees esparsos, inteligência de código e skills por pacote para que Claude permaneça focado no código em que você está trabalhando.

Uma grande base de código pode ser um repositório com milhões de linhas ou um monorepo com muitos pacotes. Claude Code funciona em qualquer tamanho, mas conforme a base de código cresce, os padrões ajustados para projetos menores podem preencher a janela de contexto com instruções e leituras de arquivo não relacionadas à tarefa, custando tokens e degradando o desempenho do Claude.

Este guia mostra a desenvolvedores individuais e equipes de engenharia como escopar Claude para a parte da base de código que uma tarefa toca. Cada seção observa se uma configuração é pessoal à sua máquina ou confirmada no repositório.

O que este guia cobre

A tabela abaixo lista cada configuração e o que ela realiza. A árvore de arquivos depois dela é o monorepo de exemplo ao qual cada amostra de código nesta página se refere.

Configurações nesta página

Cada configuração abaixo é independente. Elas se sobrepõem em vez de se substituírem, então aplique aquelas que se adequarem ao seu repositório. Escolha onde iniciar Claude determina onde seus arquivos de configuração vivem, então leia primeiro. Junte tudo mostra todos eles combinados.

Eu quero Usar
Carregar apenas as convenções para o código que você toca, em vez de um arquivo raiz cobrindo cada subsistema Arquivos CLAUDE.md por diretório
Excluir arquivos CLAUDE.md para pacotes em que você nunca trabalha claudeMdExcludes
Impedir que Claude abra saída de compilação, código gerado e dependências fornecidas Regras de negação Read em permissions.deny
Encontrar a definição de um símbolo ou chamadores através do servidor de linguagem em vez de verificar arquivos Um plugin de inteligência de código
Verificar apenas os diretórios que uma tarefa precisa quando Claude cria um worktree worktree.sparsePaths
Ler e editar um pacote irmão ou outro repositório da mesma sessão --add-dir ou additionalDirectories
Dar ao Claude procedimentos específicos de uma área que carregam apenas quando relevante Skills por diretório
Substituir muitos arquivos CLAUDE.md por diretório com um conjunto de convenções que todos instalam Um plugin em um marketplace interno

O monorepo de exemplo

Os exemplos ao longo desta página se referem a um monorepo com três pacotes. Os mesmos padrões funcionam em uma grande base de código de árvore única: onde um exemplo usa packages/api/, substitua seu próprio diretório de subsistema como src/backend/ ou lib/core/.

monorepo/
  CLAUDE.md                     # instruções raiz
  packages/
    api/
      CLAUDE.md                 # instruções específicas da API
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # instruções específicas do frontend
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # instruções da biblioteca compartilhada
      src/

Escolha onde iniciar Claude

Onde você inicia claude determina quais arquivos Claude pode ler e editar sem uma concessão de permissão adicional, quais arquivos CLAUDE.md carregam no contexto na inicialização e quais configurações de projeto se aplicam.

Iniciar de Acesso a arquivos CLAUDE.md carregado na inicialização Use quando
Raiz do repositório Cada arquivo Apenas raiz; arquivos de subdiretório carregam sob demanda quando Claude lê lá Tarefas abrangem múltiplos pacotes ou subsistemas
Um subdiretório Apenas essa subárvore, até você conceder mais Desse diretório mais cada ancestral O trabalho é escopo de um pacote ou subsistema

As configurações de projeto em .claude/settings.json carregam apenas do seu diretório inicial e não são herdadas de diretórios pai da maneira que os arquivos CLAUDE.md são: um .claude/settings.json na raiz do repositório se aplica apenas quando você inicia da raiz.

Cada seção abaixo afirma se seu arquivo de configurações pertence à raiz do repositório ou ao subdiretório do qual você inicia, e se é confirmado ou mantido localmente.

Camadas de arquivos CLAUDE.md por diretório

Em uma grande base de código, um único CLAUDE.md na raiz do repositório tende a crescer para cobrir as convenções de cada subsistema, custando contexto em instruções não relacionadas à tarefa atual, ou permanecer muito genérico para ser útil. Dividir instruções entre arquivos por diretório significa que Claude carrega regras em toda a repositório mais apenas as convenções para o código em que você está trabalhando.

Claude Code carrega cada arquivo CLAUDE.md do seu diretório de trabalho e cada diretório pai na inicialização, depois carrega o arquivo de cada subdiretório sob demanda quando lê arquivos lá. Um arquivo raiz define regras em toda a repositório e cada subdiretório adiciona a sua própria.

Uma divisão comum é dois níveis:

  • CLAUDE.md raiz: instruções que se aplicam em todos os lugares, como padrões de codificação, convenções de commit e layout de repositório
  • CLAUDE.md por subdiretório: convenções específicas da pilha dessa área. Em um monorepo é um por pacote. Em uma grande árvore única é um por subsistema como src/db/ ou src/api/

Confirme esses arquivos no repositório para que colegas de trabalho os herdem. O proprietário de cada diretório normalmente mantém seu arquivo.

O CLAUDE.md raiz orienta Claude para a estrutura do repositório:

Este é um monorepo com três pacotes sob packages/:

- packages/api: API REST Node.js com Express, TypeScript e PostgreSQL
- packages/web: frontend React com Vite, TypeScript e TailwindCSS
- packages/shared: utilitários TypeScript compartilhados usados por api e web

Execute comandos do diretório do pacote, não da raiz do monorepo.
Cada pacote tem seu próprio tsconfig.json, package.json e suite de testes.

O CLAUDE.md de cada subdiretório, aqui packages/api/CLAUDE.md, adiciona contexto específico da pilha dessa área:

Este pacote é o servidor da API REST.

- Executar testes: `npm test` (usa Vitest)
- Executar servidor dev: `npm run dev` (porta 3001)
- Migrações de banco de dados: `npm run migrate`
- Variáveis de ambiente: copie `.env.example` para `.env`

As rotas da API estão em src/routes/. Cada arquivo de rota exporta um roteador Express.
As consultas de banco de dados usam Knex em src/db/. Nunca escreva strings SQL brutas em manipuladores de rota.

Quando você inicia Claude de packages/api/, ele carrega tanto packages/api/CLAUDE.md quanto o CLAUDE.md raiz. Claude vê as instruções locais ao lado das regras em toda a repositório, sem instruções de packages/web/ no contexto. O mesmo vale para qualquer subdiretório em uma árvore não-monorepo.

Algumas maneiras de manter os arquivos atualizados conforme a base de código e os modelos mudam:

  • Revisar em pull requests: trate edições CLAUDE.md como qualquer outra mudança de documentação para que as convenções rastreiem o código
  • Revisitar após lançamentos de modelo principais: instruções que funcionavam em torno de uma limitação de um modelo mais antigo podem se tornar sobrecarga uma vez que um modelo mais novo lida com o caso por conta própria. Por exemplo, uma regra que força refatorações de arquivo único pode ser deletada uma vez que a limitação se foi
  • Adicionar um hook Stop que propõe atualizações: um Stop hook recebe o caminho para a transcrição da sessão quando Claude termina de responder, então um script pode revisar a sessão e propor atualizações CLAUDE.md enquanto a lacuna que expôs é fresca

Para mais sobre como os arquivos CLAUDE.md carregam e interagem, veja Memória e instruções de projeto.

Escolha entre CLAUDE.md por diretório e regras com escopo de caminho

Arquivos CLAUDE.md por diretório e regras com escopo de caminho sob .claude/rules/ ambos deixam você direcionar instruções para parte da árvore. Eles diferem em onde o arquivo vive e quando carrega.

Abordagem Localização do arquivo Carrega quando Use quando
CLAUDE.md por diretório Dentro do diretório, ao lado de seu código Na inicialização quando iniciado desse diretório, ou sob demanda quando Claude lê um arquivo lá Proprietários de diretório mantêm suas próprias convenções; instruções são versionadas com o código
Regra com escopo de caminho em .claude/rules/ .claude/ central na raiz do repo Quando Claude trabalha com um arquivo correspondendo ao glob paths: da regra Você quer todas as convenções em um lugar, ou a mesma regra se aplica a muitos caminhos espalhados

Para uma comparação que também cobre skills, veja Comparar recursos similares.

Excluir arquivos CLAUDE.md irrelevantes

Quando você inicia Claude da raiz do repositório, o CLAUDE.md de cada subdiretório carrega assim que Claude lê um arquivo nesse diretório. A configuração claudeMdExcludes pula arquivos específicos por caminho ou padrão glob para que nunca carreguem.

Use isso para diretórios em que você nunca trabalha, como pacotes de outras equipes, código legado ou subárvores fornecidas. A lista de exclusão é estática, não um switch por tarefa. Para focar em um pacote hoje e outro amanhã, inicie Claude do diretório desse pacote em vez de editar exclusões.

Se você quer apenas essas exclusões para você, coloque a configuração em .claude/settings.local.json, que é gitignored e não confirmado. Os padrões usam sintaxe glob correspondida contra caminhos de arquivo absolutos, então comece padrões de estilo relativo com **/ para corresponder em qualquer lugar da árvore. O exemplo abaixo exclui pacotes pertencentes a outras equipes:

{
  "claudeMdExcludes": [
    "**/packages/admin-dashboard/**",
    "**/packages/legacy-*/**"
  ]
}

Isso pula cada CLAUDE.md e arquivo de regras sob esses pacotes. O CLAUDE.md raiz e os pacotes em que você trabalha ainda carregam normalmente.

Esses padrões cobrem outros casos comuns:

  • "**/packages/*/CLAUDE.md": exclui o CLAUDE.md de cada pacote enquanto mantém a raiz
  • "**/packages/web/**": exclui tudo sob o pacote web, incluindo regras
  • "/home/user/monorepo/legacy/CLAUDE.md": exclui um arquivo específico por caminho absoluto

Arquivos CLAUDE.md de política gerenciada não podem ser excluídos, então instruções em toda a organização sempre se aplicam. Você pode definir claudeMdExcludes em qualquer escopo de configurações: usuário, projeto, local ou gerenciado. Os arrays se mesclam entre escopos, então uma equipe pode definir padrões em nível de projeto enquanto indivíduos adicionam substituições locais.

Para a documentação completa de exclusão, veja Excluir arquivos CLAUDE.md específicos.

Reduza o que Claude lê

Instruções são apenas parte do que acaba no contexto do Claude. Leituras de arquivo são outro custo que cresce com a base de código. As configurações abaixo bloqueiam leituras de caminhos irrelevantes e substituem varreduras exaustivas por buscas de servidor de linguagem.

Bloqueie leituras de código gerado e fornecido

As buscas de conteúdo do Claude respeitam .gitignore por padrão, então caminhos já listados lá, como node_modules/, dist/ e build/, ficam fora dos resultados de busca sem configuração adicional.

Para caminhos que são verificados, como um SDK fornecido ou código gerado confirmado, adicione regras de negação Read em permissions.deny para bloquear Claude de abrir esses arquivos mesmo quando uma busca os lista.

Para aplicar essas exclusões para todos que trabalham no repositório, confirme-as em .claude/settings.json. Para mantê-las pessoais, use .claude/settings.local.json em vez disso. Como outras configurações de projeto nesta página, esses arquivos carregam apenas do seu diretório inicial. Coloque-os na raiz do repositório se você inicia Claude lá, ou em cada .claude/ do pacote se você inicia de subdiretórios. Para impor as mesmas regras de negação em cada sessão independentemente do diretório inicial, defina-as em configurações gerenciadas, que as configurações de usuário e projeto não podem substituir.

O exemplo abaixo bloqueia artefatos de compilação e um SDK fornecido:

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

As regras de negação cobrem as ferramentas de arquivo integradas do Claude e comandos Bash reconhecidos, incluindo cat, head, grep e find, quando um caminho negado é passado como argumento. Elas não filtram caminhos negados da saída de uma busca recursiva, e não cobrem subprocessos arbitrários que abrem arquivos por conta própria. Para a sintaxe de padrão completa, veja Regras de permissão Read e Edit.

Reduza leituras de arquivo com inteligência de código

Em uma grande base de código, encontrar onde um símbolo é definido ou usado pode custar muitas leituras de arquivo e chamadas grep. Plugins de inteligência de código conectam Claude a um servidor de linguagem para que ele possa pular para definições, encontrar referências e superfícies erros de tipo diretamente em vez de verificar a árvore.

O marketplace oficial tem plugins para TypeScript, Python, Go, Rust e outras linguagens comuns. O exemplo abaixo instala o plugin TypeScript:

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

Para habilitar um plugin para todos no repositório em vez de instalá-lo você mesmo, adicione-o à configuração de projeto enabledPlugins.

Os plugins de inteligência de código requerem o binário do servidor de linguagem da linguagem em cada máquina do desenvolvedor. Veja qual binário cada linguagem requer. Instalar do marketplace oficial requer acesso à rede para GitHub, onde o marketplace é hospedado. Em uma rede restrita, adicione o marketplace de um host Git interno ou caminho local em vez disso.

Isso funciona bem com claudeMdExcludes e as regras de negação Read acima. Aqueles mantêm conteúdo irrelevante fora do contexto, e inteligência de código mantém Claude de ler através do que permanece para localizar uma definição.

Escopo worktrees e acesso a arquivos

Essas configurações controlam o que está no disco em worktrees e quais diretórios Claude pode ler e escrever além do seu ponto inicial.

Verifique apenas os diretórios que você precisa

A flag --worktree inicia uma sessão em um novo git worktree para que as mudanças fiquem isoladas do seu checkout principal. Por padrão, ela verifica todo o repositório. Em um repositório grande, a configuração worktree.sparsePaths usa git sparse-checkout para escrever apenas os diretórios listados mais arquivos em nível raiz no disco, para que worktrees iniciem mais rápido e usem menos espaço.

Se todos que trabalham neste diretório precisam dos mesmos caminhos, confirme a configuração em .claude/settings.json. Para adicionar caminhos para você, use .claude/settings.local.json: as listas se mesclam entre escopos, então um arquivo local pode adicionar caminhos à lista confirmada mas não removê-los. O exemplo abaixo mostra o arquivo confirmado:

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

Quando Claude cria um worktree, ele verifica apenas .claude/, packages/api/ e packages/shared/ em vez da árvore completa. Os caminhos em sparsePaths são relativos à raiz do repositório, independentemente de qual subdiretório você inicia Claude. Qualquer caminho de diretório funciona aqui, não apenas raízes de pacote.

Isso é particularmente útil para isolamento de worktree de subagente. Subagentes são instâncias Claude paralelas geradas para subtarefas, e cada uma que executa em um worktree obtém um checkout leve em vez da árvore completa. Todos os worktrees em uma sessão compartilham o mesmo sparsePaths, então se um subagente precisa de packages/api/ e outro precisa de packages/web/, liste ambos.

Liste diretórios em sparsePaths, não arquivos individuais. Arquivos em nível raiz como package.json, tsconfig.base.json e arquivos de lock são sempre verificados ao lado dos diretórios que você lista. Diretórios em nível raiz não são, então inclua .claude na lista se você quer o .claude/settings.json, .claude/rules/ ou .claude/skills/ da raiz do repositório disponível dentro do worktree.

Para evitar duplicar diretórios grandes como node_modules entre worktrees, emparelhe sparsePaths com symlinkDirectories no mesmo .claude/settings.json:

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

Isso cria um symlink do node_modules/ de cada worktree de volta para a cópia do repositório principal em vez de duplicá-lo no disco.

Para a referência completa de configurações de worktree, veja Configurações de Worktree.

Conceda acesso entre pacotes ou repositórios

Esta seção se aplica quando você inicia Claude de um subdiretório, ou quando uma tarefa abrange múltiplos checkouts. Se você inicia da raiz do repositório em uma grande árvore única, Claude já tem acesso a cada arquivo e você pode pular isso.

Quando você inicia Claude de packages/api/, ele pode ler e escrever arquivos dentro desse diretório. Se uma tarefa requer mudanças entre pacotes, como atualizar um tipo compartilhado que tanto api quanto web importam, você precisa conceder acesso ao diretório irmão. O mesmo mecanismo concede acesso a um repositório separadamente verificado.

A configuração additionalDirectories em .claude/settings.json dá ao Claude acesso a diretórios fora do diretório de trabalho. O exemplo abaixo concede acesso a dois pacotes irmãos:

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

Os caminhos relativos resolvem contra o diretório do qual você inicia Claude. Com essa configuração, Claude pode ler e editar arquivos em packages/shared/ e packages/web/ enquanto trabalha de packages/api/.

Você também pode conceder acesso em tempo de execução sem editar configurações passando --add-dir quando você inicia Claude:

claude --add-dir ../shared

Porém você adicione um diretório, Claude pode ler e editar arquivos nele. Se o CLAUDE.md do diretório, arquivos .claude/rules/ e skills também carregam depende de como você o adicionou:

Adicionado com Carrega CLAUDE.md e regras Carrega skills
Configuração additionalDirectories Nunca Nunca
Flag --add-dir ou comando /add-dir Apenas com a variável de ambiente abaixo Sim

Para carregar arquivos CLAUDE.md e regras de um diretório adicionado com --add-dir ou /add-dir, defina a variável de ambiente CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:

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

A variável de ambiente não tem efeito em diretórios listados na configuração additionalDirectories. Veja Carregar de diretórios adicionais para detalhes.

Para diretórios irmãos que todos nesta área precisam, confirme additionalDirectories em .claude/settings.json. Para uma seleção pessoal ou acesso único, use .claude/settings.local.json ou passe --add-dir na inicialização.

Adicione skills por diretório

Qualquer subdiretório pode definir skills escopo para sua própria pilha. Uma skill carrega sob demanda quando Claude determina que é relevante, então ferramentas específicas da API não consomem contexto durante trabalho frontend.

As skills vivem sob .claude/skills/ dentro do diretório. Confirme-as ao lado do código dessa área para que qualquer um que clone o repositório as obtenha. Em um monorepo isso pode ser um conjunto de skills por pacote. Em uma grande base de código de árvore única é um conjunto por subsistema como src/db/.claude/skills/.

Crie um diretório de skill dentro do subdiretório:

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

Então escreva SKILL.md dentro desse diretório, aqui packages/api/.claude/skills/api-testing/SKILL.md. Este exemplo ensina ao Claude os padrões de teste do pacote API:

---
name: api-testing
description: Padrões de teste para o pacote API. Use ao escrever ou modificar testes em packages/api/.
---

## Estrutura de teste

Os testes estão em `src/__tests__/` espelhando a estrutura do diretório `src/`.
Cada arquivo de rota tem um arquivo `.test.ts` correspondente.

## Executando testes

- Todos os testes: `npm test`
- Arquivo único: `npm test -- src/__tests__/routes/users.test.ts`
- Modo watch: `npm test -- --watch`

## Utilitários de teste

- `src/__tests__/helpers/db.ts`: fornece `setupTestDb()` e `teardownTestDb()` para testes de banco de dados
- `src/__tests__/helpers/auth.ts`: fornece `createTestUser()` e `getAuthToken()` para endpoints autenticados

## Padrões

- Use `supertest` para asserções HTTP, não fetch bruto
- Sempre envolva testes de banco de dados em uma transação que reverte
- Mock de serviços externos em `src/__tests__/mocks/`

Um subdiretório diferente mantém diferentes skills da mesma maneira: packages/web/.claude/skills/component-patterns/ descreve as convenções de componente do frontend em vez de teste. Quando Claude trabalha em um arquivo em packages/api/, ele carrega a skill api-testing. Quando trabalha em packages/web/, carrega component-patterns em vez disso. As skills de nenhum diretório carregam durante as tarefas do outro.

Você também pode escopar uma skill por padrão de arquivo em vez de por colocação. O campo frontmatter paths leva padrões glob, e Claude carrega a skill automaticamente apenas quando trabalha com arquivos correspondentes. Use isso para uma skill que vive no .claude/skills/ da raiz do repositório mas se aplica apenas a certos arquivos onde quer que apareçam, como uma skill de migração de banco de dados escopo para **/migrations/**.

Para mais sobre criar e organizar skills, veja Skills.

Mantenha skills descobríveis

Com skills espalhadas por muitos diretórios, a lista da qual Claude escolhe pode crescer grande. Claude escolhe uma skill lendo o nome e descrição de cada skill descoberta, e apenas o conteúdo completo da skill escolhida carrega no contexto. Esta seção cobre como manter essa lista pequena e escrever descrições que sobrevivem ao encurtamento.

Quais skills estão em escopo depende de onde você inicia Claude:

  • De um subdiretório como packages/api/: skills desse diretório, cada pai até a raiz do repositório, e os níveis de usuário e empresa
  • Da raiz do repositório: skills de cada subdiretório que Claude toca durante a sessão, que pode acumular em centenas
  • Depois de adicionar um irmão com --add-dir: as skills desse irmão também carregam. A configuração additionalDirectories concede apenas acesso a arquivo e não carrega skills

Os nomes sempre carregam, mas descrições são encurtadas quando há muitas, que pode remover as palavras-chave que Claude usa para decidir se uma skill se aplica. Mantenha descrições curtas e comece com palavras que uma solicitação conteria, como "escrevendo ou modificando testes em packages/api/".

Para skills que muitos diretórios compartilham, como convenções de PR ou uma checklist de deploy, coloque-as no .claude/skills/ da raiz do repositório para que carreguem de qualquer diretório inicial. Quando skills compartilhadas precisam de seu próprio histórico de versão ou devem funcionar entre repositórios, empacote-as como um plugin em vez disso. As skills de plugin usam um namespace plugin-name:skill-name, então nunca colidem com skills por diretório. Uma equipe de plataforma pode versioná-las e atualizá-las em um lugar.

Para encontrar quais skills vão não utilizadas, habilite o exportador OpenTelemetry logs e defina OTEL_LOG_TOOL_DETAILS=1 para que nomes de skill sejam registrados verbatim em vez de redacted. O evento skill_activated registra cada invocação em seu atributo skill.name, e invocation_trigger registra se um comando, Claude ou uma skill aninhada o invocou, que te diz o que consolidar ou aposentar.

Centralize convenções quando camadas param de escalar

Arquivos CLAUDE.md por diretório podem se tornar difíceis de governar conforme a base de código cresce. As convenções derivam, os arquivos ficam obsoletos, e ninguém possui a raiz. Resolver isso tipicamente cai para a equipe que mantém a configuração Claude Code do repositório em vez de para cada desenvolvedor trabalhando em sua própria área.

Mova convenções e conteúdo de referência para fora de CLAUDE.md sempre carregado e para mecanismos que carregam sob demanda:

  • Skills: material de referência que Claude carrega apenas quando relevante para a tarefa
  • Plugins: pacotes versionados de skills, hooks e comandos que uma equipe de plataforma possui centralmente
  • Servidores MCP: se sua organização já executa uma busca de código ou índice RAG sobre o repositório, exponha-o como uma ferramenta MCP para que Claude a consulte em vez de ler arquivos diretamente

Veja configurações gerenciadas por servidor ou endpoint para como equipes de plataforma podem impor essas centralmente.

Recomende o plugin certo na inicialização da sessão

Uma vez que convenções vivem em plugins, um colega iniciando Claude em uma parte desconhecida da árvore não tem sinal sobre qual plugin os proprietários dessa área mantêm. Um SessionStart hook pode fechar essa lacuna, já que qualquer coisa que o hook imprime para stdout é adicionada ao contexto do Claude antes do primeiro prompt.

Por exemplo, você pode escrever um script que lê o diretório de inicialização da entrada do hook, o procura em um mapa de caminho para plugin confirmado no repositório, e imprime a recomendação para Claude retransmitir em sua primeira resposta. Veja Automatize ações com hooks para escrever e registrar o hook.

Junte tudo

A configuração combinada abaixo usa o layout do monorepo. Os mesmos arquivos funcionam para qualquer subdiretório em uma grande árvore única. As configurações de projeto carregam apenas do diretório do qual você inicia Claude, então o .claude/settings.json de cada subdiretório deve ser autossuficiente em vez de em camadas em um arquivo raiz.

O exemplo confirma worktree, additionalDirectories e as regras de negação Read em .claude/settings.json para que cada desenvolvedor em packages/api/ obtenha o mesmo acesso irmão, caminhos esparsos e exclusões. O arquivo abaixo é as configurações por área confirmadas para packages/api/:

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

Porque essa sessão inicia de packages/api/, os arquivos CLAUDE.md de pacotes irmãos já estão fora de escopo, então claudeMdExcludes não é necessário aqui. Adicione-o ao .claude/settings.local.json da raiz do repositório em vez disso se você também inicia sessões da raiz.

A entrada additionalDirectories se aplica quando você inicia Claude de packages/api/ diretamente. Dentro de um worktree criado dessa sessão, o diretório de trabalho é a raiz do worktree, então esse arquivo de configurações não carrega. Os pacotes irmãos já são alcançáveis dentro do worktree sem ele, mas as regras de negação precisam de uma segunda cópia no .claude/settings.json da raiz do repositório para que sessões de worktree as peguem, como a nota de configurações de worktree descreve:

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

Após a configuração, o repositório tem esse layout:

monorepo/
  CLAUDE.md
  .claude/settings.json                           # regras de negação para sessões de worktree
  packages/
    api/
      CLAUDE.md
      .claude/settings.json                       # worktree, additionalDirectories, regras de negação
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

Com essa configuração, iniciando Claude de packages/api/:

  • Carrega o CLAUDE.md raiz e packages/api/CLAUDE.md, pula packages/web/CLAUDE.md
  • Pode ler e editar arquivos em packages/api/ e packages/shared/
  • Pula leituras de saída de compilação sob dist/ e build/ em packages/api/
  • Tem a skill api-testing disponível sob demanda
  • Cria worktrees contendo .claude/, packages/api/, packages/shared/ e arquivos em nível raiz, com as regras de negação aplicadas através do worktree do arquivo de configurações raiz

Escopo e plano de mudanças que abrangem pacotes

A configuração acima controla o que Claude vê. Quando uma única mudança toca vários pacotes, como atualizar um tipo compartilhado junto com cada site de chamada que o usa, como você escopeia e sequencia a tarefa também afeta o resultado.

Duas técnicas ajudam a manter uma mudança entre pacotes consistente:

  • Dê ao Claude a mudança inteira em uma sessão: entregar a edição compartilhada e seus sites de chamada juntos mantém as decisões atrás de cada edição consistentes, em vez de re-derivá-las por pacote
  • Salve o plano em um arquivo antes de editar: planeje primeiro e peça ao Claude para escrever o plano em um arquivo markdown no repositório. Uma longa sessão entre pacotes compacta seu contexto ao longo do caminho, e o plano salvo sobrevive onde o histórico de conversa pode não

Próximos passos

Uma vez que essa configuração está em lugar, você pode refiná-la:

  • Use hooks para executar linters ou verificadores de tipo por diretório após Claude editar arquivos
  • Revise Gerencie custos efetivamente para entender como o tamanho da base de código afeta o uso de tokens e como definir limites de gastos antes de um rollout mais amplo
  • Leia Como Claude Code funciona em grandes bases de código no blog Claude para padrões de rollout organizacional e modelos de propriedade que ficam acima da configuração por repositório nesta página