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.

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.

As configurações de projeto em .claude/settings.json não são herdadas de diretórios pai da maneira que os arquivos CLAUDE.md são. Para saber qual diretório .claude/settings.json uma sessão lê, consulte onde Claude Code procura por cada arquivo.

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 e convenções de commit
• 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.

Para aparar um arquivo que já está verificado, execute o checkup /doctor. O CLAUDE.md raiz contém as regras que se aplicam em cada pacote:

Execute scripts de pacote do diretório do pacote, não da raiz do monorepo.
Prefixe assuntos de commit com o nome do pacote, por exemplo `api: add rate limiting`.
Nunca edite arquivos sob packages/*/generated/. Execute `npm run codegen` no pacote em vez disso.

O CLAUDE.md de cada subdiretório, aqui packages/api/CLAUDE.md, adiciona as convenções específicas dessa área:

Copie `.env.example` para `.env` antes de executar qualquer coisa. Testes e o servidor dev falham sem ele.
Escreva consultas de banco de dados com o construtor de consultas Knex. Nunca coloque strings SQL brutas em manipuladores de rota.
Nunca edite uma migração depois que ela foi mesclada. Adicione uma nova migração em vez disso.

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. Para confirmar quais arquivos carregaram, execute /context e verifique a lista sob Memory files.

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.

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, cada CLAUDE.md de 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. Claude Code adiciona esse arquivo ao seu gitignore global quando salva uma configuração lá. Como você está criando manualmente aqui, adicione-o ao seu gitignore você mesmo. 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 um pacote pertencente a outra equipe:

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

Isso pula cada CLAUDE.md e arquivo de regras sob esse pacote. 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/legacy-*/**": exclui cada pacote cujo nome corresponde ao glob, 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ê

As instruções são apenas parte do que acaba no contexto do Claude. As 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 de arquivos por pesquisas de servidor de linguagem.

Bloqueie leituras de código gerado e fornecido

As pesquisas de conteúdo do Claude respeitam .gitignore por padrão, portanto, caminhos já listados lá, como node_modules/, dist/ e build/, ficam fora dos resultados de pesquisa 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 impedir que Claude abra esses arquivos.

As regras de negação podem cobrir todos que trabalham no repositório, apenas você ou cada sessão na máquina, dependendo de qual arquivo de configurações você as colocar:

