Pular para o conteúdo principal

Fluxo de teste visual via worktree (IA/agente)

Quando um agente de IA precisa validar mudanças visuais (CSS, componentes, layout) antes de commitar, o padrão usado neste projeto é subir uma segunda instância do next dev isolada, num worktree separado, sem interferir no pnpm dev que o desenvolvedor já tem rodando.

Por que um worktree em vez de editar direto​

O worktree evita dois problemas:

  • Conflito de .next: rodar um segundo next dev apontando pro mesmo diretório do projeto principal faria os dois processos escreverem no mesmo cache de build (.next/), o que pode corromper o build do desenvolvedor.
  • Symlink de node_modules não funciona com Turbopack: Symlink [project]/apps/web/node_modules is invalid, it points out of the filesystem root — Turbopack recusa symlinks que escapam da raiz do projeto do worktree. Por isso é preciso rodar pnpm install de verdade dentro do worktree (rápido, ~6-15s, majoritariamente cache hit do pnpm store).

O erro que torna esse fluxo lento​

Depois que o worktree existe e o pnpm install já rodou, o erro comum é matar e subir o processo next dev do zero a cada pequeno ajuste (uma mudança de className, um minWidth, etc.). Isso descarta o cache do Turbopack e força recompilar a rota inteira do zero na primeira requisição seguinte — algo como 15s+ só pra ver o resultado de uma linha de CSS.

O fluxo correto​

  1. Suba o next dev do worktree uma vez (ex: node run-3001.mjs, script que injeta as envs do DW a partir do .env.local principal e roda pnpm dev na porta 3001).
  2. Para cada ajuste: copie só o(s) arquivo(s) alterado(s) pro worktree (cp arquivo.tsx worktree/caminho/arquivo.tsx) e dê reload na página no navegador (Playwright/Chrome DevTools).
  3. O Fast Refresh do Turbopack pega a mudança em menos de 1 segundo — igual aconteceria no pnpm dev normal do desenvolvedor.
  4. Não reinicie o processo entre ajustes. Só reinicie se ele travar, crashar, ou se a estrutura do worktree mudar (novo arquivo criado, dependência nova instalada).
  5. Ao final da sessão de testes (antes de reportar "pronto" ou pedir validação do usuário), pare os processos do worktree (node run-3001.mjs, next dev, pino-pretty, postcss.js).

Resumo​

AçãoCusto
Criar worktree + pnpm install~6-15s, uma vez por sessão
Subir next dev (cold start)~1-2s pra ficar "Ready", uma vez por sessão
Primeira compilação de uma rota~15s, uma vez por rota, por sessão
Ajuste + Fast Refresh (fluxo correto)<1s por rodada
Ajuste + restart do processo (fluxo errado)~15s+ por rodada — evitar