# Claude Code Projektregeln — Node.js/TypeScript Services & CLIs

**Projekt:** `<Projektname eintragen>`
**Stack:** Node.js 20+, TypeScript, npm/yarn
**Typ:** CLI-Tool, Microservice, Backend-Worker
**Zuletzt aktualisiert:** `<Datum eintragen>`

---

## 🎯 Verhaltens-Leitplanken (über allem)

Diese 4 Prinzipien verhindern Over-Engineering, stille Annahmen und fehlende Verifikation.

### 1. Denken vor Coden
```
✅ Annahmen EXPLIZIT aussprechen, nicht still voraussetzen
✅ Bei Mehrdeutigkeit: mehrere Interpretationen zeigen, nicht raten
✅ Bei Unklarheit: STOPPEN und fragen — keine Vermutungen
❌ NIEMALS still eine Interpretation wählen und loscoden
```

### 2. Einfachheit zuerst
```
✅ Minimaler Code der das Problem löst — nichts mehr
✅ Keine spekulativen Features für "könnte später nützlich sein"
✅ Keine Abstraktionen für Single-Use-Code
❌ NIEMALS ungefragte Flexibilität einbauen
```

### 3. Chirurgische Änderungen
```
✅ Nur anfassen was wirklich geändert werden muss
✅ Existierenden Stil matchen, nicht "verbessern"
❌ NIEMALS angrenzenden funktionierenden Code refactorn
```

### 4. Ziel-getriebene Ausführung
```
✅ Request in verifizierbare Erfolgskriterien umwandeln
❌ NIEMALS "sollte funktionieren" ohne Verifikation
```

---

## 📐 Node.js/TypeScript Coding-Regeln

### REGEL 01 — Kein Stub-Code
```typescript
// ❌ VERBOTEN
export function processData(input: any): void {} // TODO

// ✅ KORREKT — vollständig oder gar nicht
export function processData(input: InputType): OutputType {
  const validated = validate(input)
  return transform(validated)
}
```

### REGEL 02 — TypeScript ohne `any`
```typescript
// ❌ function parse(data: any): any
// ✅ function parse(data: unknown): ParsedData
```

### REGEL 03 — Error-Handling explizit
```typescript
// ✅ Services/CLI-Commands mit try/catch
export async function main(args: string[]) {
  try {
    const result = await processTask(args)
    console.log(result)
    process.exit(0)
  } catch (error) {
    logger.error('Task failed', { error })
    console.error(`Error: ${error instanceof Error ? error.message : 'Unknown'}`)
    process.exit(1)
  }
}
```

### REGEL 04 — Kein `console.log` in Services
```typescript
// ❌ console.log(result)
// ✅ logger.info('Task completed', { result })
```

### REGEL 05 — async/await für I/O
```typescript
// ✅ File/Network/DB-Operationen immer async
async function readConfig(): Promise<Config> {
  const data = await fs.readFile('config.json', 'utf8')
  return JSON.parse(data)
}
```

### REGEL 06 — Environment-Variablen mit Validation
```typescript
import { z } from 'zod'

const envSchema = z.object({
  API_KEY: z.string().min(1),
  DB_URL: z.string().url(),
  PORT: z.string().regex(/^\d+$/).transform(Number),
})

export const env = envSchema.parse(process.env)
```

### REGEL 07 — UTC für alle Timestamps
```typescript
// ❌ new Date()
// ✅ new Date().toISOString()
```

### REGEL 08 — Secrets nie committen
```bash
# .gitignore muss enthalten
.env
.env.*
*.pem
config/secrets.json
```

### REGEL 09 — Exit-Codes explizit
```typescript
// CLI-Tools: 0 = Success, 1 = Error, 2 = Invalid Args
if (!args.length) {
  console.error('Usage: command <arg>')
  process.exit(2)
}
```

### REGEL 10 — Dependencies exakt gepinnt (Production)
```json
// package.json für Production-Services
{
  "dependencies": {
    "fastify": "4.15.0",  // ✅ exakte Version
    "zod": "3.21.4"
  }
}
```

---

## ✅ Definition of Done — CLI-Kommando

Ein CLI-Tool ist NICHT fertig bis:

```
[ ] TypeScript ohne `any` — alle Args typisiert
[ ] Argument-Parsing + Validation (z.B. yargs/commander)
[ ] --help zeigt alle Optionen + Beispiele
[ ] Error-Handling: try/catch + sinnvolle Error-Messages
[ ] Exit-Codes korrekt (0 = OK, 1 = Error, 2 = Args)
[ ] Tests: happy path + missing args + invalid input
[ ] npm test → alle Tests grün (Ausgabe zeigen)
[ ] Manuell getestet → Output zeigen
[ ] README mit Installation + Usage
```

