# Codex e Next.js: guia prático para usar o agente

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

Aprenda a configurar o Codex em projetos Next.js: AGENTS.md, loop de trabalho, testes e armadilhas de Server Components para o agente de terminal.

**Resumo:**

- O Codex acelera tarefas repetitivas em Next.js, mas exige um AGENTS.md específico para respeitar Server e Client Components.
- Use um loop curto com passos pequenos, testes e revisão do diff para validar cada mudança do agente.
- Automatize revisão e paralelismo com worktrees para reduzir riscos em refatorações de rotas e componentes.

O [Codex](/pt/agents/codex/) é um agente de linha de comando que, ao ser iniciado com `codex` na pasta do projeto, lê o contexto do repositório e executa tarefas de código. Em um projeto Next.js, ele é útil para refatorar componentes, criar Route Handlers, ajustar metadata e até escrever testes, desde que o projeto esteja preparado com instruções claras. Este guia mostra o fluxo prático para tirar proveito do agente sem perder o controle sobre Server Components, cache e tipagem.

## Por que o Codex se encaixa bem em projetos Next.js

Next.js mistura servidor e cliente de forma implícita, o que costuma gerar erros de hidratação ou vazamento de segredos quando um agente não conhece as convenções do framework. O Codex, por ser um agente que opera no terminal com acesso direto aos arquivos, consegue aplicar mudanças em várias partes do projeto — por exemplo, alterar uma Server Action, atualizar o componente e ajustar o teste na mesma sessão. Isso reduz a fricção de alternar entre arquivos manualmente. Como ele lê o AGENTS.md, dá para codificar as regras específicas do Next.js, como “não importe `headers` dentro de um Client Component sem necessidade” ou “use `revalidatePath` depois de mutações”. O resultado é um agente que respeita a arquitetura do projeto em vez de gerar código genérico.

## Preparando o projeto para o agente

Antes de rodar `codex`, o projeto precisa falar a língua do agente. O arquivo AGENTS.md na raiz é o ponto de entrada: ele define comandos, estrutura de pastas e regras que o agente deve seguir. Em um projeto Next.js, vale incluir os comandos reais de build, lint e teste, além de convenções sobre App Router e Server Components. Um exemplo curto:

```markdown
# AGENTS.md

## Comandos
- Instalar: npm install
- Desenvolver: npm run dev
- Build: npm run build
- Lint: npm run lint
- Testar: npm run test
- Testar e2e: npm run test:e2e

## Estrutura
- `app/` usa App Router; `components/` guarda componentes compartilhados.
- Server Components por padrão; só adicione `'use client'` quando necessário.
- Route Handlers em `app/api/`; retorne `Response`, não use `req`/`res` do Express.

## Regras
- Não misture lógica de servidor no cliente.
- Use `fetch` com `next: { revalidate }` para dados que mudam pouco.
- Testes de unidade em `__tests__/` com Vitest; testes E2E em `e2e/` com Playwright.
- Rode `npm run lint` e `npm run typecheck` antes de finalizar.
```

Além disso, mantenha o arquivo curto e atualizado: regras genéricas demais fazem o agente ignorar pontos críticos. Se o projeto usa Pages Router, adapte a seção de estrutura para `pages/` e `getServerSideProps`. Se usa ESLint com regras específicas, mencione o comando e a pasta de configuração. O importante é que o agente saiba como validar o próprio trabalho.

## Um loop de trabalho eficiente

O melhor uso do Codex em Next.js segue um ciclo curto: planejar, executar um passo pequeno, rodar testes/lint e revisar o diff. Não peça para o agente “criar o sistema de autenticação completo” de uma vez; ele tende a gerar muitos arquivos e esconder decisões erradas. Em vez disso, divida a mudança em etapas verificáveis. Exemplos de prompts úteis:

- “Crie um Route Handler em `app/api/contact/route.ts` que valide o corpo com Zod, salve no banco e retorne 201. Inclua teste com Vitest e rode `npm run test`.”
- “Adicione metadata estática e `generateMetadata` para a página `app/blog/[slug]/page.tsx`, lendo o post do filesystem. Mostre o diff antes de aplicar.”
- “Refatore o componente `app/dashboard/page.tsx` para extrair a lista de cards em um Server Component separado, mantendo a tipagem estrita.”
- “Atualize o formulário em `components/NewsletterForm.tsx` para usar Server Action com `useActionState`, trate erro e mostre mensagem de sucesso.”
- “Rode `npm run lint`, corrija as violações e depois rode `npm run test:e2e` para a rota `/checkout`; se falhar, explique a causa e ajuste apenas o necessário.”

Depois de cada resposta, revise o `git diff`. Não aceite mudanças em arquivos que não fazem parte da tarefa; peça para reverter ou explicar. Rodar os testes e o lint na mesma interação fecha o ciclo e evita que um erro simples se propague para as próximas etapas.

## Tarefas típicas e pontos de atenção

