Plankton Code Quality

Plankton Code Quality Skill

Integrationsreferenz für Plankton (Credit: @alxfazio), ein System zur Durchsetzung von Codequalität während des Schreibens für Claude Code. Plankton führt Formatierer und Linter bei jeder Dateiänderung über PostToolUse-Hooks aus und startet dann Claude-Subprozesse, um Verstöße zu beheben, die der Agent nicht erkannt hat.

Wann verwenden

• Du wünschst automatische Formatierung und Linting bei jeder Dateiänderung (nicht nur beim Commit)
• Du benötigst Schutz vor Agenten, die Linter-Konfigurationen ändern, um Tests zu bestehen, anstatt Code zu korrigieren
• Du möchtest abgestuftes Modell-Routing für Korrekturen (Haiku für einfache Stil, Sonnet für Logik, Opus für Typen)
• Du arbeitest mit mehreren Sprachen (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)

Funktionsweise

Drei-Phasen-Architektur

Jedes Mal, wenn Claude Code eine Datei bearbeitet oder schreibt, wird der PostToolUse-Hook multi_linter.sh von Plankton ausgeführt:

Phase 1: Auto-Format (Leise)
├─ Führt Formatierer aus (ruff format, biome, shfmt, taplo, markdownlint)
├─ Behebt 40-50% der Probleme leise
└─ Keine Ausgabe an den Hauptagenten

Phase 2: Verstöße sammeln (JSON)
├─ Führt Linter aus und sammelt nicht behebbare Verstöße
├─ Gibt strukturiertes JSON zurück: {line, column, code, message, linter}
└─ Immer noch keine Ausgabe an den Hauptagenten

Phase 3: Delegieren + Verifizieren
├─ Startet claude -p Subprozess mit Verstößen als JSON
├─ Leitet basierend auf der Komplexität des Verstoßes an die entsprechende Modellstufe:
│   ├─ Haiku: Formatierung, Imports, Stil (E/W/F-Codes) — 120s Timeout
│   ├─ Sonnet: Komplexität, Refactoring (C901, PLR-Codes) — 300s Timeout
│   └─ Opus: Typsystem, tiefes Reasoning (unresolved-attribute) — 600s Timeout
├─ Führt Phase 1+2 erneut aus, um Korrekturen zu verifizieren
└─ Exit 0 wenn sauber, Exit 2 wenn Verstöße verbleiben (dem Hauptagenten gemeldet)

Was der Hauptagent sieht

Szenario	Agent sieht	Hook-Exit
Keine Verstöße	Nichts	0
Alle durch Subprozess behoben	Nichts	0
Verstöße verbleiben nach Subprozess	[hook] N Verstoß(e) verbleiben	2
Hinweis (Duplikate, alte Tools)	[hook:advisory] ...	0

Der Hauptagent sieht nur Probleme, die der Subprozess nicht beheben konnte. Die meisten Qualitätsprobleme werden transparent gelöst.

Konfigurationsschutz (Schutz vor Regel-Manipulation)

LLMs werden .ruff.toml oder biome.json ändern, um Regeln zu deaktivieren, anstatt Code zu korrigieren. Plankton blockiert dies mit drei Ebenen:

1. PreToolUse-Hook — protect_linter_configs.sh blockiert Änderungen an Linter-Konfigurationen, bevor sie stattfinden
2. Stop-Hook — stop_config_guardian.sh erkennt Konfigurationsänderungen über git diff am Session-Ende
3. Geschützte Dateien — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml und weitere

Paketmanager-Durchsetzung

Ein PreToolUse-Hook auf Bash blockiert Legacy-Paketmanager:

• pip, pip3, poetry, pipenv → Blockiert (verwende uv)
• npm, yarn, pnpm → Blockiert (verwende bun)
• Erlaubte Ausnahmen: npm audit, npm view, npm publish

Einrichtung

Schnellstart

Hinweis: Plankton erfordert eine manuelle Installation aus dem Repository. Überprüfe den Code vor der Installation.

# Installiere Kernabhängigkeiten
brew install jaq ruff uv

# Installiere Python-Linter
uv sync --all-extras

# Starte Claude Code — Hooks aktivieren automatisch
claude

Kein Installationsbefehl, keine Plugin-Konfiguration. Die Hooks in .claude/settings.json werden automatisch erkannt, wenn du Claude Code im Plankton-Verzeichnis ausführst.

Integration in eigene Projekte

Um Plankton-Hooks in deinem eigenen Projekt zu verwenden:

1. Kopiere das Verzeichnis .claude/hooks/ in dein Projekt
2. Kopiere die Hook-Konfiguration aus .claude/settings.json
3. Kopiere Linter-Konfigurationsdateien (.ruff.toml, biome.json, etc.)
4. Installiere die Linter für deine Sprachen

Sprachspezifische Abhängigkeiten

Sprache	Erforderlich	Optional
Python	ruff, uv	ty (Typen), vulture (toter Code), bandit (Sicherheit)
TypeScript/JS	biome	oxlint, semgrep, knip (tote Exporte)
Shell	shellcheck, shfmt	—
YAML	yamllint	—
Markdown	markdownlint-cli2	—
Dockerfile	hadolint (>= 2.12.0)	—
TOML	taplo	—
JSON	jaq	—