• Todos que trabalham no repositório: confirme as regras em .claude/settings.json, na raiz do repositório se você iniciar o Claude lá, ou em cada .claude/ do pacote se você iniciar a partir de subdiretórios. Como outras configurações de projeto nesta página, esse arquivo não é herdado de diretórios pai.
• Apenas você: use .claude/settings.local.json na raiz do repositório, que carrega em cada sessão CLI dentro do repositório independentemente do diretório inicial, exceto nos casos em que Claude Code não usa a raiz do repositório, como no Windows. Padrões relativos como o Read(./**/vendor/**/*) do exemplo ainda ancoram no diretório de trabalho atual da sessão em vez da raiz do repositório, portanto, se você iniciar sessões a partir de subdiretórios, escreva as regras neste arquivo como caminhos absolutos //, como Read(//absolute/path/to/repo/**/vendor/**/*). Antes da v2.1.211, .claude/settings.local.json também carregava apenas a partir do diretório inicial.
• Todos, aplicado em cada sessão: defina as regras 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. Seus padrões de diretório terminam com /**/* em vez de /** para que cada regra cubra tudo dentro do diretório, mas não o próprio diretório. Claude pode então ainda listar esses diretórios ou entrar neles, por exemplo com ls dist ou cd build.

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

As regras de negação cobrem as ferramentas de arquivo integradas do Claude. Em Bash, elas cobrem os comandos de arquivo que Claude Code reconhece, como cat, head, grep e find, quando um caminho negado aparece como um argumento, e o alvo de um redirecionamento como < file. Claude Code também faz uma tentativa de melhor esforço para manter caminhos negados fora dos resultados das ferramentas Grep e Glob integradas. Uma pesquisa Bash como grep -r ou find em um diretório que contém arquivos negados ainda os inclui em sua saída.

As regras de negação não cobrem subprocessos que abrem arquivos por conta própria. Para a sintaxe de padrão completa, consulte Regras de permissão Read e Edit.

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

Em uma base de código grande, 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 exibir erros de tipo diretamente em vez de varrer a árvore.

O marketplace oficial tem plugins para TypeScript, Python, Go, Rust e outras linguagens comuns. Execute o comando abaixo dentro de uma sessão Claude Code para instalar o plugin TypeScript:

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

Se a instalação falhar, corresponda à mensagem que Claude Code relata:

• Marketplace "claude-plugins-official" not found: adicione o marketplace com /plugin marketplace add anthropics/claude-plugins-official, depois tente novamente a instalação.
• O plugin não foi encontrado no marketplace: verifique o nome do plugin.

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 exigem o binário do servidor de linguagem da linguagem em cada máquina do desenvolvedor. Veja qual binário cada linguagem exige. A instalação 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 a inteligência de código impede que Claude leia o que permanece para localizar uma definição.

Escopo de 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 de partida.

Faça checkout apenas dos diretórios que você precisa

A flag --worktree inicia uma sessão em uma nova git worktree para que as alterações fiquem isoladas do seu checkout principal. Por padrão, ela faz checkout de 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 no nível raiz no disco, para que worktrees iniciem mais rapidamente 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ê mesmo, 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.

Os exemplos JSON nesta página mostram uma configuração por vez. Se seu .claude/settings.json já contiver outras chaves, como as regras permissions.deny acima, adicione a chave worktree ao lado delas em vez de substituir o arquivo. Coloque tudo junto mostra o resultado combinado.

O exemplo abaixo mostra o arquivo confirmado:

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

Quando Claude cria uma worktree, ele faz checkout apenas de .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 pacotes.

Isso é particularmente útil para isolamento de worktree de subagentes. Subagentes são instâncias paralelas de Claude geradas para subtarefas, e cada uma que é executada em uma worktree obtém um checkout leve em vez da árvore completa. Todas as 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 no nível raiz como package.json, tsconfig.base.json e arquivos de lock são sempre feitos checkout ao lado dos diretórios que você lista. Diretórios no nível raiz não são, então inclua .claude na lista se você quiser que o .claude/settings.json da raiz do repositório ou .claude/rules/ estejam disponíveis dentro da worktree. Para skills de projeto, agentes e comandos, veja O que worktrees compartilham com o checkout principal.

O sparse checkout requer que o git habilite extensions.worktreeConfig no .git/config compartilhado do repositório enquanto uma worktree esparsa existe. Claude Code remove essa entrada após a última worktree ser removida, mas apenas se Claude Code a adicionou. Nunca remove um valor que você definiu você mesmo. Antes da v2.1.207, a entrada permanecia após a última worktree ser removida, e ferramentas baseadas em go-git como tea falhavam ao abrir o repositório até que você executasse git config --unset extensions.worktreeConfig.

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

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

Isso cria um symlink de cada node_modules/ da 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ê iniciar da raiz do repositório em uma única árvore grande, Claude já tem acesso a todos os arquivos 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 alterações 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á a 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 são resolvidos em relação ao 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:

Para carregar arquivos CLAUDE.md e rules 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 no lançamento.

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.

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 raiz, mais 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 quando há muitas, algumas skills perdem suas descrições inteiramente, 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 Claude Code adiciona texto simples que o hook imprime para stdout 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. 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
• Planeje antes de editar: planeje primeiro em plan mode, e Claude escreve o plano em um arquivo. Uma longa sessão entre pacotes compacta seu contexto ao longo do caminho. Claude Code reinjecta o arquivo de plano após cada compactação, então o plano 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