# Gemini CLI com Next.js: guia prático para desenvolvedores

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

Aprenda a configurar o Gemini CLI em um projeto Next.js: GEMINI.md, loop de trabalho com testes e revisão de diff, e armadilhas comuns.

**Resumo:**

- O Gemini CLI funciona melhor no Next.js quando o GEMINI.md define comandos, pastas e regras de Server/Client Components.
- Use um loop curto: peça mudanças pequenas, rode lint, testes e build, e revise o diff antes de aceitar.
- Para vários agentes no mesmo repositório, worktrees separados, revisão automática e checkpoints evitam conflitos e builds quebrados.

O [Gemini CLI](/pt/agents/gemini-cli/) ajuda a implementar features, corrigir bugs e refatorar código em projetos Next.js sem sair do terminal. Com um `GEMINI.md` bem configurado, o agente respeita comandos de build, teste e lint e distingue Server Components de Client Components. Veja como configurar e operar o agente no dia a dia.

## Por que o Gemini CLI se encaixa no trabalho com Next.js

Next.js mistura renderização no servidor, componentes client, route handlers e convenções de arquivo que mudam o comportamento da aplicação. O Gemini CLI trabalha bem nesse cenário porque lê a estrutura do projeto e usa o contexto do `GEMINI.md` para não ultrapassar fronteiras como `"use client"` e imports de código de servidor. Em vez de dar respostas genéricas, ele edita arquivos, roda comandos e interpreta erros de build, lint e teste.

Na prática, você ganha um executor que entende a separação entre `app/` e `pages/`, a diferença entre Server e Client Components e o papel de `layout.tsx`, `page.tsx` e `route.ts`. Isso é valioso em um framework onde uma mudança pequena pode transformar uma página estática em dinâmica ou incluir um hook onde não deveria. Para quem está começando, vale seguir o fluxo descrito em [Como usar o Gemini CLI: guia passo a passo](/pt/blog/how-to-use-gemini-cli/).

## Preparando o projeto para o agente

Antes de iniciar o `gemini` no diretório do projeto, crie ou ajuste o `GEMINI.md` na raiz. Esse arquivo é a principal fonte de instruções do agente. Em Next.js, ele deve conter os comandos exatos de build, teste e lint, as convenções de pastas do App Router e do Pages Router, e regras sobre Server e Client Components.

Exemplo curto e realista:

```markdown
# GEMINI.md

## Comandos
- Instalar dependências: npm ci
- Build: npm run build
- Testes unitários: npm run test:unit
- Testes E2E: npm run test:e2e
- Lint: npm run lint
- Typecheck: npx tsc --noEmit

## Estrutura e convenções
- App Router em `app/`; Pages Router em `pages/` apenas para rotas legadas.
- Componentes de servidor não podem usar hooks, APIs do browser nem `"use client"`.
- Componentes com estado ou eventos recebem `"use client"` no topo e ficam em `components/client/`.
- Route handlers em `app/api/` retornam `Response` ou `NextResponse`.
- Código de servidor fica em `lib/server/`; nunca importe `lib/server` em Client Component.

## Regras para o agente
- Antes de alterar, rode `npm run lint` e os testes afetados.
- Não mude `next.config.*` sem explicar o motivo.
- Priorize Server Components; adicione `"use client"` apenas quando necessário.
- Nunca coloque secrets em Client Components; use variáveis de ambiente prefixadas com `NEXT_PUBLIC_` apenas para valores públicos.
```

Esse arquivo mantém o agente dentro das convenções do projeto e reduz revisões desnecessárias.

## Loop de trabalho: planejar, implementar em passos pequenos e revisar

O fluxo ideal com o Gemini CLI em um projeto Next.js é planejar a tarefa, pedir uma alteração pequena, rodar lint/testes/build e revisar o diff antes de seguir. O agente funciona melhor quando cada prompt descreve um objetivo claro, com arquivo ou rota alvo e critério de aceite.

Exemplos de prompts para tarefas comuns:

- "Crie uma página `app/produtos/[id]/page.tsx` que use `generateStaticParams` para gerar as rotas estáticas a partir de `lib/produtos.ts` e renderize os detalhes com um componente de servidor."
- "Refatore o componente `components/Carrinho.tsx` para usar `'use client'` apenas nos elementos interativos, mantendo os cálculos de preço como funções puras em `lib/preco.ts`."
- "Adicione um route handler `app/api/checkout/route.ts` que valide o payload com Zod e retorne `NextResponse.json` com status 400 em caso de erro. Depois adicione um teste com Vitest."
- "Corrija o problema de hidratação na página `app/dashboard/page.tsx`: compare o HTML do servidor com o primeiro render no cliente e sugira uma solução sem desativar a hidratação."
- "Rode `npm run test:e2e` e ajuste o teste de checkout para lidar com o novo fluxo de pagamento, mantendo os seletores do Playwright consistentes."

Depois de cada solicitação, revise `git diff` e rode `npm run lint` e os testes antes de aceitar a mudança.

