Claude Code em monorepos: limitar o contexto e manter a precisão

Por que monorepos grandes tornam o Claude menos preciso

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.

Comece definindo a tarefa, não o repositório

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.”

Defina limites claros que o Claude não deva cruzar

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.”

Como escrever resumos locais úteis

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:

• Para que serve este pacote/serviço, e para que não serve (limites de escopo)
• Onde o trabalho começa (pontos de entrada como arquivos principais, rotas, comandos ou componentes)
• O que é seguro chamar de fora (APIs públicas, módulos exportados, eventos, endpoints)
• Do que ele depende (bancos, filas, caches, config, serviços externos)
• Quais regras importam aqui (padrões de nome, estilo de erro, logging, e como os testes são escritos)

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.

Onde colocar os resumos e como mantê-los atualizados

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:

• O que é esta pasta (propósito em 1–2 frases)
• Superfície pública (pontos de entrada principais, módulos exportados ou APIs)
• Dependências chave (internas e externas)
• Limites (o que não deve importar ou modificar)
• Como testar (a checagem local mais rápida)
• Last updated: 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.

Um fluxo passo a passo para ficar dentro do contexto certo

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.

Passo 1: Peça primeiro um mapa rápido

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.”

Passo 2: Comece com uma fatia e um limite

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:

• Defina o objetivo e o limite em uma frase.
• Exija suposições e desconhecidos (Claude deve listá-los).
• Peça os arquivos exatos que ele precisa a seguir (limite de 3 a 6).
• Forneça apenas esses arquivos, então repita.
• Exija um plano curto antes de qualquer patch.

Passo 3: Force suposições explícitas e pedidos de arquivo

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.

Use restrições e contratos nos seus prompts

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:

• Modificar somente arquivos sob packages/payments/.
• Não editar packages/auth/, infra/ ou configs compartilhadas.
• Se precisar de alterações fora do escopo, pare e peça primeiro.
• Mantenha as mudanças mínimas: corrija o bug, evite refactors.

Depois, defina checagens de aceitação. Sem elas, o Claude pode produzir código que parece certo mas quebra regras reais do repositório.

• Rode os testes unitários do pacote (nomeie o comando que você usa).
• Rode lint/format (nomeie a ferramenta, ou diga “use a config existente”).
• Rode typecheck/build do pacote.
• Confirme que a app ainda inicia (um comando simples de run basta).

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.”

Armadilhas comuns que causam desvio e edições erradas

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:

• A resposta fala sobre “padrões típicos” sem nomear seus arquivos reais
• Introduz uma nova utilidade compartilhada em vez de usar a existente
• Altera imports entre limites de pacotes
• Ignora feature flags ou ramos específicos de env
• Sugere adicionar uma dependência a um pacote central

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.

Checklist rápido antes de pedir qualquer coisa ao Claude

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:

• Boundary: Trabalhar somente em <package>/<path>. Objetivo: <uma frase>. Ignore todo o resto a menos que solicitado.
• Context starter: Resumo local: <5-10 linhas>. Arquivo de entrada: <path/to/file>.
• Constraints: Pastas permitidas: <...>. Não mudar: <pastas/arquivos ou APIs>. Manter comportamento: <o que deve continuar verdadeiro>.
• Pedido de arquivos primeiro: “Antes de propor mudanças, liste os arquivos mínimos que precisa ver (máx 5) e por quê.”
• Formato de saída: “Responda com um plano curto primeiro. Após minha confirmação, dê sugestões em estilo patch por arquivo.”

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.

Exemplo: fazer uma mudança em um pacote sem acordar o monorepo inteiro

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:

1. Mapa: “Essa mudança está limitada a CartPage e ícones do ui-kit. Sem edições em checkout/auth.”
2. Suposições: exija uma lista de suposições e espere confirmação.
3. Pedidos de arquivos: aprove apenas os poucos arquivos realmente necessários (CartPage, useCart, ícones do ui-kit, index do ui-kit).
4. Plano: confirme que bate com os limites.
5. Edições: faça o menor diff possível, depois peça os testes atualizados.

Após a mudança, documente para que o contexto futuro permaneça pequeno:

• Atualize ambos os resumos locais com o novo export e os arquivos exatos tocados.
• Adicione uma nota curta no cabeçalho da página do carrinho: o que o botão faz e onde o estado é tratado.
• Registre os comandos de teste que passaram (e quaisquer snapshots atualizados).

Próximos passos: torne isso repetível para sua equipe

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.

Transforme seus melhores prompts em um template de equipe

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).

Mantenha resumos atualizados com uma cadência leve

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.