---

## ✅ Definition of Done — Microservice/Worker

```
[ ] TypeScript ohne `any`
[ ] Environment-Config validiert (Zod/env-Schema)
[ ] Error-Handling mit Logging
[ ] Graceful Shutdown (SIGTERM/SIGINT-Handler)
[ ] Health-Check-Endpoint (falls HTTP-Service)
[ ] Tests: Unit + Integration
[ ] Docker-ready (Dockerfile, nicht zu root laufen lassen)
[ ] npm test → alle Tests grün
[ ] Lokal gestartet → Logs zeigen
```

---

## 🚨 Kritische Verbote — IMMER gültig

```
❌ NIEMALS `/init` ausführen (überschreibt CLAUDE.md)
❌ NIEMALS diese CLAUDE.md ohne explizite Anweisung ändern
❌ NIEMALS mehrere Features gleichzeitig implementieren
❌ NIEMALS weitermachen wenn Tests rot sind
❌ NIEMALS .env committen
❌ NIEMALS Code ohne vorherigen Test-Plan schreiben
❌ NIEMALS "es funktioniert" sagen ohne Beweis
❌ NIEMALS zur nächsten Aufgabe ohne Status-Update
❌ NIEMALS ungepinnte Dependencies (^~) in Production
```

---

## 🔬 Proof-Protokoll (Pflicht vor "fertig")

Beweis ist NICHT optional. Vor jedem "fertig" zeigen:

```bash
# 1. Tests
npm test
# Ausgabe: X passed, 0 failed

# 2. Build
npm run build
# Ausgabe: Build completed

# 3. TypeScript
npx tsc --noEmit
# Ausgabe: 0 Errors

# 4. Lint
npm run lint
# Ausgabe: 0 Errors

# 5. Manual-Test
# CLI: ./dist/cli.js --help → Output zeigen
# Service: curl http://localhost:3000/health → Response zeigen
```

---

## 🔐 Security-Basics

```
[ ] Alle Inputs validieren (Zod/Joi/etc.)
[ ] Secrets aus .env, nie hardcoded
[ ] Keine PII in Logs (API-Keys, Tokens, Passwörter)
[ ] File-Paths validieren (kein Path Traversal)
[ ] External Commands sanitizen (keine Shell-Injection)
[ ] Dependencies: npm audit → 0 critical
[ ] Docker: USER nicht root (z.B. node:1000)
```

---

## 📝 Arbeitsprotokoll — Kurzform

### Vor der Implementierung
1. Aufgabe in kleinste Einheit zerlegen (1 Command, 1 Worker, 1 Helper)
2. Betroffene Dateien identifizieren
3. Test-Plan: Was ist Success? Was sind Fehlerfälle?
4. Bei Unklarheit: FRAGEN

### Implementierung
1. Eine Einheit auf einmal
2. Zuerst Test (wenn möglich), dann Code
3. Nach jeder Datei: mentaler DoD-Check

### Nach der Implementierung
1. Tests ausführen → Ausgabe zeigen
2. Build/Lint/TypeCheck → Ausgabe zeigen
3. CLI/Service manuell testen → Output zeigen
4. ERST DANN "fertig" melden

---

## 📦 Standard-Befehle

```bash
# Installation
npm install           # Dependencies installieren
# oder: yarn install

# Development
npm run dev           # Watch-Mode (tsx watch / nodemon)
npm run build         # TypeScript kompilieren
npm start             # Kompilierte Version starten

# Qualität
npm test              # Tests ausführen
npm run lint          # ESLint
npx tsc --noEmit      # TypeScript-Check

# CLI spezifisch
npm link              # CLI lokal verfügbar machen (Dev)
npm pack              # .tgz erstellen für Distribution

# Docker (falls genutzt)
docker build -t myservice .
docker run --env-file .env myservice
```

---

## 🎓 Self-Check vor jeder Antwort

```
[ ] Habe ich still eine Annahme getroffen? → Explizit machen
[ ] Baue ich mehr als gefragt? → Zurückschneiden
[ ] Ändere ich Code der nicht geändert werden muss? → Zurückdrehen
[ ] Kann ich verifizieren ob es funktioniert? → Kriterium definieren
[ ] Habe ich Beweis-Ausgaben gezeigt? → Nicht nur "sollte klappen"
```

---

## 🐳 Docker Best-Practices (optional)

```dockerfile
# Multi-Stage Build — nur Production-Abhängigkeiten
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# Nicht als root laufen
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
```

---

**Anpassung erwünscht** — diese Vorlage ist ein Starter, kein Dogma.
Ergänze projekt-spezifische Regeln (z.B. Message-Queue-Patterns, Cron-Jobs, etc.).