Claude Code × AWS S3: sync, Bilder, Backups und Presigned URLs mit minimalen Rechten

S3 wirkt wie einfacher Dateispeicher, aber in echten Anwendungen kommen Rechte, öffentliche Sichtbarkeit, Sync, Cache, Löschen und Kosten dazu. Claude Code kann Skripte und TypeScript-Helper schnell bauen, erzeugt bei vagen Prompts aber auch zu breite IAM-Policies.

Dieser Leitfaden richtet sich an Einsteiger, die S3 produktionsnah einsetzen wollen. Wir behandeln statische Sites, Bild-Uploads, Backups und Presigned URLs. Die wichtigste Regel ist least privilege: jedes Skript bekommt nur die Action und den Prefix, die es wirklich braucht.

Die Beispiele orientieren sich an den offiziellen Dokumenten: AWS CLI S3 reference, aws s3 sync reference, Boto3 presigned URL guide, Claude Code common workflows.

Ergänzend helfen diese Artikel: IAM, security, context.

S3-Anwendungsfälle vor dem Code trennen

use case 1 ist eine statische Site. dist wird nach site/ synchronisiert und CloudFront liefert aus. use case 2 sind Bilder. Das Admin-Tool schreibt nach uploads/ oder assets/images/. use case 3 sind Backups. Dumps und PDFs liegen unter einem Datums-Prefix und nutzen kein —delete. use case 4 sind private Downloads über kurze Presigned URLs.

Wenn alles gemischt wird, wirkt s3:* bequem. Besser sind Prefixes wie site/, assets/images/, uploads/, backups/ und assets/private-reports/. Mit diesen Grenzen erzeugt Claude Code deutlich besser prüfbare Scripts.

Identität und IAM Least Privilege

Lege Bucket und Region zuerst als Variablen fest, damit Mensch und Claude Code dasselbe Ziel prüfen.

export AWS_REGION=ap-northeast-1
export S3_BUCKET=claudecode-lab-assets-prod
aws sts get-caller-identity
aws s3 ls "s3://${S3_BUCKET}/" --region "${AWS_REGION}"

