Claude Code em monorepos pode se desviar quando o repositório é enorme. Aprenda sobre limites, resumos locais e fluxos repetíveis para manter as respostas precisas.
Claude Code em monorepos pode parecer imprevisível por um motivo simples: o repositório é maior do que o que o modelo consegue manter na memória de trabalho de uma vez.
“Contexto” é o conjunto de arquivos, trechos, anotações e instruções que o Claude recebeu para essa tarefa, além do que ele pode inferir a partir deles. Quando detalhes-chave estão faltando, o Claude preenche lacunas com suposições. Em um repositório grande, isso acontece com mais frequência.
Três modos de falha aparecem repetidas vezes:
Primeiro, arquivos perdidos. Uma alteração que parece segura em uma pasta na verdade depende de um tipo compartilhado, de uma regra de configuração ou de um passo de build definido em outro lugar. Se essa dependência não está no contexto, o Claude pode editar a coisa errada com confiança ou parar cedo porque não vê a verdadeira fonte da verdade.
Segundo, similaridade falsa. Monorepos frequentemente contêm vários pacotes que se parecem: dois módulos de auth, três clients de API ou várias apps React com estruturas de pastas semelhantes. O Claude pode misturar padrões entre eles, atualizar um helper no pacote errado ou importar do nome de módulo “quase certo”.
Terceiro, descompasso temporal. Grandes bases de código geralmente têm formas antigas e novas de fazer a mesma coisa. Se o Claude só vê arquivos mais antigos, ele pode copiar padrões obsoletos (opções de configuração depreciadas, APIs legadas) mesmo que a equipe já tenha migrado.
Um exemplo comum no mundo real: você pede uma pequena mudança na UI de cobrança, e o Claude edita um componente payments compartilhado usado por outras apps porque nunca viu o wrapper específico da app que deveria ter sido alterado.
O objetivo não é mostrar ao Claude o monorepo inteiro. O objetivo é fornecer entradas menores e deliberadas que respondam à pergunta: o pacote que você está alterando, suas dependências diretas e uma ou duas “fontes da verdade” para tipos e configuração. Também indique áreas de “não tocar” (outras apps, infra, código gerado) e confirme qual pacote é o dono do comportamento.
A precisão depende menos de quanto código você cola e mais de quão claramente você descreve o trabalho.
Comece pelo resultado que você quer: um conserto específico, um refactor ou uma resposta. Uma “pergunta sobre o código” pode ficar em alto nível. Um pedido de “fazer uma mudança” precisa de limites, entradas e checagens de sucesso.
Antes de compartilhar qualquer coisa, escreva uma frase que termine esta expressão: “Depois que você terminar, eu devo ser capaz de…”. Por exemplo: “rodar os testes unitários do pacote X sem falhas” ou “ver o novo campo na resposta da API para o endpoint Y.” Essa frase vira a estrela guia quando o repositório é enorme.
Para mudanças, compartilhe o menor conjunto de artefatos que possa provar que a alteração está correta: o(s) ponto(s) de entrada, os tipos/interfaces ou schema relevantes, um teste que falha ou um passo de repro com o resultado esperado, e qualquer configuração que afete esse caminho (rotas, feature flags, build ou regras de lint). Se ajudar, adicione um pequeno mapa de pastas do pacote para que o Claude entenda o propósito de cada diretório.
Seja explícito sobre o que não olhar. Diga: “Ignore arquivos gerados, pastas vendor, outputs de build, snapshots e lockfiles, a menos que eu peça.” Isso evita tempo perdido e edições em locais que você não vai revisar.
Também defina expectativas para incertezas. Peça ao Claude que sinalize suposições e desconhecidos em vez de chutar. Por exemplo: “Se você não consegue ver onde essa função é chamada, diga isso e proponha 2 maneiras de localizá-la.”
Em um monorepo grande, a precisão cai quando o modelo começa a “ajudar” puxando código próximo que não faz parte da tarefa. A correção é direta: defina o que está dentro do escopo e o que está fora antes de pedir mudanças.
Comece com um limite que corresponda à organização do repositório: um pacote, um serviço, uma app ou uma biblioteca compartilhada. Se a mudança é “atualizar a UI de checkout”, o limite provavelmente é um pacote de app, não todos os lugares onde a palavra “checkout” aparece.
Sinais que ajudam o Claude a se manter no lugar incluem convenções de pastas (apps/, services/, packages/, libs/), manifests de pacotes (exports e dependências), pontos de entrada públicos (arquivos index, componentes/handlers exportados) e testes (eles frequentemente revelam a superfície pretendida). Um README dentro da pasta pode ser o marcador de limite mais rápido.
Limites funcionam melhor quando você nomeia as pontes entre eles. Aponte as interfaces específicas que o Claude pode tocar e trate todo o resto como fora dos limites. Pontes típicas são contratos de API HTTP, tópicos e payloads de eventos, tipos compartilhados ou um pequeno conjunto de funções exportadas.
Também nomeie zonas de “não tocar” sempre que a mudança não deva afetá-las. Comuns são configs de infraestrutura e deploy, lógica de segurança e auth, faturamento e pagamentos, migrações de dados e schemas de produção, e bibliotecas compartilhadas usadas por muitas equipes.
Um detalhe concreto do prompt que ajuda:
“Faça mudanças apenas dentro de packages/cart/ e seus testes. Você pode ler tipos compartilhados em packages/types/ mas não os modifique. Não edite infra, auth ou billing.”
A precisão melhora quando você fornece um pequeno e estável mapa da área que quer mudar. Um “resumo local” é esse mapa: curto o suficiente para ler rápido, específico o bastante para evitar suposições.
Mantenha cada resumo com cerca de 10 a 20 linhas. Escreva como se estivesse entregando o código a um novo colega que só precisa mexer nesse limite, não no repositório inteiro. Use linguagem simples e nomes reais do código: pastas, pacotes, funções exportadas.
Um resumo local útil responde cinco perguntas:
Adicione uma linha “gotchas”. É aí que você evita erros caros: cache oculto, feature flags, passos de migração e qualquer coisa que quebre silenciosamente.
Aqui está um template compacto que você pode copiar:
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>
Exemplo: se você está editando um pacote de billing, anote a função exata que cria invoices, os nomes das tabelas que ela escreve e a regra para erros re-tentáveis. Assim o Claude pode focar naquele limite em vez de vaguear por auth compartilhado, config ou pacotes não relacionados.
O melhor resumo é aquele que o Claude vê quando precisa. Coloque-o ao lado do código que descreve para que seja difícil ignorar e fácil atualizar. Por exemplo, mantenha um SUMMARY.md curto (ou uma seção no README.md) dentro de cada pasta de pacote, serviço ou app em vez de um documento gigante na raiz.
Uma estrutura simples e repetível ajuda. Mantenha-o curto o suficiente para que as pessoas o mantenham:
YYYY-MM-DD - <o que mudou em uma frase>Resumos ficam desatualizados por motivos previsíveis. Trate atualizações como se fosse atualizar uma definição de tipo: parte de terminar o trabalho, não uma tarefa separada.
Atualize o resumo quando um refactor mudar estrutura ou nomes, um novo módulo virar a principal forma de fazer algo, uma API/event/schema mudar (mesmo que os testes ainda passem), limites entre pacotes mudarem, ou uma dependência for removida/substituída.
Um hábito prático: quando você mergear uma mudança, adicione uma linha “Last updated” dizendo o que mudou. Ferramentas como Koder.ai podem ajudar a acelerar a mudança de código, mas o resumo é o que mantém mudanças futuras precisas.
A precisão muitas vezes depende de como você paceia a conversa. Faça o Claude ganhar contexto em pequenos pedaços em vez de chutar a partir de um snapshot enorme.
Antes de qualquer edição, peça ao Claude que descreva o que ele vê e o que precisa. Um bom mapa é curto: pacotes chave envolvidos, ponto de entrada do fluxo e onde estão testes ou tipos.
Prompt:
“Crie um mapa desta mudança: pacotes envolvidos, fluxo principal e pontos prováveis a tocar. Não proponha código ainda.”
Escolha uma fatia estreita: uma feature, um pacote, um fluxo de usuário. Declare o limite claramente (por exemplo: “Altere apenas packages/billing-api. Não toque em shared-ui ou infra.”).
Um workflow que mantém você no controle:
Se o Claude estiver faltando algo, ele deve dizer. Peça que escreva: (1) suposições que está fazendo, (2) o que falsificaria essas suposições e (3) os próximos arquivos necessários para confirmar.
Exemplo: você precisa adicionar um campo à resposta Invoice em um pacote. O Claude pede o handler, o DTO/definição de tipo e um teste. Você compartilha apenas esses. Se estiver usando um builder baseado em chat como Koder.ai, a mesma regra vale: forneça o menor conjunto de arquivos fonte, então expanda só quando realmente necessário.
Sua melhor defesa contra edições erradas é um pequeno “contrato” escrito no prompt: o que o Claude pode tocar, como você vai julgar o sucesso e quais regras ele deve seguir.
Comece com um limite fácil de obedecer e verificar. Seja explícito sobre onde edições são permitidas e nomeie zonas de “não tocar” para não haver tentação de vaguear.
Template de contrato:
packages/payments/.packages/auth/, infra/ ou configs compartilhadas.Depois, defina checagens de aceitação. Sem elas, o Claude pode produzir código que parece certo mas quebra regras reais do repositório.
Restrições de estilo importam também. Diga quais padrões seguir e quais evitar, com base no que sua base de código já faz. Por exemplo: “Use os helpers de erro existentes neste pacote; não adicione dependências; mantenha nomes de função em camelCase; não introduza uma nova camada de arquitetura.”
Por fim, exija um plano curto antes de qualquer edição:
“Antes de editar, liste os 3–5 arquivos que espera tocar e a mudança exata de comportamento. Aguarde aprovação.”
Exemplo:
“Corrigir arredondamento nos totais da invoice. Edite apenas packages/billing/src/ e testes em packages/billing/test/. Aceitação: pnpm -C packages/billing test e typecheck. Siga os utils de money existentes; não reescreva os tipos da API. Forneça um plano em 4 passos primeiro.”
A forma mais rápida de conseguir edições erradas em um monorepo é dar muito contexto de uma vez. Quando você cola um monte de código, ele frequentemente recorre a padrões genéricos em vez do design específico que seu repositório já usa.
Outra armadilha é deixá-lo chutar a arquitetura. Se você não mostra pontos de entrada reais, ele pode escolher o primeiro arquivo que parece plausível e conectar a lógica ali. Na prática, a precisão vem de um pequeno conjunto de arquivos “fonte da verdade” (módulos de entrada, routers, registradores de serviços, docs de boundary do pacote). Se esses não estiverem no contexto, o modelo preenche lacunas.
Nomes também podem enganar. Monorepos frequentemente têm pacotes como ui, ui-kit, shared-ui, ou helpers duplicados como date.ts em dois lugares. Se você misturar trechos de ambos, o Claude pode aplicar patch em um arquivo enquanto raciocina sobre o outro. Exemplo: você pede para alterar o estilo de um botão, ele edita packages/ui/Button.tsx, mas a app importa packages/ui-kit/Button.tsx. O diff parece correto, mas nada muda em produção.
Config também é uma fonte de desvio silencioso. O comportamento pode depender de variáveis de ambiente, feature flags, settings de build ou tooling do workspace. Se você não mencionar isso, o Claude pode remover uma checagem “estranha” que só importa quando uma flag está ativa, ou adicionar código que quebra um passo de build.
Sinais de alerta de que você está desviando:
Trate imports entre pacotes como uma decisão, não um padrão. Mantenha edições locais a menos que você realmente expanda o escopo intencionalmente.
A maneira mais rápida de obter edições corretas é começar com limites, não com volume. Um bom prompt é um pouco rígido: diz ao Claude onde olhar, o que ignorar e o que significa “pronto”.
Antes de colar código, escreva um prefácio curto que prenda o trabalho a um lugar no repositório. Nomeie o pacote, a pasta exata e o objetivo específico. Então inclua um resumo local (propósito, dependências chave, convenções importantes) e o arquivo de entrada que ancora a mudança.
Checklist:
<package>/<path>. Objetivo: <uma frase>. Ignore todo o resto a menos que solicitado.<5-10 linhas>. Arquivo de entrada: <path/to/file>.<...>. Não mudar: <pastas/arquivos ou APIs>. Manter comportamento: <o que deve continuar verdadeiro>.Se o Claude propor mudanças fora do seu limite, trate isso como um sinal: ou torne o prompt mais rígido, ou expanda o limite de propósito e reitere claramente.
Suponha que seu monorepo tenha apps/web-store (uma app React) e packages/ui-kit (botões, inputs e estilos compartilhados). Você quer uma pequena feature: adicionar um botão “Salvar para mais tarde” na página do carrinho, usando um novo SaveIcon do ui-kit. Nada mais deve mudar.
Antes de pedir edições, crie dois resumos locais que atuem como limites. Mantenha-os curtos, específicos e opinativos sobre o que importa.
# 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
Depois mantenha o loop apertado:
CartPage e ícones do ui-kit. Sem edições em checkout/auth.”CartPage, useCart, ícones do ui-kit, index do ui-kit).Após a mudança, documente para que o contexto futuro permaneça pequeno:
Se funciona bem para uma pessoa mas não para o resto da equipe, o que falta normalmente é repetibilidade. Faça da “boa higiene de contexto” o padrão, não um hábito pessoal.
Salve um esqueleto de prompt que todo mundo possa copiar e preencher. Mantenha curto, mas rígido. Inclua o objetivo (o que significa “pronto”), escopo permitido, limites duros (e por quê), um resumo local e um contrato de saída (plano primeiro, depois diffs e testes).
Evite grandes revisões mensais que ninguém faz. Anexe atualizações de resumo ao trabalho normal: quando uma mudança altera comportamento, dependências ou APIs, atualize o resumo local no mesmo PR.
Uma regra simples: se um colega perguntaria “onde isso vive?” ou “o que depende disso?”, o resumo está desatualizado.
Se você prefere um fluxo chat-first, o Koder.ai pode ajudar a tornar esse estilo de iteração mais seguro. O modo de planejamento ajuda a concordar sobre escopo e limites antes de edições acontecerem, e snapshots com rollback permitem testar mudanças sem travar quando uma suposição se mostra errada.
Claude fica menos preciso quando não consegue “ver” a verdadeira fonte da verdade.
Em um monorepo grande, o modelo frequentemente deixa de fora um arquivo de dependência, confunde dois pacotes parecidos ou replica um padrão antigo porque foi isso que apareceu no contexto.
Não tente incluir o repositório inteiro. Comece com o menor conjunto que comprove que a mudança está correta.
Um padrão útil é:
Compartilhe o que ancora o comportamento, não tudo que tem o mesmo nome.
Um conjunto prático é:
Escolha um limite que reflita a organização do repositório: um pacote, app ou serviço.
Depois, declare-o explicitamente, incluindo o que está fora do escopo. Exemplos de restrições:
packages/cart/ e seus testes.”Porque monorepos frequentemente têm módulos parecidos (ui, ui-kit, shared-ui) e helpers duplicados (date.ts em dois lugares).
Claude pode aplicar a ideia certa no pacote errado ou importar de um nome de módulo “quase certo”. Prevença isso nomeando o pacote e os pontos de entrada exatos.
Um resumo local é um mapa curto da área exata que você quer mudar, geralmente 10–20 linhas.
Inclua:
Coloque-o perto do código que descreve para que seja fácil de achar e atualizar.
Um padrão simples:
SUMMARY.md ou uma pequena seção no README.md do pacoteDiga ao Claude para sinalizar suposições e desconhecidos em vez de chutar.
Uma regra útil:
Use um loop curto que force o contexto a ser conquistado em pequenas peças:
Escreva um mini “contrato” no seu prompt e torne-o exequível:
Isso facilita a revisão e reduz edições acidentais entre pacotes.