## Tarefas típicas de Next.js com o agente e pontos de atenção

O Gemini CLI entrega bem tarefas bem delimitadas, como criar páginas com `generateStaticParams`, adicionar route handlers, mover dados de Server para Client Components e configurar metadata. Também é útil para explicar erros de build complexos e sugerir otimizações de bundle.

No entanto, vale observar de perto mudanças que afetam a fronteira entre servidor e cliente. O agente pode, sem querer, adicionar `"use client"` em um arquivo que contém dados sensíveis ou importar um hook do React em um Server Component. Também pode alterar `next.config.js` e mudar o comportamento de cache ou redirecionamentos sem explicitar o impacto.

Uma tabela rápida ajuda a orientar o agente:

| Tarefa | Prompt sugerido |
|---|---|
| Página estática com dados locais | "Crie `app/blog/[slug]/page.tsx` com `generateStaticParams` e `generateMetadata`." |
| Route handler com validação | "Adicione `app/api/contato/route.ts` com validação Zod e resposta `NextResponse.json`." |
| Corrigir erro de hidratação | "Investigue o aviso de hidratação em `app/perfil/page.tsx` e ajuste o componente para usar `useEffect` apenas quando necessário." |
| Converter Server para Client Component | "Transforme `components/Formulario.tsx` em Client Component, movendo apenas a parte interativa para `use client`." |

Nos pontos de atenção, revise sempre os imports e a localização de cada arquivo. Em projetos com Pages Router legado, confirme se o agente não mistura convenções de `getServerSideProps` no App Router.

## Testes e verificação no Next.js com o agente

Peça ao Gemini CLI para rodar os testes e interpretar falhas. No Next.js, o agente pode trabalhar com Vitest ou Jest para testes unitários e de componentes, e com Playwright para testes de ponta a ponta. O ideal é que os scripts estejam no `package.json` e descritos no `GEMINI.md`.

Sempre verifique:

- `npm run lint` para as regras do ESLint, incluindo as específicas do Next.js.
- `npx tsc --noEmit` para checagem de tipos, que evita problemas entre Server e Client Components.
- `npm run build` para validar a compilação em produção, incluindo geração de páginas estáticas e rotas dinâmicas.
- Testes E2E com Playwright para fluxos que dependem de interação no browser.

O agente pode corrigir testes quebrados, mas é importante revisar se a correção apenas força o teste a passar sem atacar a causa.

## Rodando vários agentes em um projeto Next.js com o AgentVera

Quando você quer escalar o trabalho, o AgentVera permite rodar o Gemini CLI e outros agentes em paralelo, cada um em seu próprio terminal. Para Next.js, o destaque é o suporte a worktrees do Git: cada agente trabalha em uma cópia isolada do repositório, evitando que alterações em componentes compartilhados se sobrescrevam. A revisão automática feita por um segundo modelo ajuda a pegar violações como `"use client"` em Server Component antes do merge. Os checkpoints por turno permitem desfazer rapidamente uma alteração que quebra o build ou os testes. Já os orçamentos de tokens controlam tarefas longas e impedem que um agente consuma todo o limite em uma refatoração mal direcionada. Para coordenação entre agentes, vale conhecer os padrões em [Equipe de agentes de IA: gerente, papéis e repasses](/pt/blog/ai-agent-team/).

## Conclusão

O Gemini CLI pode ser um par de programação eficiente em projetos Next.js, desde que você forneça contexto claro no `GEMINI.md`, mantenha os comandos de qualidade disponíveis e revise diffs pequenos. A chave é tratar o agente como um executor que segue convenções bem definidas, não como um substituto para decisões de arquitetura. Com esse fluxo, você acelera tarefas repetitivas e reduz o tempo gasto com erros de build e configuração. Se quiser explorar mais a colaboração com agentes, veja [Pair programming com IA: como trabalhar com um agente](/pt/blog/ai-pair-programming/).

## Perguntas frequentes

**O Gemini CLI funciona com App Router e Pages Router?** Sim. No Next.js, ele entende a estrutura de pastas se você descrever no GEMINI.md onde cada router está e as regras de Server e Client Components. Em projetos mistos, defina qual pasta é legada e qual segue o App Router.

**Preciso do GEMINI.md para usar o Gemini CLI em um projeto Next.js?** Não é obrigatório, mas é recomendado. O arquivo orienta o agente sobre comandos, convenções de pasta e regras específicas, reduzindo alterações erradas em Server Components, route handlers e cache.

**Como evitar que o Gemini CLI quebre Server Components?** Descreva no GEMINI.md que componentes sem interatividade devem ser Server Components e que "use client" só deve ser usado quando necessário. Peça revisão de diff e rode o build após cada mudança.

**Dá para usar o Gemini CLI com Vitest, Jest e Playwright no Next.js?** Sim. Configure os scripts de teste no package.json e liste os comandos no GEMINI.md. O agente pode rodar os testes, interpretar falhas e ajustar mocks ou seletores.

---

**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/