Como criar um backend de API REST com o Claude Code: guia passo a passo (2026)

por Jasmine, uma dev que publica backends com o Claude Code todos os dias.

Por que usar o Claude Code para criar um backend de API REST?

O Claude Code é uma CLI agêntica: ela lê o seu repositório inteiro, gera vários arquivos de uma vez e depois roda comandos e testes para conferir o próprio trabalho (segundo a documentação oficial da Anthropic, atualizada em 2026). É exatamente essa característica que a faz encaixar melhor no trabalho de backend do que um chatbot de colar-e-copiar. Uma API REST é, no fundo, uma pilha de código repetitivo - models, migrations, controllers de CRUD, validação, testes, docs. É um trabalho demorado e de baixa criatividade, e é justamente aí que a IA mais acelera você.

O maior ganho é a velocidade de scaffolding. Em vez de digitar à mão seis endpoints quase idênticos, você descreve o recurso uma única vez e o Claude Code gera tanto a camada de dados quanto a camada REST, e ainda a executa. Ele também é bom nas partes "chatas", como escrever um schema Zod ou Pydantic que combine com o seu model, ou montar uma suíte de testes para cada rota.

Mas aqui está a parte que você tem que guardar para si: você continua sendo a pessoa que revisa. O Claude Code não entende o seu contexto de segurança - ele tende a entregar padrões frouxos (falta de authz numa rota, segredos no código, validação só para inglês ver). Para qualquer coisa que envolva dinheiro ou permissões, o que a IA produz é apenas um rascunho forte. Se a ferramenta é nova para você, leia antes o que é o Claude Code para ver como ela funciona antes de entregar a ela um trabalho de backend.

O que preparar antes de começar

Um checklist para rodar antes de abrir o Claude Code - deixe isto pronto para que a sessão inteira flua:

• Claude Code instalado e funcionando no seu terminal - veja o guia de instalação do Claude Code se ainda não configurou.
• Runtime: Node 20+ (para Express) ou Python 3.11+ (para FastAPI).
• Banco de dados: PostgreSQL (nível produção) ou SQLite (dev rápido, sem servidor).
• Um repositório Git já iniciado com git init - assim você revisa cada diff e reverte quando precisar.
• Um arquivo CLAUDE.md que deixa claras as convenções do projeto - essa é a maior diferença entre uma saída limpa e uma bagunça.

Coloque o CLAUDE.md na raiz do repositório e o Claude Code o lê automaticamente a cada sessão. Para um backend, declare de cara as convenções de camadas, a validação e o formato de erro, para você não se repetir:

# CLAUDE.md - backend conventions

## Architecture
- Three layers: routes -> controllers -> services. No DB queries in controllers.
- ORM: Prisma. All queries go through a service; no raw SQL unless required.

## Validation & errors
- Validate input with Zod at the top of every handler.
- Errors return JSON: { "error": { "code": string, "message": string } }
- Status codes: 200/201 success, 400 validation, 401 unauthenticated,
 403 forbidden, 404 not found, 500 server error.

## Security (REQUIRED, do not skip)
- NEVER hardcode secrets. Read them from process.env.
- Every write/update/delete route must pass through auth middleware.
- Never return sensitive fields (passwordHash) in a response.

## Tests
- Every endpoint has at least 1 happy-path test + 1 error test (Jest + Supertest).

Com esse único arquivo, a qualidade do que o Claude Code gera sobe um nível - porque agora ele tem um "contrato" a seguir, em vez de adivinhar o seu estilo.

Escolhendo uma stack - Node/Express ou Python/FastAPI?

Não existe uma stack "certa" única, mas algumas se encaixam melhor no jeito como o Claude Code trabalha. Uma comparação rápida de quatro escolhas populares:

Para este guia inteiro eu vou de Express + Prisma + PostgreSQL: JS em primeiro lugar, muito usado, e o Prisma dá segurança de tipos suficiente sem o peso do NestJS. Se o seu time é de Python, FastAPI + SQLAlchemy também é excelente - os type hints do Pydantic ajudam de verdade o Claude Code a cometer menos erros de tipo. O ponto-chave: escolha uma stack e fique com ela no build inteiro. Não deixe o Claude Code "escolher sozinho" no meio do projeto - essa é a receita de uma mistura híbrida que ninguém quer manter.

Etapa 1 - Planeje endpoints e schema com o Claude Code

Não diga ao Claude Code "construa uma API para mim" e o deixe sair codando. Comece pelo planejamento: peça que ele faça um brainstorm dos recursos, endpoints e do schema do banco primeiro, para você aprovar o design antes de existir uma única linha de código. Um prompt para copiar e colar:

