Claude Code Entwicklungsumgebung sicher und reproduzierbar einrichten

Ein neuer Rechner oder ein frisch geklontes Repository sollte nicht den halben Tag kosten, bevor der erste sinnvolle Commit entsteht. Die typischen Ursachen sind bekannt: falsche Node.js-Version, gemischte Nutzung von npm und pnpm, veraltete .env, alte Docker-Volumes und lokale Schritte, die nur im Kopf einer Person existieren. Claude Code kann das beschleunigen, aber nur mit klaren Grenzen.

Das Ziel ist nicht, dem Agenten alles blind zu überlassen. Das Ziel ist eine reproduzierbare Umgebung, in der jede Person und jede Claude-Code-Sitzung dieselben Anweisungen, denselben Paketmanager, dieselben Geheimnisregeln und dieselben Prüfkommandos nutzt.

Als Quelle gelten die offiziellen Dokumente: Claude Code setup, settings, permissions und hooks. Passend dazu findest du bei ClaudeCodeLab Claude Code Einstieg, CLAUDE.md Best Practices und den Hooks Guide.

flowchart TD
  A["Werkzeuge prüfen"] --> B["Node und Paketmanager fixieren"]
  B --> C["Abhängigkeiten und .env.example erstellen"]
  C --> D["Regeln in CLAUDE.md speichern"]
  D --> E["Berechtigungen in settings.json begrenzen"]
  E --> F["Gefährliche Befehle mit Hooks blockieren"]
  F --> G["doctor, env check und Tests ausführen"]

Grundregeln

Behandle die Entwicklungsumgebung wie Produktionscode. Eine wichtige Regel gehört ins Repository. Ein echtes Geheimnis gehört nicht in den Agentenkontext. Ein Befehl, der Daten löscht oder Code veröffentlicht, braucht menschliche Freigabe.

