Claude Code Devcontainer: reproduzierbare Entwicklungsumgebung

Claude Code ist dann am nützlichsten, wenn die Entwicklungsumgebung langweilig stabil ist. Wenn ein Entwickler Node.js 22 nutzt, eine Kollegin noch Node.js 20 hat, PostgreSQL lokal anders installiert ist und Redis nur auf manchen Rechnern läuft, muss der Agent zuerst Umgebungsprobleme erklären. Das kostet Zeit und macht Review-Ergebnisse schwer reproduzierbar.

Ein Dev Container verschiebt diese Details in versionierte Dateien im Repository. Der Editor verbindet sich mit einem Docker-Container, und Terminal, Sprachserver, Tests, Datenbank-Tools und Claude Code laufen im selben Kontext. In diesem Leitfaden bauen wir eine praktische Umgebung für Next.js und TypeScript mit PostgreSQL, Redis, Dockerfile, postCreateCommand, Berechtigungen, Secrets, Volumes und Port-Forwarding.

Am 2. Juni 2026 enthält die offizielle Claude-Code-Dokumentation eine Seite zu Development containers. Sie beschreibt die Dev Container Feature, persistente Anmeldedaten, Netzwerkgrenzen und den riskanten Umgang mit übersprungenen Berechtigungsabfragen. Für den Container-Standard sollten Sie zusätzlich die VS Code Dev Containers Dokumentation und die Dev Container Specification prüfen.

Warum Devcontainer zu Claude Code passen

Claude Code liest Dateien, ändert Code, führt Kommandos aus und analysiert fehlgeschlagene Tests. Diese Stärke wird zum Risiko, wenn der Agent in einer unscharfen Host-Umgebung läuft. Dort können alte globale Pakete, private Cloud-Zugänge, Umgebungsvariablen anderer Projekte oder eine andere Datenbank sichtbar sein.

Mit einem Devcontainer wird die Arbeitsfläche überprüfbar. Node.js-Version, Systempakete, Claude-Code-CLI-Version, VS-Code-Erweiterungen, Lifecycle-Kommandos, Volumes und weitergeleitete Ports stehen im Repository. Wenn Claude Code sagt, dass npm test ausgeführt wurde, ist klar, in welcher Umgebung das passiert ist.

flowchart LR
  Host["Host-Rechner"] --> Editor["VS Code / Cursor"]
  Editor --> Container["Dev Container"]
  Container --> Claude["Claude Code CLI"]
  Container --> Tools["Node.js / npm / psql / redis-cli"]
  Container --> Services["PostgreSQL / Redis"]
  Container --> Repo["Gemountetes Repository"]
  Claude --> Repo
  Claude --> Tools

Drei Einsatzfälle sind besonders praktisch. Beim Onboarding muss eine neue Person nicht alle Tools manuell installieren. Bei Remote-Entwicklung funktioniert dieselbe .devcontainer-Konfiguration lokal und in Codespaces. Bei KI-gestütztem Debugging kann das Team Linting, Typechecks und Tests mit denselben Versionen wiederholen.

Die Dateien der Konfiguration

Die Umgebung trennt Anwendung, abhängige Services und Claude-Code-Zustand. Genau diese Trennung verhindert, dass aus Bequemlichkeit das komplette Home-Verzeichnis des Hosts gemountet wird.

Datei	Aufgabe	Review-Fokus
.devcontainer/devcontainer.json	Einstiegspunkt für den Editor	remoteUser, Ports, Mounts, Lifecycle-Kommandos
.devcontainer/Dockerfile	Installiert Tools und Claude Code	CLI-Version, nicht-root User, Systempakete
.devcontainer/docker-compose.yml	Startet App, PostgreSQL und Redis	Volumes, Healthchecks, veröffentlichte Ports
.devcontainer/post-create.sh	Setup nach Container-Erstellung	Lockfile, Prisma, sichtbare Fehler
.claude/settings.json	Berechtigungsregeln für Claude Code	.env, Secrets, Push und gefährliche Docker-Kommandos

devcontainer.json zum Kopieren

Legen Sie .devcontainer/devcontainer.json an. Die Datei ist echtes JSON, daher ohne Kommentare.

{
  "name": "claude-code-next-dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspaces/app",
  "remoteUser": "node",
  "shutdownAction": "stopCompose",
  "waitFor": "postCreateCommand",
  "postCreateCommand": "bash .devcontainer/post-create.sh",
  "postStartCommand": "git config --global --add safe.directory /workspaces/app || true",
  "forwardPorts": [3000, 5432, 6379],
  "portsAttributes": {
    "3000": { "label": "Next.js", "onAutoForward": "notify" },
    "5432": { "label": "PostgreSQL", "onAutoForward": "silent" },
    "6379": { "label": "Redis", "onAutoForward": "silent" }
  },
  "mounts": [
    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
  ],
  "containerEnv": {
    "NODE_ENV": "development",
    "DISABLE_AUTOUPDATER": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "anthropic.claude-code",
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-azuretools.vscode-docker"
      ],
      "settings": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "typescript.tsdk": "node_modules/typescript/lib",
        "terminal.integrated.defaultProfile.linux": "bash"
      }
    }
  }
}