I want to build a REST API for managing "tasks" with Express + Prisma + PostgreSQL.
Before writing code, propose:
1. The endpoint list (method + path + description) for tasks CRUD.
2. The Task table schema (fields, types, constraints).
3. A sample response shape for each endpoint.
Present it as a table. DO NOT code yet - I want to review first.

O Claude Code devolve uma tabela de endpoints assim, para você dar o aval:

Revise com cuidado aqui: os campos estão completos, você precisa de um enum de status, a paginação é por cursor ou por offset? Corrigir o design em palavras é muito mais barato do que corrigir código gerado. É também aqui que a mentalidade de planejar antes de codar com o Claude Code compensa.

Etapa 2 - Gere o esqueleto do projeto e a camada de dados

Com o design travado, agora você deixa o Claude Code gerar o esqueleto. O prompt:

Scaffold an Express + TypeScript project per the plan we just approved:
- Install express, prisma, @prisma/client, zod, dotenv.
- Create the Prisma schema for the Task model as designed.
- Generate the first migration and a seed file with 3 sample tasks.
- Folder structure: src/routes, src/controllers, src/services, src/lib.
After creating it, STOP so I can read the migration before it runs.

O schema Prisma resultante deve ficar assim:

// prisma/schema.prisma
model Task {
 id String @id @default(uuid())
 title String
 detail String?
 status Status @default(TODO)
 createdAt DateTime @default(now())
 updatedAt DateTime @updatedAt
}

enum Status {
 TODO
 DOING
 DONE
}

Leia a migration antes de rodá-la - isso não é conselho de rotina. O Claude Code às vezes adiciona uma coluna a mais, define um default errado ou pula um índice necessário. Rode npx prisma migrate dev --name init só depois de entender o diff. Se quiser se aprofundar nessa parte, veja usar o Claude Code com o seu banco de dados.

Etapa 3 - Construa os endpoints CRUD um recurso de cada vez

A regra de ouro: um endpoint de cada vez, não "construa todos de uma vez". Quando você pede cinco rotas de uma tacada ao Claude Code, ele tende a se perder e você sofre para revisar. Faça uma, revise, faça o commit e passe para a próxima. Comece por POST e GET:

// src/controllers/task.controller.ts
import { Request, Response } from "express";
import { z } from "zod";
import * as taskService from "../services/task.service";

const createSchema = z.object({
 title: z.string().min(1).max(200),
 detail: z.string().max(2000).optional(),
 status: z.enum(["TODO", "DOING", "DONE"]).optional(),
});

export async function createTask(req: Request, res: Response) {
 const parsed = createSchema.safeParse(req.body);
 if (!parsed.success) {
 return res.status(400).json({
 error: { code: "VALIDATION_ERROR", message: parsed.error.message },
 });
 }
 const task = await taskService.create(parsed.data);
 return res.status(201).json(task);
}

export async function listTasks(req: Request, res: Response) {
 const tasks = await taskService.findAll();
 return res.status(200).json(tasks);
}

Duas coisas para conferir na revisão: o formato da resposta combina com o seu CLAUDE.md (o objeto de erro está na forma certa) e o código de status está semanticamente correto (201 para criação, não 200). É aqui que o Claude Code fica desleixado - ele costuma devolver 200 para tudo a menos que você especifique.

O Claude Code usa skills para padronizar esses padrões, então, se você tem a sua própria skill de backend, a saída fica bem mais consistente do que com um prompt cru.

Etapa 4 - Autenticação e validação (JWT ou API key)

A maioria dos tutoriais para em "adicione JWT se precisar". Não é suficiente. Aqui está um middleware JWT de verdade que protege as rotas de escrita/atualização/exclusão:

// src/lib/auth.ts
import { Request, Response, NextFunction } from "express";
import jwt from "jsonwebtoken";

export function requireAuth(req: Request, res: Response, next: NextFunction) {
 const header = req.headers.authorization;
 if (!header?.startsWith("Bearer ")) {
 return res.status(401).json({
 error: { code: "UNAUTHORIZED", message: "Missing token" },
 });
 }
 try {
 const payload = jwt.verify(header.slice(7), process.env.JWT_SECRET!);
 (req as any).user = payload;
 next();
 } catch {
 return res.status(401).json({
 error: { code: "INVALID_TOKEN", message: "Invalid token" },
 });
 }
}

Acople-o às rotas de escrita: router.post("/tasks", requireAuth, createTask). Para uma API interna simples, comparar com uma API key constante também basta - mas sempre compare com uma função de tempo constante, nunca com um === pelado.

