Shadow Workspace & Git Worktrees

1. Visão geral do conceito e problema sistêmico

Quando um agente autônomo começa a modificar a base de código no diretório ativo do desenvolvedor, surge um bloqueio crítico (Workflow Lockout). Se o agente edita 25 arquivos, compila o código, instala pacotes e executa testes, a pessoa não consegue escrever código em paralelo, verificar seu dev-server local ou trocar de branch: as alterações não commitadas do desenvolvedor e do agente inevitavelmente se misturam, causando conflitos.

Além disso: se o agente falhar, travar ou alucinar, a redefinição da árvore de trabalho (git checkout -f ou git clean) pode apagar acidentalmente o trabalho não commitado do próprio engenheiro.

O Shadow Workspace (espaço de trabalho sombra) baseado em Git Worktrees resolve esse problema de forma definitiva. O agente recebe um diretório totalmente isolado no disco, vinculado à sua própria branch. O engenheiro continua escrevendo código em seu editor favorito, enquanto o agente em segundo plano realiza refatorações complexas no ambiente sombra sem qualquer impacto na estação de trabalho ativa.

2. Taxonomia arquitetural e modelo mental

A arquitetura de interação com espaços sombra baseia-se na divisão de discos e em uma base de objetos Git compartilhada:

┌─────────────────────────────────────────────────────────────┐
│                 SHARED REPOSITORY OBJECTS (.git)            │
└──────────────┬───────────────────────────────┬──────────────┘
               │                               │
               ▼                               ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│  PRIMARY WORKSPACE (Human)  │ │ SHADOW WORKSPACE (AI Agent) │
│ • Branch: feature/payments  │ │ • Branch: agent/fix-auth    │
│ • Path: ~/projects/app      │ │ • Path: ~/.worktrees/task-42│
│ • Port: 3000 (Active)       │ │ • Port: 3001 (Isolated)     │
│ • Uncommitted local edits   │ │ • Automated ReAct Loop      │
└─────────────────────────────┘ └─────────────────────────────┘

1. Banco de Objetos Compartilhado (Single Object Database):
   • Todos os workspaces utilizam uma única base local de objetos Git (.git/objects). Não há necessidade de baixar novamente gigabytes de histórico ou realizar um git clone lento.
2. Worktree Dinâmico do Agente:
   • Criado em milissegundos pelo comando git worktree add -b <agent-branch> <shadow-path> <base-commit>.
   • Fornece ao agente uma árvore de trabalho completamente limpa, sem lixo nem edições incompletas do humano.
3. Isolamento de Ambiente (Environment Decoupling):
   • Arquivos de configuração de ambiente próprios (.env.test), portas de rede isoladas e diretórios temporários de build dedicados.
4. Mecanismo de Reconciliação e Limpeza (Reconciliation & Cleanup):
   • Após a verificação e a passagem bem-sucedida dos testes, as alterações são consolidadas como um commit atômico, após o que o diretório sombra é removido com segurança (git worktree remove).

3. Pipeline técnico e mecânica interna

O ciclo de vida de uma tarefa no espaço de trabalho sombra:

1. Iniciação e Alocação do Espaço Sombra: O orquestrador (ou o desenvolvedor via um comando como agy-run-in-worktree) gera um ID único da tarefa e cria o diretório:

   git worktree add -b agent/auth-refactor ../shadow-auth main
   

2. Linkagem Rápida de Dependências: Para evitar esperar minutos pela execução de npm install, o orquestrador cria links simbólicos para node_modules compartilhados ou utiliza o cache de conteúdo do pnpm:

   ln -s $(pwd)/node_modules ../shadow-auth/node_modules
   

3. Trabalho Autônomo do Agente: O agente é iniciado com o diretório de trabalho Cwd = ../shadow-auth. Ele autonomamente:
   • Lê e edita arquivos.
   • Inicia um servidor local em uma porta isolada (PORT=3005 npm run test:e2e).
   • Itera no ciclo ReAct até o sucesso completo.
4. Validação do Resultado: Todos os testes passam no espaço sombra. Se o agente quebrar o build, o engenheiro não sente nenhum problema em sua IDE principal.
5. Consolidação e Integração: O agente faz o commit final na branch agent/auth-refactor. O orquestrador remove o diretório sombra:

   git worktree remove ../shadow-auth
   

6. Apresentação do Resultado ao Engenheiro: O engenheiro vê a notificação de conclusão da tarefa e pode executar um rápido git merge ou abrir um PR.

4. Cenários práticos de engenharia em produção

01. Desenvolvimento paralelo de feature sem interromper o trabalho do desenvolvedor

O engenheiro está construindo uma nova tela de configurações na branch main:

• Simultaneamente, inicia um agente em background para escrever migrações de banco de dados e controladores no espaço sombra.
• O agente executa testes, corrige tipos e prepara a parte backend em isolamento.
• O engenheiro não interrompe por um segundo sequer o desenvolvimento de sua tela.

02. Teste competitivo de hipóteses concorrentes (Multi-Agent Bake-off)

Busca pelo algoritmo mais rápido para processar grandes volumes de dados:

• O orquestrador provisiona três Worktrees paralelos: agent-a, agent-b, agent-c.
• Três modelos diferentes (Claude 3.7 Sonnet, DeepSeek R1, GPT-4o) recebem a mesma tarefa de otimização.
• Um benchmark é executado; a solução com melhor latência é selecionada, e os outros dois workspaces são automaticamente removidos.

03. Execução segura de scripts de agentes não verificados

Teste de uma atualização radical do núcleo do sistema:

• Se o agente corromper completamente a estrutura de arquivos ou gerar código inoperante, o desenvolvedor simplesmente exclui o diretório do workspace em 1 segundo, sem medo de danificar o repositório Git local.

5. Armadilhas, erros comuns e segurança

• Conflitos de Portas de Rede Ocupadas (Port Collisions): Se o workspace sombra iniciar testes que tentam implicitamente subir um web server na porta fixa 3000, eles falharão com o erro EADDRINUSE se essa porta estiver ocupada pelo desenvolvedor. Configure sempre a parametrização de portas.
• Bloqueios de Branch (Worktree Branch Locks): O Git proíbe montar a mesma branch em dois Worktrees diferentes simultaneamente. Agentes sombra devem sempre trabalhar em branches novas e únicas.
• Acúmulo de Espaço em Disco: Se o orquestrador terminar abruptamente sem a etapa de limpeza (git worktree remove), dezenas de pastas esquecidas do repositório podem permanecer no disco. Execute periodicamente git worktree prune.
• Vazamento de Arquivos Não Controlados (.env.local): Arquivos listados no .gitignore não são copiados automaticamente para o novo worktree. É necessário fornecer explicitamente ao agente acesso às variáveis de ambiente de teste para garantir a passagem correta dos testes.