Guia prático de AWS Lambda com Claude Code: Node.js, IAM e API Gateway

Claude Code ajuda bastante em AWS Lambda porque consegue preparar, no mesmo contexto, o handler, o evento de teste, um rascunho de política IAM, os comandos de deploy e uma checklist de revisão. Essa velocidade é útil, mas permissões e custos na AWS são decisões reais de produção. Use Claude Code para rascunhar e revisar; não para conceder permissões, expor APIs públicas ou criar recursos com custo sem revisão humana.

Este guia mostra um fluxo prático para equipes: criar uma Lambda em Node.js, testar localmente, manter IAM perto do menor privilégio, configurar variáveis de ambiente, conectar API Gateway, ler CloudWatch Logs, atualizar o pacote zip e fechar o ciclo com uma revisão segura. Lambda é um pequeno runtime que roda quando chega um evento. IAM define o que a função pode fazer. API Gateway é a entrada HTTP que encaminha requests para a Lambda.

Deixe as referências oficiais abertas: AWS Lambda getting started, Lambda com Node.js, variáveis de ambiente do Lambda, monitoramento com CloudWatch Logs e Claude Code common workflows. Os exemplos usam o runtime Lambda Node.js 24, conforme este artigo em 1 de junho de 2026.

Quando este padrão faz sentido

Lambda funciona bem quando você precisa de uma ação pequena e confiável sem manter um servidor rodando o dia inteiro. Claude Code ajuda mais quando cria uma estrutura repetível e uma pessoa mantém a decisão final.

Caso de uso	Por que Lambda serve	O que Claude Code pode rascunhar	O que humanos devem revisar
Receber webhooks	Pagamentos, formulários e SaaS enviam eventos curtos	Verificação de assinatura, fixtures, respostas de erro	Secrets, retries, eventos duplicados
API JSON interna	Endpoints pequenos não exigem servidor permanente	Handler, comandos do API Gateway, formato de logs	Autenticação, CORS, exposição, custo
Entrada de batch	CSV, imagens e notificações podem começar pequenos	Validação, logs estruturados, classes de erro	Timeout, estratégia de retry, remoção segura

Para uma primeira prova de conceito, AWS CLI com pacote zip é rápido. Para operação em equipe, mova depois a mesma lógica para SAM, CDK ou outro fluxo IaC revisado.

Método	Melhor para	Atenção
Console AWS	Conferir comportamento uma vez	Passos manuais somem do histórico de revisão
AWS CLI + zip	Prova pequena e reproduzível	IAM e variáveis exigem revisão cuidadosa
SAM / CDK	Operação contínua em equipe	Review de IaC e aprovação de deploy são obrigatórios

flowchart LR
  A[Rascunho com Claude Code] --> B[Teste local Node.js]
  B --> C[Humano revisa IAM e ambiente]
  C --> D[Zip package para dev]
  D --> E[Teste via API Gateway]
  E --> F[Ler CloudWatch Logs]
  F --> A

1. Criar o handler Node.js

Comece com um index.mjs sem dependências externas. Ele aceita eventos HTTP API v2 e também o formato antigo de REST API.

// index.mjs
import crypto from "node:crypto";

const allowedStages = new Set(["dev", "staging", "prod"]);

function readConfig() {
  const stage = process.env.APP_STAGE ?? "dev";
  if (!allowedStages.has(stage)) {
    throw new Error(`Invalid APP_STAGE: ${stage}`);
  }

  return {
    stage,
    tableName: process.env.TABLE_NAME ?? "local-orders",
    logLevel: process.env.LOG_LEVEL ?? "info",
  };
}

function log(level, message, details = {}) {
  console.log(
    JSON.stringify({
      level,
      message,
      service: "orders-api",
      ...details,
    })
  );
}

function json(statusCode, body) {
  return {
    statusCode,
    headers: {
      "content-type": "application/json",
    },
    body: JSON.stringify(body),
  };
}

function parseBody(event) {
  if (!event.body) return {};
  const raw = event.isBase64Encoded
    ? Buffer.from(event.body, "base64").toString("utf8")
    : event.body;
  return JSON.parse(raw);
}

export async function handler(event = {}, context = {}) {
  const config = readConfig();
  const method = event.requestContext?.http?.method ?? event.httpMethod ?? "GET";
  const path = event.rawPath ?? event.path ?? "/";
  const requestId = context.awsRequestId ?? "local";

  log("info", "request.start", {
    requestId,
    method,
    path,
    stage: config.stage,
  });

  try {
    if (method === "GET" && path === "/health") {
      return json(200, { ok: true, stage: config.stage });
    }

    if (method === "POST" && path === "/orders") {
      const payload = parseBody(event);
      const orderId = payload.orderId ?? crypto.randomUUID();

      log("info", "order.accepted", {
        requestId,
        orderId,
        tableName: config.tableName,
      });

      return json(202, {
        orderId,
        status: "accepted",
        storedIn: config.tableName,
      });
    }

    return json(404, { error: "not_found", method, path });
  } catch (error) {
    log("error", "request.failed", {
      requestId,
      errorName: error.name,
      errorMessage: error.message,
    });

    return json(500, { error: "internal_error", requestId });
  }
}

