Claude Code – Projektstruktur

# Analytics Platform – Projekt-Kontext

## Stack & Umgebung
- Python 3.11 · pandas, polars, sqlalchemy, dbt 1.7
- Datenbank: Google BigQuery (Projekt: `acme-analytics-prod`)
- BI-Tool: Looker (LookML) · Reporting: Jupyter + nbconvert
- Versionierung: GitHub · CI/CD: GitHub Actions

## Datenmodell-Überblick
# Schichten (dbt layers)
raw/       → Rohdaten, nie direkt abfragen
staging/   → 1:1 Abbilder, Typen gecasted, keine Joins
intermediate/ → Business-Joins, berechnete Felder
marts/     → Fertige Reporting-Tabellen (fact_*, dim_*)

## Wichtigste Tabellen
- `marts.fact_orders`     PK: order_id, FK: customer_id, product_id
- `marts.dim_customers`   PK: customer_id, SCD Typ 2
- `marts.dim_products`    PK: product_id, Hierarchie: category→subcategory

## Coding-Konventionen
- SQL: snake_case, CTEs bevorzugen, keine Subqueries in FROM
- Python: type hints Pflicht, docstrings bei jeder Funktion
- Metriken immer als Float, nie gerundet in der Quelle
- Datumsfelder: immer UTC, Format YYYY-MM-DD

## Sicherheitsregeln
NIEMALS: DELETE/TRUNCATE ohne explizite Bestätigung
NIEMALS: Direkt auf raw-Layer joinen
IMMER:   Queries mit LIMIT testen, dann ohne

{
  "mcpServers": {
    "bigquery": {
      "command": "mcp-server-bigquery",
      "env": { "GOOGLE_PROJECT_ID": "acme-analytics-prod" }
    },
    "github": {
      "command": "mcp-server-github",
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "dbt-cloud": {
      "command": "mcp-server-dbt",
      "env": { "DBT_CLOUD_API_KEY": "${DBT_CLOUD_API_KEY}" }
    },
    "slack": {
      "command": "mcp-server-slack",
      "env": { "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}" }
    }
  }
}

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(python:*)",        // Python uneingeschränkt
      "Bash(dbt:*)",           // dbt-Befehle erlaubt
      "Bash(git:*)",           // Git-Operationen ok
      "Read(**)",              // Alle Dateien lesen
      "Write(models/**)",      // Nur im models/-Ordner schreiben
      "mcp__bigquery__query"  // BigQuery-Abfragen erlaubt
    ],
    "ask": [
      "Bash(psql:*)",          // DB-Zugriff: immer fragen
      "Write(seeds/**)"        // Seed-Daten: fragen
    ],
    "deny": [
      "Bash(rm:*)",            // Löschen verboten
      "Bash(*:*DELETE*)"       // SQL DELETE verboten
    ]
  },
  "hooks": {
    "PreToolUse": [".claude/hooks/validate-sql.sh"],
    "PostToolUse": [".claude/hooks/log-queries.sh"]
  }
}

# dbt Model Review

Reviewe das aktuelle dbt-Model (`$ARGUMENTS` oder aktuell geöffnete Datei).
Prüfe folgende Punkte und erstelle einen strukturierten Report:

## 1. Datenqualität
- Sind alle Primärschlüssel eindeutig (dbt test unique)?
- Gibt es not_null Violations auf wichtigen Feldern?
- Prüfe auf mögliche Duplikate durch fehlende DISTINCT

## 2. Performance
- Werden Partitionen korrekt genutzt (_PARTITIONTIME)?
- Gibt es unnötige Full Table Scans?
- Können CTEs durch Materialisierung beschleunigt werden?

## 3. Code-Qualität (prüfe gegen .claude/rules/sql-style.md)
- SELECT * vorhanden?
- Alle Joins mit expliziten Bedingungen?
- Kommentare bei komplexer Business-Logik?

## Output-Format
Erstelle eine Tabelle: | Issue | Severity | Fix |
Severity: 🔴 Kritisch / 🟡 Warnung / 🟢 Hinweis

# Neue Metrik erstellen

Erstelle eine neue Business-Metrik für `$ARGUMENTS`.

