AWS Lambda mit Claude Code: Praxisguide für Node.js, IAM und API Gateway

Claude Code ist bei AWS Lambda besonders nützlich, weil es Handler, Test-Event, IAM-Policy-Entwurf, Deployment-Kommandos und Review-Checkliste in einem Kontext vorbereiten kann. Diese Geschwindigkeit ist hilfreich, aber AWS-Berechtigungen und Kosten sind echte Produktionsentscheidungen. Verwenden Sie Claude Code zum Entwerfen und Prüfen, nicht zum blinden Vergeben von IAM-Rechten, Veröffentlichen einer API oder Erzeugen kostenpflichtiger Ressourcen ohne menschliche Freigabe.

Dieser Guide zeigt einen teamtauglichen Ablauf: eine Node.js-Lambda erstellen, lokal testen, IAM nah am Prinzip der minimalen Rechte halten, Umgebungsvariablen setzen, API Gateway verbinden, CloudWatch Logs lesen, ein Zip-Paket aktualisieren und eine sichere Review-Schleife einbauen. Lambda ist eine kleine Laufzeitumgebung, die bei Events startet. IAM legt fest, was die Funktion darf. API Gateway ist der HTTP-Eingang, der Anfragen an Lambda weiterleitet.

Legen Sie die offiziellen Referenzen daneben: AWS Lambda Getting Started, Lambda mit Node.js, Lambda-Umgebungsvariablen, Monitoring mit CloudWatch Logs und Claude Code common workflows. Die Beispiele nutzen den Lambda-Runtime Node.js 24, Stand 1. Juni 2026.

Wann dieses Muster passt

Lambda passt, wenn eine kleine und zuverlässige Aktion gebraucht wird, ohne dauerhaft einen Server zu betreiben. Claude Code bringt den größten Nutzen, wenn es wiederholbare Struktur erstellt und ein Reviewer die endgültige Entscheidung trifft.

Anwendungsfall	Warum Lambda passt	Was Claude Code entwerfen kann	Was Menschen prüfen müssen
Webhook-Empfänger	Payment-, Formular- und SaaS-Events sind kurz	Signaturprüfung, Event-Fixture, Fehlerantworten	Secrets, Retries, doppelte Events
Interne JSON-API	Kleine Endpunkte brauchen keinen permanenten App-Server	Handler, API-Gateway-Kommandos, Log-Format	Auth, CORS, Exposition, Kosten
Batch-Einstieg	CSV-Importe, Bildjobs und Benachrichtigungen starten klein	Eingabeprüfung, strukturierte Logs, Fehlerklassen	Timeout, Retry-Strategie, sichere Löschung

Für einen ersten Proof of Concept ist AWS CLI plus Zip-Paket schnell. Für Team-Betrieb sollte dieselbe Logik später in SAM, CDK oder einen anderen geprüften IaC-Fluss wandern.

Ansatz	Geeignet für	Achtung
AWS Console	Einmalige Verhaltensprüfung	Manuelle Schritte landen nicht sauber im Review
AWS CLI + zip	Kleiner reproduzierbarer Proof of Concept	IAM und Umgebungsvariablen brauchen genaue Prüfung
SAM / CDK	Dauerhafter Team-Betrieb	IaC-Review und Deployment-Freigabe sind Pflicht

flowchart LR
  A[Entwurf mit Claude Code] --> B[Lokaler Node.js-Test]
  B --> C[Mensch prüft IAM und Umgebung]
  C --> D[Zip-Paket nach dev deployen]
  D --> E[Test über API Gateway]
  E --> F[CloudWatch Logs lesen]
  F --> A

1. Node.js-Lambda-Handler erstellen

Beginnen Sie mit einem index.mjs ohne externe Abhängigkeiten. Es akzeptiert HTTP API v2 Events und auch das ältere REST-API-Format.

// 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 });
  }
}

Diese erste Version schreibt noch nicht nach DynamoDB. Das ist Absicht. Zuerst sollten Event-Empfang, JSON-Parsing, Response-Shape und durchsuchbare Logs stabil sein.

2. Lokal mit einem Event-Fixture testen

Ein Fixture ist eine feste Testeingabe. Auch wenn Claude Code sie generiert, sollte sie im Repository bleiben, damit Reviewer Fehler reproduzieren können.

{
  "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
}

Speichern Sie die Datei als events/create-order.json und fügen Sie einen lokalen Runner hinzu.

// 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));

Vor AWS zuerst lokal ausführen:

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

Wenn lokal kein statusCode: 202 zurückkommt, wird ein Deployment das Debugging nur verlangsamen. Ein konkretes Fixture hilft auch Claude Code, über echte Eingaben statt Vermutungen zu argumentieren.