Esta primeira versão ainda não grava no DynamoDB. Isso é intencional. Para começar, confirme recebimento do evento, parsing de JSON, formato de resposta e logs pesquisáveis antes de adicionar banco e permissões.

2. Testar localmente com fixture de evento

Fixture é uma entrada fixa de teste. Mesmo que Claude Code gere o arquivo, mantenha no repositório para que revisores reproduzam falhas.

{
  "version": "2.0",
  "routeKey": "POST /orders",
  "rawPath": "/orders",
  "requestContext": {
    "http": {
      "method": "POST",
      "path": "/orders"
    }
  },
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"orderId\":\"demo-1001\",\"amount\":3200,\"currency\":\"JPY\"}",
  "isBase64Encoded": false
}

Salve como events/create-order.json e adicione um runner local.

// local-test.mjs
import { readFile } from "node:fs/promises";
import { handler } from "./index.mjs";

process.env.APP_STAGE = "dev";
process.env.TABLE_NAME = "orders-dev";
process.env.LOG_LEVEL = "debug";

const eventPath = process.argv[2] ?? "events/create-order.json";
const event = JSON.parse(await readFile(eventPath, "utf8"));

const result = await handler(event, { awsRequestId: "local-001" });
console.log(JSON.stringify(result, null, 2));

Rode antes de tocar na AWS:

node local-test.mjs events/create-order.json

Se o resultado local não retornar statusCode: 202, fazer deploy só vai atrasar o diagnóstico. Uma fixture concreta também ajuda Claude Code a raciocinar sobre uma entrada real.

3. Manter IAM perto do menor privilégio

Não anexe AdministratorAccess ao execution role da Lambda. Comece com logs e adicione acesso a dados somente quando o handler realmente precisar.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CreateOwnLogGroupIfMissing",
      "Effect": "Allow",
      "Action": "logs:CreateLogGroup",
      "Resource": "arn:aws:logs:ap-northeast-1:123456789012:*"
    },
    {
      "Sid": "WriteOwnLambdaLogs",
      "Effect": "Allow",
      "Action": ["logs:CreateLogStream", "logs:PutLogEvents"],
      "Resource": "arn:aws:logs:ap-northeast-1:123456789012:log-group:/aws/lambda/claude-orders-dev:*"
    },
    {
      "Sid": "ReadWriteOnlyOrdersTable",
      "Effect": "Allow",
      "Action": ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:Query"],
      "Resource": "arn:aws:dynamodb:ap-northeast-1:123456789012:table/orders-dev"
    }
  ]
}

Trate esse JSON como rascunho. Troque account, region, function name e table name. Remova o bloco DynamoDB até ele ser usado de verdade. Para aprofundar, veja também o guia de AWS IAM.

4. Fazer deploy de pacote zip com AWS CLI

Os comandos abaixo criam recursos reais da AWS e podem gerar custo. Use uma conta dev, confirme a região e conheça os passos de limpeza antes de executar.

export AWS_REGION=ap-northeast-1
export FUNCTION_NAME=claude-orders-dev
export ROLE_NAME=claude-orders-dev-lambda-role
export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

zip function.zip index.mjs

Crie trust-policy.json para permitir que Lambda assuma o role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Salve o rascunho IAM anterior como lambda-policy.json e crie o role e a função.

aws iam create-role \
  --role-name "$ROLE_NAME" \
  --assume-role-policy-document file://trust-policy.json

aws iam put-role-policy \
  --role-name "$ROLE_NAME" \
  --policy-name claude-orders-dev-inline \
  --policy-document file://lambda-policy.json

ROLE_ARN=$(aws iam get-role \
  --role-name "$ROLE_NAME" \
  --query "Role.Arn" \
  --output text)

aws lambda create-function \
  --function-name "$FUNCTION_NAME" \
  --runtime nodejs24.x \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --role "$ROLE_ARN" \
  --architectures arm64 \
  --timeout 10 \
  --memory-size 128 \
  --environment "Variables={APP_STAGE=dev,TABLE_NAME=orders-dev,LOG_LEVEL=info}" \
  --region "$AWS_REGION"

Para atualizar apenas o código:

zip function.zip index.mjs

aws lambda update-function-code \
  --function-name "$FUNCTION_NAME" \
  --zip-file fileb://function.zip \
  --region "$AWS_REGION"

Tenha cuidado com variáveis de ambiente. Com update-function-configuration, o mapa Variables é substituído por completo. Leia a configuração atual antes de alterar. Senhas e API keys devem ir para Secrets Manager ou Parameter Store, não para variáveis em texto simples.