O Codex lida bem com tarefas mecânicas e bem delimitadas: criar Route Handlers, ajustar metadata, converter um componente em Client Component, extrair funções utilitárias, escrever mocks e atualizar testes. Em projetos grandes, ele também ajuda a mover código entre páginas e componentes, desde que as convenções estejam no AGENTS.md. Uma tabela ajuda a traduzir a tarefa em um prompt mais preciso:

| Tarefa | Prompt sugerido |
|---|---|
| Criar API route com validação | “Crie `app/api/signup/route.ts` com Zod, trate 400 e 409, e teste o handler com Vitest.” |
| Corrigir erro de hidratação | “O componente `app/price/page.tsx` causa hydration mismatch; encontre a causa, explique e corrija usando `suppressHydrationWarning` apenas se for adequado.” |
| Ajustar cache e revalidação | “Mude a busca em `app/products/page.tsx` para usar `fetch` com `next: { revalidate: 60 }` e adicione um teste que confirma o cache.” |
| Migrar de Pages para App Router | “Migre `pages/about.tsx` para `app/about/page.tsx`, preserve o conteúdo e atualize os imports de `next/link` se necessário.” |

Porém, há armadilhas específicas do Next.js que merecem atenção redobrada. A mais comum é o agente inserir `"use client"` em um componente que poderia continuar no servidor, inchando o bundle e expondo dados indevidos. Outra é manipular `headers`, `cookies` ou `searchParams` como se fossem síncronos; no App Router, essas APIs são dinâmicas e exigem `await` ou funções assíncronas. O agente também pode sugerir `useEffect` para buscar dados no cliente quando o ideal seria buscar no servidor. Fique atento a imports de bibliotecas server-only em Client Components e a chamadas de `fetch` sem `cache: 'no-store'` quando a rota deve ser dinâmica. Em Route Handlers, erros como retornar o objeto do Prisma sem serializar ou não definir `export const runtime = 'edge'` quando necessário são comuns. Revise sempre o diff em arquivos de configuração como `next.config.ts` e `middleware.ts`; mudanças ali afetam o build inteiro.

## Testes e verificação com o agente

O Codex só é confiável se o projeto tiver uma malha de verificação que ele mesmo possa executar. Configure Vitest ou Jest para testes unitários, Playwright para testes de ponta a ponta e ESLint para consistência. No AGENTS.md, deixe os comandos explícitos, como no exemplo acima. Quando pedir uma mudança, exija que o agente rode os testes relevantes e mostre o resultado. Para fluxos de UI, use Playwright para cobrir navegação real; o agente pode escrever specs, mas é bom revisar seletores e esperas, pois ele tende a usar `waitForTimeout` onde um `expect` assíncrono seria mais robusto. Uma prática que reduz retrabalho é pedir uma revisão automatizada após a sessão: você pode configurar um fluxo em que outro modelo revisa o código gerado e aponta problemas com referência de arquivo e linha, como descrito em [Revisão de código com IA: confira o código dos agentes](/pt/blog/ai-code-review/). Isso complementa o olho humano, especialmente em mudanças que cruzam Server e Client Components.

## Rodando vários agentes no mesmo projeto com AgentVera

Em projetos Next.js com várias frentes — layout, API routes, testes — o AgentVera roda vários agentes de terminal lado a lado, cada um na sua própria janela real. O uso de worktrees do Git evita que agentes paralelos sobrescrevam arquivos, essencial quando um mexe em `app/` e outro em `app/api/`. A revisão automática ao fim de cada turno aponta problemas com link para arquivo e linha, ajudando a pegar erros de hidratação ou vazamento de server-only. Checkpoints permitem desfazer um turno inteiro e repetir a sessão passo a passo; limites de token por agente evitam que uma exploração longa estoure o orçamento.

## Considerações finais

O Codex em um projeto Next.js funciona melhor quando o AGENTS.md é específico, o loop de trabalho é curto e a verificação automatizada está no lugar. Não espere que o agente acerte Server Components de primeira; em vez disso, use o diff e os testes como rede de segurança. Com esses cuidados, ele vira um acelerador real para tarefas diárias, de Route Handlers a testes de interface, sem transformar o repositório em uma caixa-preta.

## Perguntas frequentes

**Como usar o Codex em um projeto Next.js?** Inicie o agente com codex na raiz do projeto e mantenha um arquivo AGENTS.md com comandos, estrutura de pastas e regras do Next.js. Peça tarefas pequenas e revise o diff a cada etapa.

**O Codex entende Server Components e Client Components?** Sim, se as regras estiverem no AGENTS.md. Sem instruções, ele pode adicionar 'use client' desnecessariamente ou usar APIs de servidor no cliente; por isso vale incluir convenções explícitas.

**Quais comandos devo colocar no AGENTS.md para Next.js?** Inclua npm run build, npm run lint, npm run test e npm run test:e2e, além de convenções de App Router e Route Handlers. Isso permite que o agente valide o próprio trabalho.

**O Codex consegue escrever testes para componentes Next.js?** Sim, ele escreve testes unitários com Vitest/Jest e testes E2E com Playwright quando instruído. É importante revisar seletores e esperas e exigir que ele rode os testes antes de finalizar.

---

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