Tutorial · 2026-07-12

Criando uma API Node.js Completa com Agentes de IA

Tutorial passo a passo para criar uma API Node.js completa usando Claude Code e Codex como assistentes de desenvolvimento, do setup ao deploy.

Construir uma API Node.js completa do zero envolve decisões de arquitetura, configuração de banco de dados, criação de rotas, implementação de autenticação e testes. Quando você adiciona agentes de IA ao processo, cada uma dessas etapas ganha um acelerador poderoso. Neste tutorial, você vai aprender a criar uma API Node.js com agentes de IA usando Claude Code e Codex de forma orquestrada no Windows 11.

O que vamos construir

Vamos desenvolver uma API de gerenciamento de projetos com Node.js, Express e Prisma. O sistema terá:

CRUD de projetos e tarefas
Autenticação JWT com refresh token
Validação de dados com Zod
Banco de dados PostgreSQL via Prisma ORM
Testes unitários e de integração com Jest
Documentação automática com Swagger

Imagem sugerida: Diagrama de arquitetura mostrando cliente, API Express, Prisma ORM, PostgreSQL e os agentes Claude Code e Codex atuando em cada camada.

Setup do projeto com Claude Code

O primeiro passo é configurar o ambiente do projeto. Com Claude Code, isso leva segundos.

Inicialização

Abra o terminal e execute:

mkdir projeto-manager-api cd projeto-manager-api npm init -y

Em seguida, peça ao Claude Code para configurar as dependências:

claude "Crie um projeto Node.js com Express, Prisma e TypeScript para uma API de gerenciamento de projetos. Instale express, cors, helmet, morgan, prisma, @prisma/client, jsonwebtoken, bcryptjs, zod. Configure TypeScript com ts-node-dev. Crie estrutura de pastas: src/routes, src/controllers, src/middleware, src/services, src/utils, tests. Configure Prisma com PostgreSQL. Crie .env.example com DATABASE_URL, JWT_SECRET, PORT."

Claude Code analisa as dependências, cria a estrutura de diretórios e configura o schema Prisma. Em menos de um minuto, a espinha dorsal do projeto está pronta.

Estrutura resultante

projeto-manager-api/ ├── src/ │ ├── routes/ │ ├── controllers/ │ ├── middleware/ │ ├── services/ │ └── utils/ ├── prisma/ │ └── schema.prisma ├── tests/ ├── .env.example ├── tsconfig.json └── package.json

Modelagem do banco com Codex

Com a estrutura pronta, vamos usar Codex para gerar o schema do banco de dados — uma tarefa de alto volume e baixa complexidade onde o agente da OpenAI se destaca.

Schema Prisma

Peça ao Codex para gerar o schema completo:

opencode "Gere o schema Prisma completo para PostgreSQL de um sistema de gerenciamento de projetos com os seguintes modelos: Model User: - id: String (UUID) - name: String - email: String (unique) - password: String (hash) - role: enum (ADMIN, MANAGER, MEMBER) - avatar: String? - createdAt: DateTime - updatedAt: DateTime - projects: relation Project[] - tasks: relation Task[] Model Project: - id: String (UUID) - name: String - description: String? - status: enum (PLANNING, ACTIVE, COMPLETED, ARCHIVED) - ownerId: String (FK User) - owner: relation User - tasks: relation Task[] - createdAt: DateTime - updatedAt: DateTime Model Task: - id: String (UUID) - title: String - description: String? - status: enum (TODO, IN_PROGRESS, REVIEW, DONE) - priority: enum (LOW, MEDIUM, HIGH, CRITICAL) - projectId: String (FK Project) - project: relation Project - assigneeId: String? (FK User) - assignee: relation User? - dueDate: DateTime? - createdAt: DateTime - updatedAt: DateTime Inclua @map para snake_case e @@map para nomes de tabela."

Codex gera o schema completo com todos os enums, relações e índices — sem erros de digitação ou campos esquecidos.

Rotas e controllers com Claude Code

Claude Code é o agente ideal para criar rotas e controllers porque entende o contexto completo do projeto.

Autenticação

claude "Crie src/middleware/auth.ts com funções generateToken, verifyToken, authenticate e requireAdmin. Use JWT com expiração de 24h para access token e 7d para refresh token. O middleware authenticate deve extrair o token do header Authorization Bearer, verificar e anexar userId ao request. O middleware requireAdmin deve verificar se o usuário tem role ADMIN."

Controllers

claude "Crie src/controllers/UserController.ts com métodos register, login, refreshToken, getProfile, updateProfile, listUsers, deleteUser. Cada método deve validar entrada com Zod, usar services para lógica de negócio e retornar respostas padronizadas com { success, data, error }."