aws lambda update-function-configuration \
  --function-name "$FUNCTION_NAME" \
  --environment "Variables={APP_STAGE=dev,TABLE_NAME=orders-dev,LOG_LEVEL=debug}" \
  --region "$AWS_REGION"

5. Verificar API Gateway e CloudWatch Logs

Primeiro invoque a Lambda diretamente.

aws lambda invoke \
  --function-name "$FUNCTION_NAME" \
  --payload fileb://events/create-order.json \
  --region "$AWS_REGION" \
  response.json

cat response.json

Depois crie uma HTTP API. Isso expõe um endpoint público; revise autenticação, CORS, rate limits e plano de remoção antes de executar.

API_ID=$(aws apigatewayv2 create-api \
  --name claude-orders-dev-api \
  --protocol-type HTTP \
  --target "arn:aws:lambda:${AWS_REGION}:${ACCOUNT_ID}:function:${FUNCTION_NAME}" \
  --query "ApiId" \
  --output text)

aws lambda add-permission \
  --function-name "$FUNCTION_NAME" \
  --statement-id AllowHttpApiInvoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:${AWS_REGION}:${ACCOUNT_ID}:${API_ID}/*/*" \
  --region "$AWS_REGION"

API_ENDPOINT=$(aws apigatewayv2 get-api \
  --api-id "$API_ID" \
  --query "ApiEndpoint" \
  --output text)

curl -s "$API_ENDPOINT/health"
curl -s -X POST "$API_ENDPOINT/orders" \
  -H "content-type: application/json" \
  -d '{"amount":3200,"currency":"JPY"}'

Leia os logs logo depois do teste.

aws logs tail "/aws/lambda/${FUNCTION_NAME}" \
  --follow \
  --region "$AWS_REGION"

Se os logs não aparecerem, confira região, function name, logs:CreateLogStream e logs:PutLogEvents. Se API Gateway retornar 500, confirme que a resposta Lambda contém statusCode, headers e body. Para mais detalhes, leia o guia de AWS CloudWatch e o guia de AWS API Gateway.

Prompt Claude para revisar Lambda

Faça Claude Code explicar riscos antes de editar ou fazer deploy.

You are reviewing a Node.js AWS Lambda change for a team repository.

Scope:
- Files: index.mjs, events/*.json, IAM policy JSON, deployment commands in docs
- Runtime: nodejs24.x
- Entry point: index.handler

Review for:
1. API Gateway event compatibility and response shape
2. Input validation and JSON parsing failures
3. Environment variables that overwrite existing values
4. IAM actions that are wider than needed
5. CloudWatch logs that expose secrets or personal data
6. AWS resources that can create unexpected cost
7. Local test commands that a reviewer can copy and run

Return:
- blocking issues
- non-blocking improvements
- exact commands to verify locally
- questions a human must answer before deploying

O ciclo seguro é: explorar, planejar, editar, testar localmente, fazer deploy apenas em dev, ler logs e pedir aprovação humana para IAM e custos. Para transformar esta prova de conceito em CI/CD e IaC, continue com o guia de deployment AWS.

Armadilhas comuns

A primeira é fazer deploy sem reprodução local. Se o formato do evento estiver errado, uma fixture mostra isso mais rápido que CloudWatch.

A segunda é colocar secrets diretamente em variáveis de ambiente. Elas são úteis para configuração, mas secrets exigem controle de acesso e rotação.

A terceira é abrir IAM demais. dynamodb:* e Resource: "*" fazem demos passarem, mas aumentam o impacto de um erro.

A quarta é expor um endpoint API Gateway sem responsável claro. Antes de compartilhar a URL, defina autenticação, CORS, throttling, logs e data de limpeza.

A quinta é ignorar custo. Lambda parece pequeno, mas API Gateway, CloudWatch Logs, DynamoDB, NAT e chamadas externas podem gerar cobrança.

ClaudeCodeLab organiza esse tipo de fluxo em templates e material de treinamento de Claude Code. Se sua equipe precisa desenhar permissões AWS, CLAUDE.md, prompts de revisão e regras de aprovação de deploy para um repositório real, veja a página de consultoria e treinamento Claude Code.

Remova os recursos de prova de conceito ao terminar.

aws apigatewayv2 delete-api --api-id "$API_ID" --region "$AWS_REGION"
aws lambda delete-function --function-name "$FUNCTION_NAME" --region "$AWS_REGION"
aws iam delete-role-policy --role-name "$ROLE_NAME" --policy-name claude-orders-dev-inline
aws iam delete-role --role-name "$ROLE_NAME"

Ao testar de fato o fluxo deste artigo, o maior ganho foi ver Claude Code manter handler, fixture, rascunho IAM e comandos CLI no mesmo contexto revisável. A parte perigosa não foi gerar código, mas decidir permissões e exposição. O padrão confiável é fixture local primeiro, deploy em dev depois, evidência no CloudWatch e revisão humana de IAM e custos antes de qualquer produção.