3. IAM nah am geringsten Recht halten

Hängen Sie keine AdministratorAccess-Policy an die Lambda-Ausführungsrolle. Starten Sie mit Logs und fügen Sie Datenzugriff nur hinzu, wenn der Handler ihn wirklich braucht.

{
  "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"
    }
  ]
}

Das ist ein Entwurf, keine Produktionsantwort. Ersetzen Sie Account, Region, Funktionsname und Tabellenname. Entfernen Sie den DynamoDB-Block, bis er wirklich gebraucht wird. Für eine tiefere Berechtigungsprüfung hilft der AWS-IAM-Guide.

4. Zip-Paket mit AWS CLI deployen

Die folgenden Befehle erstellen echte AWS-Ressourcen und können Kosten verursachen. Nutzen Sie ein Dev-Konto, prüfen Sie die Region und kennen Sie die Löschschritte vor der Ausführung.

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

Erstellen Sie trust-policy.json, damit Lambda die Rolle übernehmen darf.

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

Speichern Sie den IAM-Entwurf als lambda-policy.json, dann Rolle und Funktion erstellen.

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"

Nur den Code aktualisieren:

zip function.zip index.mjs

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

Achten Sie auf Umgebungsvariablen. Bei update-function-configuration wird die Variables-Map vollständig ersetzt. Lesen Sie die aktuelle Konfiguration vor Änderungen. Passwörter und API-Schlüssel gehören eher in Secrets Manager oder Parameter Store.

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. API Gateway und CloudWatch Logs prüfen

Zuerst Lambda direkt aufrufen.

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

cat response.json

Dann eine HTTP API erstellen. Dadurch entsteht ein öffentlicher Endpoint; prüfen Sie Auth, CORS, Rate Limits und Cleanup-Plan vor der Ausführung.

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"}'

Direkt danach Logs lesen.

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

Wenn keine Logs erscheinen, prüfen Sie Region, Funktionsname, logs:CreateLogStream und logs:PutLogEvents. Wenn API Gateway 500 zurückgibt, prüfen Sie, ob die Lambda-Antwort statusCode, headers und body enthält. Mehr dazu steht im AWS-CloudWatch-Guide und im AWS-API-Gateway-Guide.

Claude-Prompt für Lambda-Review

Lassen Sie Claude Code Risiken erklären, bevor es editiert oder deployt.

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

Der sichere Ablauf lautet: explorieren, planen, editieren, lokal testen, nur nach dev deployen, Logs lesen und IAM- sowie Kostenänderungen von Menschen freigeben lassen. Für den Übergang zu CI/CD und IaC lesen Sie den AWS-Deployment-Guide.

Häufige Fehler

Der erste Fehler ist ein Deployment ohne lokale Reproduktion. Wenn die Event-Form falsch ist, findet ein Fixture das schneller als CloudWatch.

Der zweite Fehler ist, Secrets direkt in Umgebungsvariablen zu schreiben. Sie sind gut für Konfiguration, aber Secrets brauchen Zugriffskontrolle und Rotation.

Der dritte Fehler ist zu breites IAM. dynamodb:* und Resource: "*" machen Demos einfach, erhöhen aber den Schaden bei Fehlern.

Der vierte Fehler ist ein API-Gateway-Endpoint ohne klare Verantwortung. Vor dem Teilen der URL müssen Auth, CORS, Throttling, Logging und Cleanup-Datum feststehen.

Der fünfte Fehler ist, Kosten zu übersehen. Lambda wirkt klein, aber API Gateway, CloudWatch Logs, DynamoDB, NAT und externe API-Aufrufe können alle Gebühren erzeugen.

ClaudeCodeLab bündelt solche Review-Flows in Claude-Code-Templates und Trainingsmaterial. Wenn Ihr Team AWS-Berechtigungen, CLAUDE.md, Review-Prompts und Deployment-Freigaben für ein echtes Repository gestalten will, nutzen Sie die Seite für Claude-Code-Beratung und Training.

Proof-of-Concept-Ressourcen danach löschen:

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"

Beim praktischen Durchspielen dieses Ablaufs war der größte Gewinn, dass Claude Code Handler, Fixture, IAM-Entwurf und CLI-Kommandos in einem prüfbaren Kontext zusammenhält. Das Risiko lag nicht primär in der Codegenerierung, sondern in Berechtigungen und öffentlicher Exposition. Das verlässliche Muster ist: lokales Fixture zuerst, dev-Deployment danach, CloudWatch-Belege lesen und IAM sowie Kosten vor Produktion menschlich prüfen.