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

O 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:

# 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:

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. 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.