Repita o processo para projetos e tarefas:

claude "Crie src/controllers/ProjectController.ts e src/controllers/TaskController.ts com CRUD completo. ProjectsController deve ter create, list, getById, update, delete. TaskController deve ter create, list, getById, update, delete e reorder (para drag-and-drop de prioridades). Use services para separar lógica de negócio dos controllers."

Rotas centralizadas

claude "Crie src/routes/index.ts agrupando todas as rotas: /auth (register, login, refresh), /users (CRUD protegido), /projects (CRUD protegido), /tasks (CRUD protegido). Aplique middleware authenticate nas rotas protegidas e requireAdmin nas rotas de deleção."

Testes automatizados

Nenhuma API está completa sem testes. Vamos usar Codex para gerar a suíte de testes e Claude Code para corrigir falhas.

Testes com Codex

opencode "Crie tests/integration/auth.test.ts com testes para: 1. POST /auth/register — deve criar usuário (201), rejeitar email duplicado (409), rejeitar senha fraca (400) 2. POST /auth/login — deve retornar token (200), rejeitar credenciais inválidas (401) 3. POST /auth/refresh — deve renovar token (200), rejeitar token expirado (401) Use supertest e banco de testes in-memory."

Correção automática

Após gerar os testes, execute:

npm test

Se houver falhas, peça ao Claude Code para corrigir:

claude "Analise a saída dos testes, identifique as falhas e corrija os arquivos de implementação para que todos os testes passem. Não modifique os arquivos de teste."

Pipeline de deploy

Para finalizar, vamos configurar o deploy com Claude Code.

claude "Crie Dockerfile multi-stage para o projeto: stage 1 com node:20-alpine para build (npm ci, npm run build), stage 2 com node:20-alpine apenas com dist e node_modules. Crie docker-compose.yml com serviços da API na porta 3000 e PostgreSQL. Crie também um workflow GitHub Actions que roda testes no push e faz deploy no merge para main."

Com isso, sua API Node.js com agentes de IA está completa, testada e pronta para produção — construída em horas, não dias.

FAQ — Perguntas Frequentes

Preciso saber Node.js para usar agentes na criação de APIs?

Sim, conhecimento de Node.js é essencial. Os agentes geram o código, mas você precisa entender a estrutura para revisar segurança, corrigir bugs e adaptar à sua arquitetura. O agente é um acelerador, não um substituto.

Qual agente é melhor para criar APIs Node.js?

Claude Code é ideal para estruturar rotas, controllers e refatorações por entender o contexto do projeto. Codex é mais rápido para gerar código padronizado como models, schemas de validação e testes. A melhor estratégia é usar os dois em orquestração.

Agentes de IA geram código seguro para APIs?

O código gerado segue boas práticas comuns como hash de senhas com bcrypt, JWT com expiração e validação de entrada com express-validator. No entanto, sempre revise middlewares de autenticação e sanitização antes de ir para produção.

Quanto tempo economiza usar agentes para desenvolver uma API?

Em projetos de porte médio (15-20 endpoints), agentes de IA reduzem o tempo de 3-4 dias para 6-8 horas — uma economia de 60% a 75%. A maior economia está na geração de código repetitivo e correção de bugs.

É possível usar Claude Code e Codex simultaneamente no mesmo projeto Node.js?

Sim. Com o Orquestra, você conecta Claude Code e Codex no mesmo canvas, define papéis para cada agente e sincroniza o diretório do projeto. Um agente cria controllers enquanto o outro gera testes — tudo em paralelo sem conflito de edição.

Comece a desenvolver APIs Node.js com agentes hoje

Neste tutorial, você aprendeu a criar uma API Node.js com agentes de IA usando Claude Code e Codex de forma orquestrada. Do setup inicial ao deploy, cada etapa foi acelerada pelos agentes, mantendo a qualidade e a segurança do código.

O segredo está na orquestração: Claude Code para contexto e arquitetura, Codex para volume e repetição. Juntos, eles cobrem o espectro completo do desenvolvimento de APIs modernas.

Quer levar essa orquestração para o próximo nível? O Orquestra foi construído exatamente para isso: conectar Claude Code, Codex e outros agentes no mesmo canvas infinito no Windows 11. Baixe o Orquestra e comece seu teste grátis de 7 dias.

Links internos recomendados

APIs REST com Agentes de IA: Tutorial Completo — tutorial complementar sobre desenvolvimento de APIs REST com Claude Code e Codex
TypeScript React Agentes IA: Tutorial de Componentes — crie o frontend que consome sua API
Testes Automatizados com Agentes de IA — aprofunde-se em testes unitários, integração e E2E

Pronto para orquestrar seus agentes?

Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Grátis por 7 dias.

Começar teste grátis