remoteUser sollte nicht root sein. Der Container begrenzt das Risiko, aber der Workspace ist weiterhin vom Host gemountet. Wenn Claude Code Dateien in /workspaces/app löscht, ist das lokale Repository betroffen. Das Volume für /home/node/.claude bewahrt Claude-Code-Einstellungen über Rebuilds hinweg, ohne das gesamte Home-Verzeichnis des Hosts freizugeben.

Docker Compose, Dockerfile und Initialisierung

Die Datei .devcontainer/docker-compose.yml startet App, PostgreSQL und Redis. Datenbankports werden zunächst nur über forwardPorts zugänglich gemacht; Compose-ports sind nur nötig, wenn ein externes Tool wirklich darauf zugreifen muss.

services:
  app:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile
    command: sleep infinity
    volumes:
      - ..:/workspaces/app:cached
      - node_modules:/workspaces/app/node_modules
      - claude_code_config:/home/node/.claude
    environment:
      DATABASE_URL: postgresql://app:app_password@db:5432/app
      REDIS_URL: redis://redis:6379
      NEXT_TELEMETRY_DISABLED: "1"
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app_password
      POSTGRES_DB: app
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 5s
      retries: 20

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 20

volumes:
  node_modules:
  claude_code_config:
  postgres_data:
  redis_data:

Im Dockerfile pinnen wir die Claude-Code-Version. Am 2. Juni 2026 lieferte npm view @anthropic-ai/claude-code version den Wert 2.1.160; prüfen Sie den aktuellen Wert, bevor Sie ihn langfristig übernehmen.

FROM mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm

ARG CLAUDE_CODE_VERSION=2.1.160

ENV DISABLE_AUTOUPDATER=1
ENV NEXT_TELEMETRY_DISABLED=1

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
      jq \
      postgresql-client \
      redis-tools \
      ripgrep \
    && rm -rf /var/lib/apt/lists/*

RUN npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
    && npm cache clean --force

USER node
WORKDIR /workspaces/app

RUN mkdir -p /home/node/.claude

Das Setup nach der Erstellung liegt in .devcontainer/post-create.sh.

#!/usr/bin/env bash
set -euo pipefail

cd /workspaces/app
corepack enable

if [ -f pnpm-lock.yaml ]; then
  pnpm install --frozen-lockfile
elif [ -f yarn.lock ]; then
  yarn install --immutable
elif [ -f package-lock.json ]; then
  npm ci
elif [ -f package.json ]; then
  npm install
fi

if [ -f prisma/schema.prisma ]; then
  npx prisma generate
fi

node --version
npm --version
claude --version || true

Das Skript respektiert vorhandene Lockfiles und bricht bei Fehlern ab. Starten Sie keinen dauerhaften Dev-Server in postCreateCommand; npm run dev gehört in ein Terminal, eine VS-Code-Task oder einen eigenen Service.

Berechtigungen, Secrets, Volumes und Ports

Mounten Sie ~/.ssh, ~/.aws, ~/.config/gcloud oder produktive .env-Dateien nicht automatisch in den Container. Das sicherste Secret ist das, das gar nicht in die Umgebung gelangt. Entwicklungswerte können auf interne Compose-Services zeigen; echte API-Schlüssel gehören in gemanagte Secrets oder kurzlebige Tokens.

Projektregeln für Claude Code können in .claude/settings.json liegen.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run typecheck)",
      "Bash(claude --version)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(printenv *)",
      "Bash(git push *)",
      "Bash(docker system prune *)"
    ]
  }
}

Volumes beschleunigen die Arbeit, konservieren aber auch alte Zustände. node_modules sollte im Linux-Container-Volume liegen, nicht als Host-Ordner von Windows oder macOS gemischt werden. Für PostgreSQL ist ein Volume praktisch, aber nach Migrationsexperimenten muss dokumentiert sein, wann docker compose -f .devcontainer/docker-compose.yml down -v erlaubt ist.

Fehlerbilder und Prüfung

Häufige Fehler sind: Claude Code als root ausführen, die CLI-Version nicht pinnen, produktive Secrets mounten, lange Prozesse in postCreateCommand starten und Datenbankports ohne Not veröffentlichen. Jeder Punkt wirkt klein, aber zusammen zerstören sie Reproduzierbarkeit.

Nach einem Rebuild prüfen Sie node --version, npm --version, claude --version, mindestens einen Lint- oder Testbefehl und http://localhost:3000. Stellen Sie sicher, dass .env, .env.local und secrets/** für Claude Code nicht lesbar sind und interne Services nicht unnötig veröffentlicht werden.

Für mehr Compose-Praxis lesen Sie den Claude Code Docker Compose Guide. Für die Verbindung mit Releases passt der Claude Code CI/CD Setup Guide. Wenn Ihr Team devcontainer, CLAUDE.md, Berechtigungen und Review-Checklisten als festen Workflow etablieren will, ist training / consultation der nächste sinnvolle Schritt.

Ergebnis des Tests

In einem kleinen Next.js-Testrepository brachten drei Entscheidungen den größten Nutzen: postCreateCommand als separates Skript, node_modules als Container-Volume und /home/node/.claude als projektbezogenes Volume. Nach jedem Rebuild waren Claude-Code-Version, Installation, Prisma-Generierung und Port 3000 gleich prüfbar. Das einzige echte Problem war alter Datenbankzustand nach mehreren Migrationsexperimenten. Reproduzierbarkeit entsteht also nicht durch das Dockerfile allein, sondern durch Versionen, Secret-Grenzen, Volume-Regeln und Port-Disziplin zusammen.