## Schritte
1. Lese `models/marts/` um bestehende Tabellen zu verstehen
2. Erstelle `models/marts/metrics/metric_$ARGUMENTS.sql`
3. Folge dem Template in `models/_templates/metric_template.sql`
4. Erstelle passende Tests in `tests/metrics/`
5. Füge Beschreibung in `models/marts/schema.yml` hinzu
6. Führe `dbt compile --select metric_$ARGUMENTS` zur Validierung aus

Frage VOR dem Erstellen: Wie soll aggregiert werden (SUM/AVG/COUNT)?
Welcher Zeitraum ist relevant?

# EDA Report Skill
## Use when: User wants to explore a dataset, understand distributions, find anomalies
## Do NOT use for: Production pipeline code, model creation, SQL optimization

## Workflow
1. Lade die Datei/Tabelle und zeige .info(), .describe(), .head()
2. Fehlende Werte: Heatmap + prozentuale Übersicht
3. Numerische Spalten: Histogramme + Outlier-Detection (IQR-Methode)
4. Kategorische Spalten: Value Counts + Top-10 Bar Charts
5. Korrelationsmatrix (Spearman für robustere Ergebnisse)
6. Zeitreihen: Trend, Saisonalität, Breaks identifizieren
7. Erstelle Summary-Markdown mit Key Findings

## Output-Format
- Jupyter Notebook mit klaren Abschnittstiteln
- Jede Visualisierung mit Interpretation (2–3 Sätze)
- Finale Empfehlungen: Was braucht Aufmerksamkeit?

---
name: data-quality-auditor
description: Prüft Datensätze auf Qualitätsprobleme. Trigger: "datenqualität",
             "anomalien", "data quality", "überprüfe die daten"
model: claude-haiku-4-5   # Schnell & günstig für repetitive Checks
tools: [Read, Bash, mcp__bigquery__query]
---

Du bist ein Datenqualitäts-Spezialist. Deine Aufgabe:

## Prüfkatalog
1. Vollständigkeit: NULL-Raten pro Spalte, Pflichtfelder
2. Eindeutigkeit: Duplikate in PK-Feldern, doppelte Transaktionen
3. Konsistenz: Referentielle Integrität, FK-Verletzungen
4. Aktualität: Letzte Aktualisierung, Freshness-Checks
5. Plausibilität: Negative Beträge, Zukunftsdaten, Outlier >3σ

## Output
Erstelle immer einen Data Quality Score (0-100) mit Begründung.
Liste Issues nach Severity geordnet mit SQL-Queries zur Verifikation.

#!/bin/bash
# Wird VOR jeder Bash-Ausführung aufgerufen
# Stoppt gefährliche SQL-Operationen

COMMAND="$1"

# Blocke DELETE/TRUNCATE/DROP ohne Bestätigung
if echo "$COMMAND" | grep -iE "(DELETE|TRUNCATE|DROP TABLE)"; then
  echo "⛔ BLOCKED: Destructive SQL operation detected"
  echo "Reason: DELETE/TRUNCATE/DROP requires manual confirmation"
  exit 1  # Exit 1 = Claude darf NICHT ausführen
fi

# Warne bei BigQuery Full Table Scans (kein Partition-Filter)
if echo "$COMMAND" | grep -i "FROM \`acme" | grep -v "_PARTITIONTIME"; then
  echo "⚠️  WARNING: Query may scan full table (no partition filter)"
  echo "Estimated cost: potentially high. Add _PARTITIONTIME filter."
  # Exit 0 = erlaubt aber mit Warnung
fi

exit 0

#!/bin/bash
# Loggt alle ausgeführten Befehle für Audit-Trail

TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
COMMAND="$1"
LOG_FILE=".claude/logs/query-audit.log"

mkdir -p .claude/logs
echo "[$TIMESTAMP] $COMMAND" >> "$LOG_FILE"

# Bei dbt-Ausführungen: Ergebnis in Slack posten
if echo "$COMMAND" | grep -q "dbt run"; then
  curl -s -X POST "$SLACK_WEBHOOK" \
    -d '{"text":"🔄 dbt run executed by Claude Code: '"$COMMAND"'"}'
fi