# Cursor Agent com Next.js: guia prático de uso

URL: https://agentvera.dev/pt/blog/cursor-agent-para-nextjs/ · Publicado: 2026-11-01

Aprenda a usar o Cursor Agent em projetos Next.js: configure AGENTS.md, monte um fluxo de trabalho com testes e evite erros de Server/Client Components.

**Resumo:**

- Cursor Agent funciona bem em projetos Next.js quando o AGENTS.md define comandos, pastas e regras de Server/Client Components.
- Adote tarefas pequenas e exija lint, typecheck, testes e build antes de aceitar as mudanças do agente.
- Os erros mais comuns estão no limite servidor/cliente, cache, next/image e variáveis de ambiente; revise esses pontos no diff.

No seu projeto Next.js, rode `cursor-agent` na raiz e deixe o agente trabalhar diretamente no terminal. O Cursor Agent lê as instruções de `AGENTS.md` ou `.cursor/rules`, então a configuração inicial define se ele vai respeitar o App Router, os limites de Server/Client Components e os comandos de validação. Este guia mostra um fluxo real para obter mudanças seguras, testadas e revisáveis em qualquer codebase Next.js.

## Por que o Cursor Agent se encaixa bem no Next.js
O [Cursor Agent](/pt/agents/cursor-agent/) executa como CLI e edita múltiplos arquivos, o que resolve bem tarefas full stack do Next.js: um componente, uma route handler e um teste podem ser alterados na mesma interação. Diferente de gerar código solto, ele segue as regras do repositório e roda os comandos que você definir, o que ajuda a manter a divisão entre Server Components, Client Components e route handlers. O risco está exatamente nessas fronteiras; com instruções claras, o agente acerta mais do que um assistente genérico, mas não substitui a sua revisão. Funciona tanto no App Router quanto no Pages Router, desde que as convenções de pastas estejam descritas.

## Preparando o projeto para o agente
Crie um `AGENTS.md` na raiz ou use `.cursor/rules`. O arquivo deve ser curto e específico; o agente o lê a cada turno. Inclua os comandos que ele pode executar, a estrutura de pastas, as regras de `'use client'`, roteamento, imagens, validação e cache. Um exemplo realista para um projeto com App Router, Vitest e Playwright:

```markdown
# AGENTS.md

## Comandos
- Instalar: npm ci
- Desenvolvimento: npm run dev
- Build: npm run build
- Lint: npm run lint
- Typecheck: npx tsc --noEmit
- Testes unitários: npm run test (Vitest)
- Testes E2E: npx playwright test

## Estrutura
- App Router em src/app; Pages Router em src/pages, se houver.
- Componentes compartilhados em src/components.
- Funções de servidor e validações em src/lib.
- Testes unitários colocalizados ou em src/__tests__.
- Testes E2E em e2e/.

## Regras Next.js
- Server Components por padrão; adicione 'use client' apenas quando usar hooks, eventos ou browser APIs.
- Não importe módulos do Node em Client Components; use route handlers ou Server Actions.
- Use next/link e next/image; nunca <a> para navegação interna nem <img> para imagens estáticas.
- Em Server Components, use fetch com next.revalidate ou revalidatePath/revalidateTag quando necessário.
- Valide entrada de Server Actions e route handlers com zod.
- Nunca exponha segredos sem prefixo NEXT_PUBLIC_ no cliente.
- Mantenha ESLint next/core-web-vitals ativo.

## Preferências
- TypeScript estrito, sem any.
- Mensagens de commit curtas em português.
- Não altere configurações de build sem pedir revisão.
```

Mantenha o arquivo versionado e atualize quando a estrutura mudar. Se preferir regras menores, divida em `.cursor/rules/nextjs.md` e `.cursor/rules/testes.md`. Antes de iniciar, confirme que o projeto está limpo com `git status` e, idealmente, rode você mesmo `npm run lint` e `npm test` para estabelecer a linha de base. Se ainda não sabe como usar o CLI, veja [Como usar o Cursor CLI: guia passo a passo](/pt/blog/how-to-use-cursor-cli/).

## Um ciclo de trabalho que funciona
Use sempre o mesmo loop: planeje a mudança em um parágrafo, peça uma tarefa pequena, rode os testes e revise o diff antes de aceitar. Não peça “melhore o site” nem deixe o agente tocar em muitas áreas ao mesmo tempo. Peça explicitamente para ele executar lint, typecheck e testes, e para parar se algo falhar.

- Adicione a página `src/app/produtos/[slug]/page.tsx` como Server Component, com `fetch` revalidado por tag, `generateMetadata` e tratamento para produto não encontrado.
- Crie `src/components/AddToCartButton.tsx` como Client Component com `useState`, recebendo uma Server Action via prop e mantendo `'use client'` na primeira linha.
- Implemente `src/app/api/carrinho/route.ts` com validação zod, retorno JSON e status 422 para entrada inválida; adicione testes Vitest em `src/__tests__/carrinho.test.ts`.
- Corrija o erro de hidratação em `src/components/Horario.tsx` sem adicionar `'use client'`; remova acesso a `window` durante a renderização.
- Escreva `e2e/login.spec.ts` com Playwright para o fluxo de login com email e senha, e execute `npx playwright test`.