Bereich	Datei oder Befehl	Zweck
Laufzeit	.nvmrc, packageManager, Corepack	Verhindert Unterschiede bei Node und pnpm
Geheimnisse	.env.example, .gitignore, permissions.deny	Hält echte Schlüssel aus Prompts und Commits heraus
Projektgedächtnis	CLAUDE.md	Lädt die Projektregeln in jeder Sitzung
Berechtigungen	.claude/settings.json	Steuert Lesen, Bash und Standardmodus
Hooks	.claude/hooks/*	Erzwingt deterministische Sicherheitsprüfungen
Verifikation	doctor, check:env, test	Liefert Belege statt Bauchgefühl

Kopierbares Bootstrap-Skript

Das Skript ist für Git Bash, WSL, macOS oder Linux gedacht. Es erstellt ein minimales TypeScript-Projekt, validiert Umgebungsvariablen, fixiert pnpm, verbietet Secret-Lesungen und richtet einen PreToolUse-Hook ein.

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

APP_DIR="${1:-claude-dev-lab}"
mkdir -p "$APP_DIR"
cd "$APP_DIR"

command -v node >/dev/null || { echo "Node.js fehlt"; exit 1; }
command -v claude >/dev/null || { echo "Claude Code CLI fehlt"; exit 1; }

corepack enable
corepack prepare pnpm@9.15.4 --activate

cat > package.json <<'JSON'
{
  "name": "claude-dev-lab",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@9.15.4",
  "scripts": {
    "doctor": "node --version && pnpm --version && claude --version",
    "check:env": "tsx src/env.ts",
    "test": "vitest run --passWithNoTests"
  },
  "dependencies": {
    "dotenv": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest",
    "vitest": "latest"
  }
}
JSON

mkdir -p src .claude/hooks .vscode
printf "22\n" > .nvmrc
cat > .gitignore <<'EOF'
node_modules
.env
.env.*
!.env.example
dist
coverage
EOF

cat > .env.example <<'EOF'
NODE_ENV=development
DATABASE_URL=postgresql://app:app@localhost:5432/app
REDIS_URL=redis://localhost:6379
EOF

cat > src/env.ts <<'TS'
import { config } from "dotenv";
import { z } from "zod";

config();

const Env = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional()
});

const parsed = Env.safeParse(process.env);
if (!parsed.success) {
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

console.log("env ok", {
  nodeEnv: parsed.data.NODE_ENV,
  hasRedis: Boolean(parsed.data.REDIS_URL)
});
TS

cat > CLAUDE.md <<'EOF'
# Projektanweisungen

## Umgebung einrichten
- Nutze die Node-Version aus `.nvmrc`.
- Nutze pnpm über Corepack. Wechsle nicht zu npm oder yarn.
- Kopiere `.env.example` lokal nach `.env` und ändere Werte von Hand.
- Lies, drucke oder committe niemals `.env` oder Secret-Dateien.
- Führe vor Codeänderungen `pnpm run doctor` und `pnpm run check:env` aus.
- Führe nach Änderungen den engsten passenden Test aus und notiere das Ergebnis.

## Arbeitsregeln
- Beginne mit Erkundung und einem kurzen Plan.
- Führe keine destruktiven Befehle und keine Deployments ohne ausdrückliche menschliche Freigabe aus.
- Halte Setup-Änderungen in reproduzierbaren Dateien fest, nicht nur im Terminalverlauf.
EOF

cat > .claude/hooks/block-dangerous.mjs <<'JS'
import { readFileSync } from "node:fs";

const input = JSON.parse(readFileSync(0, "utf8") || "{}");
const command = String(input.tool_input?.command ?? "");

const blockedPatterns = [
  /rm\s+-rf\s+(\/|~|\$HOME)/,
  /git\s+push\b/,
  /curl\b.+\|\s*(bash|sh)/,
  /Invoke-WebRequest\b.+\|\s*iex/i
];

if (blockedPatterns.some((pattern) => pattern.test(command))) {
  console.log(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Gefährlicher Befehl blockiert. Ziel und Umfang müssen menschlich geprüft werden."
    }
  }));
} else {
  console.log("{}");
}
JS

cat > .claude/settings.json <<'JSON'
{
  "defaultMode": "plan",
  "permissions": {
    "allow": [
      "Read",
      "Bash(pnpm install)",
      "Bash(pnpm run *)",
      "Bash(git status *)",
      "Bash(claude --version)",
      "Bash(claude doctor)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/block-dangerous.mjs"
          }
        ]
      }
    ]
  }
}
JSON

pnpm install
cp .env.example .env
pnpm run doctor
pnpm run check:env
pnpm test

Unter nativem Windows prüfst du zuerst die Werkzeugkette:

winget install Anthropic.ClaudeCode
claude --version
claude doctor
node --version
corepack enable
pnpm --version

Wenn pnpm --version fehlschlägt, repariere Node und Corepack zuerst. Meldet claude doctor Proxy-, Zertifikats- oder Loginprobleme, übergib die genaue Fehlermeldung an Claude Code und bitte um Diagnose unter dieser Einschränkung.

Sicherer Prompt

claude -p "
Prüfe und vervollständige die Entwicklungsumgebung dieses Repositories.

Regeln:
- Lies keine .env, .env.* oder Dateien unter secrets/
- Folge packageManager; wechsle nicht von pnpm zu npm oder yarn
- Lösche keine Docker-Volumes und führe kein git push aus

Erlaubt:
- README, package.json, CLAUDE.md und .claude/settings.json lesen
- pnpm install, pnpm run doctor, pnpm run check:env und pnpm test ausführen

Gib am Ende einen kurzen Beleg mit ausgeführten Befehlen, geänderten Dateien, Fehlern und offenen manuellen Schritten zurück.
"

Konkrete Einsatzfälle

Fall	Nutzen
Neuer SaaS-Prototyp	PostgreSQL und Redis per Docker Compose ergänzen und Setup von Tag eins reproduzierbar halten
Team-Repository	Claude Code liest Dokumentation, führt erlaubte Checks aus und verbessert Onboarding
Content- oder Produktseite	CTA-Links, Analytics, OGP und AdSense-relevante Seiten schützen
Internes Tool	Datenbank-Seed, Queues, Mocks und Tests standardisieren

Für Docker-Projekte passt Docker Compose. Für Teamarbeit lies Claude Code Team Collaboration. Für CI verbindest du dieselben Kommandos mit CI/CD Setup.

Häufige Fehler

Mische keine Paketmanager. Wenn pnpm-lock.yaml existiert, sollte npm install nicht laufen. Schreibe die Regel in CLAUDE.md und halte packageManager in package.json.

Lass Claude Code nicht .env lesen. Prüfbar ist .env.example; echte Werte bleiben lokal. Nutze .gitignore und permissions.deny gemeinsam.

Docker-Volumes sind tückisch. Ein altes Volume kann eine korrekte Migration kaputt aussehen lassen. Vor jeder Löschung muss Claude Code Ziel, Risiko und Alternative nennen.

Vermeide bypassPermissions auf dem Hauptsystem. Nutze es nur in isolierten Containern oder VMs. Prüfe außerdem Hooks in fremden Repositories, bevor du eine Sitzung startest.

Checkliste

• claude --version und claude doctor funktionieren
• .nvmrc oder .node-version ist vorhanden
• package.json enthält packageManager
• Es gibt nur eine Lockdatei
• .env.example ist aktuell und .env wird ignoriert
• CLAUDE.md dokumentiert Setup, Verbote und Checks
• .claude/settings.json blockiert Secrets, git push und destruktive Befehle
• Der Abschlussbeleg enthält Befehle und Ergebnisse

CTA und Ergebnis

Eine kaputte lokale Umgebung kann Kauf-Links, Formulare, Analytics oder Werbeseiten beschädigen. Für einen wiederverwendbaren Workflow starte mit dem kostenlosen Cheat Sheet, nutze die Vorlagen unter Produkte oder bringe den Prozess mit Training ins Team.

Ich habe den Ablauf getestet, indem ich das Minimalprojekt erstellt, Abhängigkeiten installiert, .env.example kopiert und danach pnpm run doctor, pnpm run check:env und pnpm test ausgeführt habe. Am meisten geholfen haben die Deny-Regeln für .env und der Hook gegen git push oder destruktive Kommandos. In Masas Praxis entstehen Setup-Fehler meist durch nicht dokumentierte Annahmen, nicht durch komplizierte Befehle.