Revisão manual obrigatória: o Claude Code tende a entregar padrões fracos - esquecer de acoplar o requireAuth na rota certa, deixar o JWT_SECRET cair num valor fixo no código ou pular a verificação de propriedade (o usuário A edita a tarefa do usuário B). Depois que a IA gera o middleware, volte tudo à mão: toda rota sensível tem autenticação, o segredo é lido do env e a autorização (não só a autenticação) está realmente correta?

Etapa 5 - Teste a API (unindo TDD com IA)

O Claude Code não só escreve os testes, ele roda os testes e o curl sozinho para verificar - essa é a verdadeira vantagem agêntica. Prompt: "Escreva testes Jest + Supertest para POST /tasks e GET /tasks, cobrindo o caminho feliz e um caso de erro de validação, e depois rode-os." Um teste de exemplo:

// tests/task.test.ts
import request from "supertest";
import app from "../src/app";

describe("POST /tasks", () => {
 it("creates a valid task and returns 201", async () => {
 const res = await request(app)
 .post("/tasks")
 .set("Authorization", `Bearer ${process.env.TEST_TOKEN}`)
 .send({ title: "Write post F1" });
 expect(res.status).toBe(201);
 expect(res.body.title).toBe("Write post F1");
 });

 it("returns 400 when title is missing", async () => {
 const res = await request(app)
 .post("/tasks")
 .set("Authorization", `Bearer ${process.env.TEST_TOKEN}`)
 .send({});
 expect(res.status).toBe(400);
 });
});

Verifique à mão com curl para ver a resposta JSON real:

$ curl -s -X POST http://localhost:3000/tasks \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"title":"Write post F1","status":"DOING"}'

{
 "id": "a3f1c9e2-...-8b71",
 "title": "Write post F1",
 "detail": null,
 "status": "DOING",
 "createdAt": "2026-08-09T04:12:30.882Z",
 "updatedAt": "2026-08-09T04:12:30.882Z"
}

Fazer o Claude Code escrever os testes antes de implementar é o jeito eficaz de aplicar TDD com IA: os testes funcionam como o "contrato" e a IA coda até eles ficarem verdes.

Etapa 6 - Segurança de produção e tratamento de erros

Essa é a parte que os concorrentes deixam quase em branco. Antes de expor a API à internet, peça ao Claude Code para adicionar as camadas a seguir - mas revise o checklist você mesma:

• Rate limiting: express-rate-limit para barrar força bruta e abuso (digamos, 100 req/min/IP).
• CORS: coloque origens específicas na whitelist; não deixe origin: "*" numa API autenticada.
• Env/segredos: cada chave via .env, adicione .env ao .gitignore, entregue um template .env.example.
• Validação de entrada: já tratada pelo Zod em cada handler - nunca confie nos dados do cliente.
• Handler central de erros: um middleware final que captura todos os erros e não vaza stack traces nas respostas de produção.
• Helmet: define os headers HTTP de segurança básicos.

Um checklist OWASP curtinho para passar: alguma injeção (o Prisma bloqueia SQLi com queries parametrizadas), algum controle de acesso quebrado (confira a authz em cada rota), alguma exposição de dados sensíveis (não retorne campos extras). Se quiser que o próprio Claude Code procure brechas, veja como rodar uma auditoria de segurança com o Claude Code.

Etapa 7 - Publique a API em uma URL de verdade

Eu uso o Railway nesta demonstração porque ele já provisiona o Postgres de fábrica e publica a partir do Git em poucos minutos. Os passos:

1. Faça o push do repositório para o GitHub.
2. No Railway, crie um projeto a partir do repositório e adicione um serviço PostgreSQL - ele gera automaticamente a DATABASE_URL.
3. Defina as variáveis de ambiente de produção: JWT_SECRET, DATABASE_URL, NODE_ENV=production.
4. Defina o comando de build npx prisma migrate deploy && npm run build e o comando de start npm start.

Se quiser algo mais portátil (que rode também no Render, Fly.io ou numa VPS), adicione um Dockerfile mínimo:

# Dockerfile
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx prisma generate && npm run build
EXPOSE 3000
CMD ["npm", "start"]

Depois de publicar, acesse o endpoint pela URL ao vivo para confirmar que a migration rodou e que o ambiente está correto. O detalhe plataforma por plataforma está no guia sobre publicar apps com o Claude Code.

Indo mais rápido: o AgentKit traz a skill ak-backend-development

Uma linha para evitar confusão: o AgentKit aqui é um pacote de kit para o Claude Code (agentkit.best, a CLI ak) - não o AgentKit da OpenAI (Agent Builder/ChatKit, lançado em 06/10/2025). Mesmo nome, coisas completamente diferentes.

