Introducao
Vou te contar um cenario que ja vi em pelo menos 30 software houses nos ultimos 6 meses.
A empresa adotou monorepo. Faz sentido: codigo compartilhado, PRs atomicos, visibilidade total. Ai veio o Claude Code com agent teams — 3, 5, as vezes 8 agents trabalhando em paralelo no mesmo repositorio. Produtividade disparou. Ate que alguem olhou o disco.
Um usuario do forum do Cursor reportou que em 20 minutos de sessao com um codebase de 2GB, a criacao automatica de worktrees consumiu 9.82GB de disco. E isso sem contar node_modules, build cache, e artefatos do Bazel ou Nx. Com tudo junto? Facilmente 30-40GB.
O problema e simples: cada worktree e um clone completo do repositorio. Se o seu monorepo tem 2GB e voce roda 5 agents paralelos, sao 10GB so de codigo-fonte. E cada agent precisa do seu proprio npm install, que multiplica dependencias. A matematica e impiedosa.
Na minha experiencia com 300+ software houses, monorepo + agents paralelos e a combinacao mais poderosa que existe pra produtividade de desenvolvimento. Mas sem o controle certo, e tambem a que mais consome recursos. Desde a v2.1.76, o Claude Code tem a solucao: worktree.sparsePaths — git sparse-checkout automatizado que faz cada worktree conter so o que o agent precisa.
O que e worktree.sparsePaths
Primeiro, contexto rapido. Git worktrees sao copias isoladas do seu repositorio que compartilham o mesmo historico. O Claude Code usa worktrees para dar a cada agent (ou subagent) seu proprio espaco de trabalho, evitando conflitos de merge quando multiplos agents editam arquivos simultaneamente.
O problema e que, por padrao, cada worktree faz checkout de todo o conteudo do repositorio. Num repo pequeno, ninguem nota. Num monorepo com 50 packages, frontend, backend, infra, docs, mobile — cada worktree carrega tudo. Mesmo que o agent so precise editar 2 arquivos no package api.
O worktree.sparsePaths e um setting do Claude Code que configura automaticamente o git sparse-checkout em cone mode quando voce cria um worktree via claude --worktree ou quando um subagent com isolation: worktree e criado. Voce lista os diretorios que quer, e o worktree so contem esses diretorios.
Como funciona na pratica
Configuracao
Adicione no seu settings.json (projeto ou usuario):
{
"worktree": {
"sparsePaths": [
"packages/api",
"packages/shared",
"libs/common",
"configs"
]
}
}
Pronto. A partir de agora, todo worktree criado pelo Claude Code — seja via claude --worktree, seja por um subagent com isolation: worktree — vai conter apenas esses 4 diretorios, mais os arquivos na raiz do repo (package.json, tsconfig.json, .gitignore, etc.).
Exemplo real: monorepo de SH com microservicos
Imagine um monorepo tipico de software house:
acme-monorepo/ # 3.2GB total
├── packages/
│ ├── api/ # 180MB — Backend principal
│ ├── web/ # 420MB — Frontend React
│ ├── mobile/ # 380MB — React Native
│ ├── admin/ # 150MB — Painel admin
│ ├── shared/ # 45MB — Tipos e utils compartilhados
│ └── design-system/ # 90MB — Componentes UI
├── libs/
│ ├── database/ # 60MB — ORM e migrations
│ ├── auth/ # 30MB — Autenticacao
│ └── analytics/ # 25MB — Tracking
├── infra/ # 200MB — Terraform, Docker, CI/CD
├── docs/ # 150MB — Documentacao
└── tools/ # 80MB — Scripts internos
Sem sparsePaths, um agent que so precisa corrigir um bug no api faz checkout de 3.2GB. Com sparsePaths:
{
"worktree": {
"sparsePaths": [
"packages/api",
"packages/shared",
"libs/database",
"libs/auth"
]
}
}
O worktree fica com ~315MB em vez de 3.2GB. Reducao de 90%.
Agora multiplica por 5 agents paralelos:
E a economia nao para no disco. Menos arquivos significa:
Combinando com .worktreeinclude
O Claude Code tambem tem o arquivo .worktreeinclude que copia arquivos gitignored (como .env e .env.local) para os worktrees. As duas features sao complementares:
| Feature | Controla | Quando usar |
|---|---|---|
| `worktree.sparsePaths` | **Codigo-fonte** do repositorio | Limitar quais packages/diretorios o worktree contem |
| `.worktreeinclude` | **Configs locais** gitignored | Copiar .env, secrets, configs que nao estao no git |
Na pratica, voce configura os dois juntos:
# .worktreeinclude
.env
.env.local
.npmrc
// .claude/settings.json
{
"worktree": {
"sparsePaths": ["packages/api", "packages/shared", "libs/database"]
}
}
O worktree recebe so o codigo relevante + as configs locais necessarias. Completo e enxuto.
Com subagents e agent teams
A integracao com subagents e onde o sparsePaths realmente brilha. Quando voce define um subagent com isolation: worktree:
---
name: api-fixer
description: Corrige bugs no package api
isolation: worktree
tools: Read, Edit, Bash, Grep, Glob
---
Voce e um especialista no package api. Corrija o bug descrito,
rode os testes, e confirme que nada quebrou.
Cada vez que o Claude delega uma tarefa para esse subagent, ele:
1. Cria um worktree temporario
2. Aplica sparsePaths automaticamente (so packages/api + dependencias)
3. O subagent trabalha no espaco isolado
4. Se nao houver mudancas, o worktree e removido automaticamente
Com agent teams, 5 subagents rodando em paralelo — cada um em seu worktree enxuto — consomem uma fracao do disco que consumiriam sem sparse-checkout. E a performance de cada agent melhora porque o git opera sobre menos arquivos.
Por que isso importa para sua Software House
O elefante na sala: monorepos estao crescendo
A Spectro Cloud chamou 2026 de “o ano do monorepo” — e nao esta errada. A combinacao de AI agents que fazem cross-project changes atomicos + ferramentas como Turborepo e Nx que finalmente resolveram o problema de build fez com que mais SHs migrassem para monorepo.
Mas monorepo sem tooling adequado e receita pra desastre. Um estudo da AskanTech mostrou que empresas com tooling otimizado para monorepo tem:
E as que nao investem em tooling? CI de 45 minutos, devs esperando builds, e 3+ horas por semana perdidas com atualizacao de dependencias.
O custo real: a conta que ninguem faz
Vou fazer a conta. Uma SH com 15 devs, monorepo de 2GB, cada dev usando Claude Code com agent teams (3 agents paralelos em media):
Sem sparsePaths:
Com sparsePaths (checkout de 20% do repo):
Economia: 125GB de disco + operacoes 5x mais rapidas em cada worktree.
E isso impacta diretamente o bolso. Cada minuto que um dev espera npm install ou git status num worktree pesado e minuto jogado fora. Se cada dev perde 15 minutos por dia com operacoes lentas em worktrees (conservador), sao 15 × 15 × 22 = 4.950 minutos por mes = 82.5 horas = ~2 devs-semana jogados fora.
A conexao com o stack de produtividade
O worktree.sparsePaths nao existe isolado. Ele e parte de um stack que o Claude Code construiu para tornar agents paralelos viaveis em producao:
| Feature | Problema que resolve | Artigo |
| [Agent Teams](https://thuliobittencourt.com/claude-code-agent-teams-multiplos-agentes) | Agentes trabalhando em paralelo | ✅ |
| [–bare flag](https://thuliobittencourt.com/claude-code-bare-flag-cicd-pipeline-software-house) | Startup rapido em CI/CD | ✅ |
| [MCP_CONNECTION_NONBLOCKING](https://thuliobittencourt.com/claude-code-mcp-connection-nonblocking-pipeline-rapida-software-house/) | Pular espera de MCP em pipelines | ✅ |
| [SendMessage auto-resume](https://thuliobittencourt.com/claude-code-sendmessage-auto-resume-agent-teams-resiliencia-software-house) | Resiliencia quando agents param | ✅ |
| **worktree.sparsePaths** | **Disco e performance em monorepos** | **Este artigo** |
Juntos, esses recursos transformam Claude Code de “ferramenta de dev” em “infraestrutura de times de agents”. Cada um resolve uma peca do quebra-cabeca. Sem sparsePaths, agents paralelos em monorepos grandes simplesmente nao escalam.
O contexto tecnico que importa
Como o git sparse-checkout funciona por baixo
O worktree.sparsePaths do Claude Code usa o git sparse-checkout em cone mode por baixo dos panos. Cone mode, introduzido no Git 2.27 (2020), cria um subconjunto do repositorio em forma de cone — voce especifica diretorios, e todos os arquivos dentro desses diretorios sao incluidos, mais os arquivos na raiz.
A performance e dramatica. O GitHub Blog testou com um monorepo de 2 milhoes de arquivos:
O Claude Code abstrai toda essa configuracao. Voce nao precisa rodar git sparse-checkout init --cone, nem git sparse-checkout set, nem se preocupar com $GIT_DIR/info/sparse-checkout. Um setting JSON e tudo.
Limitacoes que voce precisa saber
1. Mesmo setting para todos os worktrees: o sparsePaths e global — todos os worktrees usam os mesmos paths. Se um agent precisa de packages/api e outro de packages/web, voce precisa listar os dois.
2. Arquivos na raiz sempre inclusos: package.json, tsconfig.json, .gitignore e outros arquivos na raiz do repo sempre estao presentes. Isso e comportamento do cone mode do git.
3. Dependencias implicitas: se packages/api importa de packages/shared, voce precisa incluir os dois no sparsePaths. O Claude Code nao resolve dependencias automaticamente.
4. Build cache nao e coberto: sparsePaths controla o checkout do git, mas build artifacts (dist/, .next/, node_modules/) sao criados pelo tooling. Considere configurar cache compartilhado (Turborepo remote cache, Nx Cloud).
O que eu penso
Eu acompanho de perto como SHs estao adotando AI agents para desenvolvimento. O padrao que vejo e claro: primeiro adotam Claude Code individualmente, depois descobrem subagents, depois agent teams, e ai esbarram no muro do monorepo.
O worktree.sparsePaths e aquele tipo de feature que nao gera hype nenhum no Twitter, mas que separa quem consegue escalar agents de quem desiste na primeira tentativa. E a diferenca entre “rodamos 5 agents paralelos e foi incrivel” e “rodamos 5 agents paralelos e o disco encheu em 20 minutos”.
O Nx Blog ja documentou como worktrees transformaram o workflow de AI agents. O Laurent Kempe escreveu sobre escalar de 3 para N worktrees paralelos no Windows. A comunidade esta convergindo na mesma direcao: worktrees sao a base do trabalho paralelo com IA, e sparse-checkout e o que torna isso viavel em repos grandes.
Se sua SH tem um monorepo e esta usando (ou planeja usar) agents paralelos, configura worktree.sparsePaths antes de escalar. Sao 5 linhas de JSON que evitam um problema de 100GB.
Conclusao
Monorepo + agents paralelos e a combinacao mais produtiva que o mercado de desenvolvimento tem hoje. Mas sem controle de checkout, e tambem a que mais desperica recursos.
O worktree.sparsePaths do Claude Code resolve isso com elegancia: uma configuracao JSON que transforma cada worktree de clone completo em checkout cirurgico. Menos disco, operacoes mais rapidas, agents mais eficientes.
Se voce esta escalando o uso de IA na sua software house e tem monorepo, isso nao e opcional — e pre-requisito.
Se voce quer estruturar esse nivel de automacao e produtividade na sua software house, a gente trabalha exatamente isso nos nossos treinamentos e mentorias.
Sou Thulio, mentoro 300+ SHs desde 2016.
