Git worktrees + agentes em paralelo: isolar tarefas sem bagunçar o repo

Dois agentes no mesmo working directory é receita para caos: um formata o arquivo que o outro ainda estava editando, o git status vira sopa, e o humano perde a noção de quem quebrou o build. Git worktrees resolvem o isolamento sem clonar o remoto de novo: um .git compartilhado, vários checkouts, cada um numa branch.

Em 2026 isso virou peça central de ADEs como o Orca — e também funciona no terminal “puro” com git worktree.


O problema do working tree único

Agentes escrevem arquivos o tempo todo. Em paralelo, no mesmo tree:

  • Conflitos de edição sem merge formal.
  • Testes de A falhando por causa do diff sujo de B.
  • git stash acidental engolindo o trabalho do outro.
  • Hooks e watchers disparando duas vezes no mesmo path.

Isolar por processo (dois terminais) não isola por filesystem. Worktree isola o filesystem do checkout.


Worktree em 60 segundos

# a partir do repo principal, na branch atual
git fetch origin

# novo checkout em pasta irmã, branch nova a partir de origin/main
git worktree add ../portfolio-fix-login -b fix/login-race origin/main

cd ../portfolio-fix-login
# agente trabalha só aqui

Listar / limpar:

git worktree list
git worktree remove ../portfolio-fix-login
# se a pasta já foi apagada à mão:
git worktree prune

Cada worktree tem sua branch (ou um detach). O objeto store é compartilhado — clones baratos em disco comparado a git clone completo.


Padrão: um agente, um worktree

Regra operacional simples:

PapelWorktree
Humano no dia a diamain checkout
Agente A (feature)../repo-feat-x
Agente B (bugfix)../repo-fix-y
Reviewer read-onlypode ser o mesmo tree do autor se não escrever; senão, tree próprio no commit do autor

ADE como Orca automatiza: criar worktree, escolher agente (Claude Code, Cursor CLI, OpenCode…), mostrar diff, apagar perdedores. O conceito é o mesmo do comando acima — ver comparação das tools.


Race: três abordagens, um bug

Fluxo que mais paga o isolamento:

  1. Crie três worktrees a partir do mesmo ref (origin/main).
  2. Lance três agentes com o mesmo prompt.
  3. Espere idle / testes.
  4. Compare diffs.
  5. Shippe o vencedor; delete os outros worktrees/branches.

Isso é orquestração leve — detalhada em orquestração de agentes de código. O valor não é “três vezes mais tokens”: é diversidade de falha barata de inspecionar.


Cuidados que pegam gente experiente

Dependências por worktree

node_modules não é compartilhado de forma mágica. Em JS/TS, cada worktree costuma precisar do próprio install (yarn / pnpm). Em monorepos grandes, orçamento de disco importa — use cache do package manager.

Portas e processos

Dois next dev → conflito de porta. Padronize PORT=3010, 3011, … por worktree ou mate o servidor ao terminar a task.

Arquivos ignorados e secrets

.env local: copie com cuidado ou use secret manager. Não assuma que o agente “vê” o env do tree principal.

Hooks

husky / pre-commit rodam por tree. Um agente que commit afoito ainda respeita hook — desde que o hook esteja instalado naquele tree.

Branch naming

Prefixos claros (agent/, orca/, wt/) evitam misturar branches humanas com experimentos descartáveis.


Mini playbook sem ADE

REPO=~/Coding/personal/portfolio
PARENT="$(dirname "$REPO")"
BASE=origin/main
NAME=fix-flake-checkout
WT="$PARENT/$NAME"

git -C "$REPO" fetch origin
git -C "$REPO" worktree add "$WT" -b "agent/$NAME" "$BASE"

cd "$WT"
# ex.: claude / cursor agent / opencode — prompt colado aqui
# yarn && yarn test

# se aprovado:
# git push -u origin HEAD
# gh pr create ...

# se descartar:
cd "$REPO"
git worktree remove "$WT"
git branch -D "agent/$NAME"

Ajuste paths ao seu OS; o ponto é ritualizar add → work → pr ou remove.


Ligação com skills e MCP

  • Skill de “spawn worktree” deve fixar base ref (origin/main vs branch atual).
  • MCP com estado em /tmp deve ser safe sob paralelo.
  • Rules: “nunca rode dois writers no tree do humano”.

Ver Skills e Rules e MCP.


Checklist

  • Cada writer tem seu worktree?
  • Base ref explícita no create?
  • Ports / installs isolados?
  • Plano de limpeza (remove + apagar branch)?
  • Integração (PR) feita por um único dono?

Conclusão

Worktrees são o isolamento barato que agentes exigem. Sem eles, “paralelismo” é só dois processos brigando pelo mesmo disco. Com eles — no git puro ou num ADE — você compara abordagens, pipelineia tasks e mantém o tree humano limpo.

Para o restante do site e projetos: portfolio.