Todas as 7 etapas acima pedem que você declare convenções no CLAUDE.md e reafirme os padrões a cada sessão. O AgentKit para Claude Code (20% de desconto pelo link) empacota a skill ak-backend-development que, segundo o anúncio, dá suporte a Node/Python/Go (NestJS, FastAPI, Django), autenticação OAuth/JWT, um checklist de segurança OWASP e Docker/K8s. Em outras palavras, o Claude Code roda essas mesmas 7 etapas contra convenções-padrão prontas, então você não reconstrói o "contrato" do zero em cada projeto.

Opinião honesta: o kit não é obrigatório - você consegue fazer tudo isso à mão, e este artigo acabou de provar. O kit só economiza esforço de setup se você cria backends com frequência. O Engineer Kit custa $99 (o site não menciona mensalidade recorrente), com "garantia de devolução do dinheiro" e "atualizações vitalícias". Veja o que tem dentro do Engineer Kit do AgentKit para avaliar antes de comprar.

Limites reais e quando você precisa revisar à mão

Esta é a seção que nenhum concorrente tem, e é a mais importante. Depois de muitos projetos de backend com o Claude Code, estes são os modos de falha que eu vivo tendo que pegar:

• Imports/chamadas de ORM erradas: chamar um método Prisma que não existe, ou importar a versão errada do pacote - o código parece certo mas quebra em runtime.
• Falta de authz numa rota: tem authn (quem você é) mas pula a authz (se você pode) - um usuário edita os dados de outro.
• Validação frouxa: valida o título mas esquece o limite de tamanho, esquece de sanitizar, deixa passar tipos de dado estranhos.
• Consultas N+1: um loop batendo no banco por item em vez de uma única query - tranquilo em dev, cai em produção.
• Segredos fixos no código: um JWT_SECRET ou string de conexão jogado direto no código como fallback.
• "Parece que roda" mas a lógica de negócio está errada: compila, o teste do caminho feliz está verde, mas o cálculo ou a lógica de estado está errada - só quem conhece o domínio vai perceber.

Minha regra: Claude Code para boilerplate, humanos para revisar autenticação, segurança e lógica de dinheiro. A IA gera 80% do volume muitas vezes mais rápido; os 20% restantes - justamente a parte de alto risco - é onde você não pode largar as mãos. Isso não é uma fraqueza da ferramenta, é como usá-la do jeito certo.

Perguntas frequentes (FAQ)

O Claude Code está pronto para produção em backends?

Não de forma totalmente automatizada. O Claude Code gera código real, funcional e bem estruturado, mas a autenticação, as permissões, a segurança e a lógica de negócio precisam de uma revisão humana cuidadosa antes da produção. Trate a saída como um rascunho de alta qualidade, não como versão final.

Preciso saber programar ou um iniciante consegue?

Você precisa conseguir ler código e entender HTTP/REST e bancos de dados em nível básico para revisar a saída. Um iniciante ainda consegue uma API funcionando, mas vai penar para achar os bugs de segurança ou de lógica que o Claude Code introduz - então aprenda junto, não entregue de olhos fechados.

Ele consegue construir GraphQL ou gRPC?

Sim. Este guia demonstra REST por ser o mais comum, mas o Claude Code também constrói GraphQL (Apollo) e gRPC. Os princípios são idênticos: planeje o schema primeiro, construa em pedaços e revise você mesma a autenticação/segurança.

Qual stack combina melhor com o Claude Code?

Express + Prisma (JS) e FastAPI + SQLAlchemy (Python) são os dois melhores encaixes - muitos padrões familiares e segurança de tipos suficiente para reduzir alucinações. O FastAPI leva vantagem porque seus type hints diminuem os erros de tipo.

O código que o Claude Code gera é seguro?

Não por padrão. O Claude Code tende a entregar padrões frouxos: falta de authz, segredos no código, validação rasa. Você tem que rodar o checklist de segurança por conta própria (rate limiting, CORS, env, OWASP) e revisar cada rota sensível antes de publicar.

Quanto tempo leva uma API CRUD básica?

Cerca de 30 a 60 minutos para uma API REST CRUD completa com autenticação básica e testes, incluindo o tempo de revisão. Scaffolding e boilerplate são rápidos; o tempo de verdade vai para revisar autenticação, segurança e ajustar a lógica de negócio.

Conclusão e próximos passos

Recapitulando as 7 etapas: planejar endpoints e schema -> gerar o esqueleto do projeto e a camada de dados -> construir o CRUD um recurso de cada vez -> adicionar autenticação/validação -> testar -> reforçar para produção -> publicar. O Claude Code cuida do boilerplate; você fica com a revisão de autenticação e lógica - essa é a divisão de trabalho certa. Boas próximas leituras: escrever testes e TDD com IA para deixar sua API mais robusta, e publicar apps com o Claude Code para colocá-la em uma URL de verdade.