O que next-dev-loop faz?
O ritmo de edição/verificação durante next dev — faça uma alteração e depois
confirme que ela realmente funciona em tempo de execução, não apenas que os tipos ou
o build estão satisfeitos.
Você verifica através de duas visões do mesmo aplicativo em execução:
/_next/mcp— um endpoint HTTP que o Next.js expõe sobre si mesmo. Sabe coisas específicas do framework: rotas, segmentos, RSC, actions do servidor, logs do servidor e erros conforme o Next.js os viu. Chametools/listpara obter a superfície atual.agent-browser— um CLI que controla um Chrome real. Sabe coisas do navegador independentes de framework: DOM, console, rede, React fiber, vitals. Antes de usá-lo, executeagent-browser skills get coreuma vez para obter o guia de uso correspondente à versão — não adivinhe subcomandos de memória.
As duas visões se verificam mutuamente.
requer
- Next.js 16.3+ com Turbopack —
/_next/mcpmais a verificação proativa de compilação viaget_compilation_issues. agent-browser>= 0.31.1 — introspecção React,session idcom escopo de worktree,--restoreidempotente e reconciliação de flags de inicialização.
Estes são limites mínimos obrigatórios, não preferências opcionais. Se algo estiver faltando, diga ao usuário como atualizar e pare. Não recorra a grep no código fonte ou a uma sonda mais fraca — esta skill assume que ambas as visões estão ativas nas versões acima.
- Atualizar Next.js:
pnpm next upgrade(ounpx next upgrade). Documentação: https://nextjs.org/docs/app/getting-started/upgrading (guia da versão 16: https://nextjs.org/docs/app/guides/upgrading/version-16) - Instalar ou atualizar
agent-browser:npm i -g agent-browser@latest. Se o CLI não estiver noPATH, instale-o antes de continuar — o pré-voo espera poder invocá-lo diretamente.
pré-voo
Uma vez por sessão, confirme que ambas as visões estão ativas.
-
Abra o
agent-browserna URL alvo, restaurando o estado de login salvo, quando presente. Primeiro, derive um session id estável para este checkout e use-o em todos os comandosagent-browser:SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)" export AGENT_BROWSER_SESSION="$SESSION" export AGENT_BROWSER_RESTORE="$SESSION"Em seguida, abra a URL alvo:
agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>--scope worktreeevita que worktrees paralelos e checkouts copiados colidam.--restoresozinho usa o session id como chave de persistência, carrega cookies/localStorage salvos antes da navegação quando presentes e salva automaticamente o estado ao fechar. Sempre passe as flags de inicialização desejadas noopen; o agent-browser reutilizará, relançará ou reiniciará seu estado de fundo com escopo conforme necessário.O navegador é do usuário. Se o estado não foi restaurado (primeira execução, sessão expirada) e a página está protegida, o usuário faz o login — pause até que ele confirme. Após o login, continue usando a mesma sessão e contexto de restauração;
agent-browser closesalva o estado dos cookies para que o próximoopeno restaure. -
Sonda
/_next/mcp(tools/list) — confirme que está acessível e listaget_compilation_issues:- Inacessível → ou
next devnão está em execução, ou o Next.js está abaixo da versão 16.3. Verifiquepackage.jsonpara desambiguar, depois recuse. get_compilation_issuesnão está na lista → Next.js abaixo de 16.3. Recuse e diga ao usuário para atualizar.
- Inacessível → ou
-
get_compilation_issuestambém serve como uma sonda do Turbopack. Uma resposta de erro"Turbopack project is not available..."significa que o usuário está no webpack. Recuse — Turbopack é obrigatório. -
get_routes→ seu mapa de rotas para o resto da sessão.
loop
antes da edição — restrinja o escopo
Pergunte ao aplicativo em execução, não ao código fonte. /_next/mcp sabe quais
arquivos renderizaram a rota atual; use-os como seu escopo de busca.
A introspecção em tempo de execução permanece barata à medida que o código fonte cresce;
a busca por agente não.
após a edição — verifique
Quatro modos de falha. Verifique cada um:
- Compila —
get_compilation_issues. - Executa sem erros —
/_next/mcp(erros do servidor e erros do navegador que chegam ao servidor aparecem aqui). - Comporta-se como esperado —
agent-browserdirige a página; afirme o que o usuário realmente vê. - Comportamento no nível React —
agent-browsercom react-devtools ativado expõe a árvore de componentes, props, estado e contagens de renderização. Fixe as verificações no nível do framework aqui (renderizações extras, mudanças de limites servidor/cliente, fallbacks de suspense) — apenas afirmações de DOM as perdem.
Escolha a ferramenta específica de tools/list ou do manual do agent-browser
em vez de usar a memória.
armadilhas
- Todo comando
agent-browserprecisa saber sua sessão e chave de restauração, ou pode usar um navegador padrão vazio ou falhar ao salvar o estado de login. A maneira mais fácil: exporte tantoAGENT_BROWSER_SESSION="$SESSION"quantoAGENT_BROWSER_RESTORE="$SESSION"no topo de cada shell onde você executar o agent-browser. Se não exportá-los, passe--session "$SESSION" --restoreem todo comando. - Quando as duas visões discordam, suspeite primeiro das ferramentas. Se
agent-browserdiz que uma rota está quebrada mas/_next/mcpe o servidor dizem que ela renderizou corretamente, uma sessão de navegador obsoleta ou mal direcionada é a causa mais provável do que um bug real — reconcilie as visões antes de depurar o aplicativo. - Confirmar um clique ou navegação: a página se estabiliza um pouco depois,
então espere com
wait --load networkidle(nenhum caminho para errar), depois faça um snapshot/leitura para confirmar a página. Evitewait --urla menos que você passe o href exato do link — um caminho adivinhado ou placeholder não corresponderá à URL real e causará timeout após 25s. - Uma leitura em branco, snapshot vazio,
about:blankou um erro "no browser session" — logo apósopenou após um clique (mesmo seopenreportou a página) — é o navegador dropando a página (uma sessão obsoleta), não uma rota quebrada. Reabra sua sessão na URL com--session "$SESSION" --restoree faça um novo snapshot; se ainda estiver em branco, executeagent-browser --session "$SESSION" --restore close, depois abra novamente. Não recorra acurl; ele ignora o navegador que você está testando. - A saída da introspecção React fica obsoleta após a navegação. Execute novamente.
- As respostas de
/_next/mcpsão SSE — leia o JSON da linhadata:comsed -n 's/^data: //p'(umsed 's/^data: //'simples deixa a linhaevent:e o parse falha). - Servidor de desenvolvimento em porta diferente de 3000: leia o banner do
next dev; definaNEXT_MCP_URL=http://localhost:<port>/_next/mcp. get_errorseget_page_metadataprecisam de pelo menos uma navegação para serem preenchidos.
referência
Todas as ferramentas abaixo estão presentes assim que o pré-voo passar. Se tools/list
estiver faltando alguma delas, o pré-voo deveria ter recusado — verifique novamente.
# /_next/mcp notas
get_project_metadata projectPath, devServerUrl, bundler
get_routes varredura do sistema de arquivos; nenhuma sessão de navegador necessária
get_errors tempo de execução + build; precisa de uma sessão de navegador;
inclui erros do lado do navegador capturados pelo servidor
get_page_metadata segment trie + routerType; precisa de uma sessão de
navegador; use como atalho de descoberta para saber
quais arquivos alimentam uma rota
get_logs retorna logFilePath
get_server_action_by_id id com hash → arquivo + nome da função
get_compilation_issues apenas Turbopack; erros no webpack
("Turbopack project is not available")
desmontagem
Feche a sessão com a mesma sessão e contexto de restauração:
agent-browser --session "$SESSION" --restore close. close salva
os cookies e armazenamento daquela sessão para que o próximo --restore open
mantenha o usuário logado. Deixe next dev rodando para o próximo loop.
Skills irmãs next-dev-loop-<tópico> (por exemplo, next-dev-loop-rsc, next-dev-loop-debug)
assumem que este pré-voo já foi executado; elas continuam a partir do loop.