O 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.
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:
# 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.tsxque usegenerateStaticParamspara gerar as rotas estáticas a partir delib/produtos.tse renderize os detalhes com um componente de servidor.” - “Refatore o componente
components/Carrinho.tsxpara usar'use client'apenas nos elementos interativos, mantendo os cálculos de preço como funções puras emlib/preco.ts.” - “Adicione um route handler
app/api/checkout/route.tsque valide o payload com Zod e retorneNextResponse.jsoncom 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:e2ee 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 lintpara as regras do ESLint, incluindo as específicas do Next.js.npx tsc --noEmitpara checagem de tipos, que evita problemas entre Server e Client Components.npm run buildpara 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.
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.