Kombination mit ECC

Komplementär, nicht überlappend

Aspekt	ECC	Plankton
Code-Qualitätsdurchsetzung	PostToolUse-Hooks (Prettier, tsc)	PostToolUse-Hooks (20+ Linter + Subprozess-Korrekturen)
Sicherheits-Scanning	AgentShield, security-reviewer-Agent	Bandit (Python), Semgrep (TypeScript)
Konfigurationsschutz	—	PreToolUse-Blockierung + Stop-Hook-Erkennung
Paketmanager	Erkennung + Einrichtung	Durchsetzung (Blockiert Legacy-PMs)
CI-Integration	—	Pre-Commit-Hooks für Git
Modell-Routing	Manuell (/model opus)	Automatisch (Verstoß-Komplexität → Stufe)

Empfohlene Kombination

1. Installiere ECC als Plugin (Agenten, Skills, Befehle, Regeln)
2. Füge Plankton-Hooks für Write-Time-Qualitätsdurchsetzung hinzu
3. Verwende AgentShield für Sicherheitsaudits
4. Nutze ECCs Verifizierungsschleife als letzte Hürde vor PRs

Vermeidung von Hook-Konflikten

Wenn sowohl ECC- als auch Plankton-Hooks laufen:

• ECCs Prettier-Hook und Planktons biome-Formatierer können bei JS/TS-Dateien in Konflikt geraten
• Lösung: Deaktiviere ECCs Prettier-PostToolUse-Hook bei Verwendung von Plankton (Planktons biome ist umfassender)
• Beide können nebeneinander für verschiedene Dateitypen existieren (ECC behandelt, was Plankton nicht abdeckt)

Konfigurationsreferenz

Planktons .claude/hooks/config.json steuert das gesamte Verhalten:

{
  "languages": {
    "python": true,
    "shell": true,
    "yaml": true,
    "json": true,
    "toml": true,
    "dockerfile": true,
    "markdown": true,
    "typescript": {
      "enabled": true,
      "js_runtime": "auto",
      "biome_nursery": "warn",
      "semgrep": true
    }
  },
  "phases": {
    "auto_format": true,
    "subprocess_delegation": true
  },
  "subprocess": {
    "tiers": {
      "haiku":  { "timeout": 120, "max_turns": 10 },
      "sonnet": { "timeout": 300, "max_turns": 10 },
      "opus":   { "timeout": 600, "max_turns": 15 }
    },
    "volume_threshold": 5
  }
}

Wichtige Einstellungen:

• Deaktiviere Sprachen, die du nicht verwendest, um Hooks zu beschleunigen
• volume_threshold — Verstöße über dieser Anzahl werden automatisch an eine höhere Modellstufe eskaliert
• subprocess_delegation: false — Phase 3 komplett überspringen (nur Verstöße melden)

Umgebungsüberschreibungen

Variable	Zweck
HOOK_SKIP_SUBPROCESS=1	Phase 3 überspringen, Verstöße direkt melden
HOOK_SUBPROCESS_TIMEOUT=N	Timeout der Stufe überschreiben
HOOK_DEBUG_MODEL=1	Modell-Auswahlentscheidungen protokollieren
HOOK_SKIP_PM=1	Paketmanager-Durchsetzung umgehen

Referenzen

• Plankton (Credit: @alxfazio)
• Plankton REFERENCE.md — Vollständige Architekturdokumentation (Credit: @alxfazio)
• Plankton SETUP.md — Detaillierte Installationsanleitung (Credit: @alxfazio)

ECC v1.8 Ergänzungen

Kopierbares Hook-Profil

Strenges Qualitätsverhalten einstellen:

export ECC_HOOK_PROFILE=strict
export ECC_QUALITY_GATE_FIX=true
export ECC_QUALITY_GATE_STRICT=true

Sprach-Gate-Tabelle

• TypeScript/JavaScript: Biome bevorzugt, Prettier als Fallback
• Python: Ruff format/check
• Go: gofmt

Konfigurations-Manipulationsschutz

Während der Qualitätsdurchsetzung Änderungen an Konfigurationsdateien im selben Durchlauf kennzeichnen:

• biome.json, .eslintrc*, prettier.config*, tsconfig.json, pyproject.toml

Wird eine Konfiguration geändert, um Verstöße zu unterdrücken, ist eine explizite Überprüfung vor dem Merge erforderlich.

CI-Integrationsmuster

Verwende in CI dieselben Befehle wie in lokalen Hooks:

1. Formatierer-Prüfungen ausführen
2. Lint-/Typ-Prüfungen ausführen
3. Bei Fehlern im Strict-Mode sofort abbrechen
4. Zusammenfassung der Korrekturen veröffentlichen

Gesundheitsmetriken

Verfolge:

• durch Gates markierte Bearbeitungen
• durchschnittliche Korrekturzeit
• wiederholte Verstöße nach Kategorie
• Merge-Blockaden aufgrund von Gate-Fehlern