Diese Policy liest nur assets, schreibt nur uploads und vermeidet breite Delete-Rechte.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadPublicAssetsOnly",
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::claudecode-lab-assets-prod/assets/*"
    },
    {
      "Sid": "WriteUploadsOnly",
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:AbortMultipartUpload"],
      "Resource": "arn:aws:s3:::claudecode-lab-assets-prod/uploads/*"
    },
    {
      "Sid": "ListLimitedPrefixes",
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::claudecode-lab-assets-prod",
      "Condition": {
        "StringLike": {
          "s3:prefix": ["assets/*", "uploads/*", "backups/*"]
        }
      }
    }
  ]
}

Das ist die Grundform für statische Sites oder Bildordner. Starte immer mit dryrun.

# 1. Preview changes first. This should become a habit.
aws s3 sync ./dist "s3://${S3_BUCKET}/site/" \
  --region "${AWS_REGION}" \
  --delete \
  --cache-control "public,max-age=300" \
  --dryrun

# 2. Deploy only after the preview looks right.
aws s3 sync ./dist "s3://${S3_BUCKET}/site/" \
  --region "${AWS_REGION}" \
  --delete \
  --cache-control "public,max-age=300"

# 3. Upload long-lived images with a different cache policy.
aws s3 sync ./public/images "s3://${S3_BUCKET}/assets/images/" \
  --region "${AWS_REGION}" \
  --exclude "*.psd" \
  --cache-control "public,max-age=31536000,immutable"

Eine Presigned URL hält den Bucket privat und erlaubt trotzdem zeitlich begrenzten Download.

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const s3 = new S3Client({ region: process.env.AWS_REGION ?? "ap-northeast-1" });

export async function createDownloadUrl(key: string, filename: string) {
  if (!key.startsWith("assets/private-reports/")) {
    throw new Error(`Unexpected S3 key prefix: ${key}`);
  }

  const command = new GetObjectCommand({
    Bucket: process.env.S3_BUCKET_NAME,
    Key: key,
    ResponseContentDisposition: `attachment; filename="${filename}"`,
  });

  return getSignedUrl(s3, command, { expiresIn: 900 });
}

Gib Claude Code Zweck, Verbote und Prüfkommandos gemeinsam mit.

このリポジトリに AWS S3 連携を追加してください。
目的: public/images を S3 の assets/images/ に同期し、private-reports/ のPDFだけ署名付きURLで配布する。
制約: バケット全体公開は禁止。s3:DeleteObject は付けない。aws s3 sync は必ず --dryrun を先に出す。
成果物: scripts/s3-sync-assets.mjs、lib/s3-presigned-url.ts、READMEの手順、確認コマンド。
確認: npm test、aws s3 ls、aws s3 sync --dryrun の出力で説明してください。
参照: AWS CLI s3/sync docs と Anthropic Claude Code common workflows。

Die Policy ist absichtlich eng: GetObject nur auf assets, PutObject nur auf uploads und ListBucket mit Prefix-Bedingung. Typische Fehler sind ListBucket auf Object-ARNs und s3:* auf den gesamten Bucket.

DeleteObject ist ein weiterer pitfall. Viele Flows brauchen es nicht. Wenn Löschen nötig ist, trenne Rolle oder Skript und verlange dryrun, Anzahl der Deletes und manuelle Bestätigung. Claude Code schreibt JSON, aber der Mensch prüft die Reichweite.

aws s3 sync sicher einsetzen

aws s3 sync vergleicht lokalen Ordner und S3-Prefix. Mit —delete löscht es remote Dateien, die lokal fehlen. Für deterministische statische Deployments ist das gut, für Backups oder gemeinsame Medienordner riskant.

# Backup use case: append-only, no --delete.
BACKUP_DATE=$(date +%Y-%m-%d)
aws s3 sync ./backups "s3://${S3_BUCKET}/backups/${BACKUP_DATE}/" \
  --region "${AWS_REGION}" \
  --storage-class STANDARD_IA \
  --exclude "*.tmp"

aws s3 ls "s3://${S3_BUCKET}/backups/${BACKUP_DATE}/" --recursive --summarize

Mein Muster ist immer: zuerst dryrun, dann Ausführung. Das Skript zeigt Bucket, Region, Prefix und Diff. Bei zu vielen Deletes stoppt es. Dieser einfache Schutz verhindert den Klassiker: falscher Ordner plus —delete.

Presigned URLs sind temporäre Erlaubnis

Eine presigned URL erlaubt eine S3-Aktion für kurze Zeit, ohne den Bucket öffentlich zu machen. Das passt für Rechnungen, private PDFs, Exporte oder benutzerbezogene Downloads nach Login.

Wichtig sind drei Punkte: expiresIn ist in Sekunden, der Key-Prefix wird geprüft, und Browser-Dateinamen werden nicht direkt S3-Keys. Erzeuge serverseitig Keys wie uploads/yyyy/mm/dd/uuid.ext. Zu lange URLs sind eine häufige failure.

Kosten, Cache und öffentliche Freigabe

S3-Kosten bestehen nicht nur aus Storage. Requests, Datentransfer, CloudFront, Versioning und Lifecycle-Regeln zählen auch. Öffentliche Assets sollten über CloudFront laufen, private Dateien nicht per öffentlichem Bucket.

DRYRUN_OUTPUT=$(aws s3 sync ./dist "s3://${S3_BUCKET}/site/" --delete --dryrun)
echo "$DRYRUN_OUTPUT"
DELETE_COUNT=$(echo "$DRYRUN_OUTPUT" | grep -c "delete:" || true)
if [ "$DELETE_COUNT" -gt 20 ]; then
  echo "Too many deletes: ${DELETE_COUNT}. Stop and review."
  exit 1
fi

Viele alte Tutorials nutzen S3 static website hosting mit Public Bucket. In modernen Setups ist private S3 + CloudFront oft sicherer und bei Audits einfacher zu erklären.

Was Claude Code übernimmt und was Menschen prüfen

Claude Code eignet sich für Sync-Skripte, TypeScript-Helper, README, Tests und Fehlermeldungen. Menschen prüfen AWS-Konto, Bucket, Prefix, DeleteObject, Public Access und CloudFront. Vorher: aws sts get-caller-identity und aws s3 ls.

Masa-Verifizierungsnotiz: Prefix-Trennung war der wichtigste Hebel. site, assets, uploads, backups und private-reports machten IAM-Review und Prompts viel klarer. Verification steps von Claude Code mitschreiben zu lassen erhöht zusätzlich das Vertrauen.

Zusammenfassung

Claude Code × AWS S3 funktioniert sehr gut, wenn die Rechte langweilig bleiben. Trenne use cases, nutze sync mit dryrun, vermeide breite Delete-Rechte, halte S3 privat und gib Presigned URLs kurz aus.

Um dieses Muster auf ein echtes Repository anzuwenden, nutze training / consultation.