Após cada tarefa, revise com `git diff --stat` e `git diff`. Não confie cegamente: o agente pode remover um `'use client'` necessário ou alterar o cache sem querer. Se algo parecer estranho, peça uma explicação ou desfaça e recomece com um prompt menor.

## O que o Cursor Agent faz bem e onde vigiar de perto
Tarefas bem delimitadas saem melhores: criar rotas, componentes, validações, testes, corrigir erros de lint e refatorar com segurança quando os testes cobrem a área. O agente também lida bem com atualizações de Next.js, como migrar de Pages Router para App Router em etapas, se você fornecer o passo a passo.

| Área | O que observar no diff |
|---|---|
| Limite Server/Client | Mudanças indevidas em `'use client'`; importação de módulos Node em client; hooks em Server Components. |
| Roteamento e links | Uso de `<a>` no lugar de `next/link`; falta de `prefetch={false}` em links para rotas dinâmicas; `useRouter` importado de local errado. |
| Cache e revalidação | Fetch sem `next.revalidate` em dados que mudam; `revalidatePath` chamado em loop; páginas estáticas que deveriam ser dinâmicas. |
| Imagens | `next/image` sem `width`/`height` ou `fill`; import de imagens fora de `public`; `layout` antigo. |
| Variáveis de ambiente | Segredos expostos sem `NEXT_PUBLIC_`; uso de `process.env.SECRET` no cliente; falta de validação no servidor. |
| Route handlers | Retorno de status errado; ausência de `try/catch`; `any` em validação; falta de `export const runtime` quando o edge é desejado. |

Ao revisar, foque nesses pontos mesmo quando os testes passam. O agente tende a acertar o fluxo feliz, mas pode introduzir regressões sutis nas bordas do runtime.

## Testes e verificação no Next.js com o agente
Inclua no prompt que o agente deve rodar os comandos e corrigir as falhas antes de finalizar. A sequência mínima para Next.js é `npm run lint`, `npx tsc --noEmit`, `npm run test` (ou `npx vitest run`) e `npm run build`. O build é o que mais revela problemas de Server/Client, static/dynamic e geração de páginas. Para fluxos críticos, rode `npx playwright test` depois de subir um servidor local; você pode pedir ao agente para executar `npm run dev` em background e só então disparar os testes E2E, mas revise o processo para não deixar portas abertas. Se o projeto usa Jest em vez de Vitest, substitua o comando de teste correspondente e mantenha a mesma exigência de passar antes do commit. Não aceite que o agente pule testes, desative regras do ESLint ou altere configurações de TypeScript para esconder erros. Uma boa prática é pedir que ele rode o build após modificar qualquer arquivo de configuração do Next.js, como `next.config.mjs`, `middleware.ts` ou `server actions`, porque essas mudanças afetam o bundler e podem quebrar a aplicação em produção.

## Rodando vários agentes no mesmo projeto Next.js com AgentVera
Para projetos maiores, rodar vários agentes em paralelo acelera o trabalho, mas conflitos de arquivo são um risco. O [AgentVera](/pt/blog/best-tools-parallel-ai-coding-agents/) executa ferramentas como Cursor Agent em terminais lado a lado, cada uma em seu próprio git worktree, então as mudanças não se sobrescrevem. Você pode revisar o código automaticamente quando cada turno termina e usar checkpoints para desfazer qualquer ação ruim em um clique. Para o Next.js, isso significa que um agente pode trabalhar no App Router enquanto outro cuida de testes E2E sem quebrar o cache ou as configurações do outro.

## Considerações finais
O Cursor Agent acelera tarefas repetitivas e bem definidas em Next.js, mas o valor está em configurar o `AGENTS.md` corretamente e manter a disciplina de revisão. Se você ainda está começando com esse fluxo, pratique em branches isolados e aumente a autonomia aos poucos, sempre deixando lint, typecheck, testes e build como portões de qualidade. Para um olhar mais amplo sobre como usar agentes de terminal com segurança, veja [Como fazer vibe coding com segurança: um fluxo prático](/pt/blog/how-to-vibe-code/). Com esse equilíbrio, o agente se torna uma extensão confiável do seu time, não uma caixa-preta.

## Perguntas frequentes

**Cursor Agent funciona com Next.js App Router?** Sim. Ele lê AGENTS.md ou .cursor/rules e consegue criar Server Components, layouts, pages e route handlers. O importante é definir a estrutura de pastas e as regras de limites entre servidor e cliente antes de começar.

**Como faço o Cursor Agent não misturar Server e Client Components?** Inclua regras explícitas no AGENTS.md: Server Components por padrão, adicionar 'use client' apenas com hooks ou eventos, e proibir import de módulos Node em componentes client. Revise o diff sempre procurando por essas violações.

**Quais comandos devo pedir ao Cursor Agent para validar um projeto Next.js?** Peça npm run lint, npx tsc --noEmit, npm run test (ou npx vitest run) e npm run build. Para fluxos E2E, inclua npx playwright test após subir o servidor local.

**O Cursor Agent pode rodar testes Playwright?** Sim, se o Playwright estiver configurado no projeto. Instrua o agente a executar npx playwright test e corrigir falhas reais, sem apagar ou pular testes apenas para passar.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/