Plankton Code Quality

Plankton Code Quality Skill

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

Wann verwenden

• Sie möchten automatische Formatierung und Linting bei jeder Dateibearbeitung (nicht nur beim Commit)
• Sie benötigen Schutz davor, dass Agenten Linter-Konfigurationen ändern, um Regeln zu umgehen, anstatt Code zu korrigieren
• Sie möchten abgestufte Modellrouten für Korrekturen (Haiku für einfache Formatierung, Sonnet für Logik, Opus für Typen)
• Sie arbeiten mit mehreren Sprachen (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)

Wie es funktioniert

Drei-Phasen-Architektur

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

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

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

Phase 3: Delegieren + Überprüfen
├─ Startet `claude -p` Subprozess mit dem JSON der Verstöße
├─ Routet basierend auf der Komplexität des Verstoßes zu einer Modellebene:
│   ├─ Haiku: Formatierung, Importe, Stil (E/W/F-Codes) — Timeout 120 s
│   ├─ Sonnet: Komplexität, Refactoring (C901, PLR-Codes) — Timeout 300 s
│   └─ Opus: Typsystem, tiefgehende Argumentation (nicht aufgelöste Attribute) — Timeout 600 s
├─ Führt Phase 1+2 erneut aus, um Korrekturen zu überprüfen
└─ Exit 0, wenn sauber; Exit 2, wenn Verstöße bestehen bleiben (wird an den Hauptagenten gemeldet)

Was der Hauptagent sieht

Szenario	Agent sieht	Hook-Exit
Keine Verstöße	Nichts	0
Alle durch Subprozess behoben	Nichts	0
Verstöße bestehen 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 (Abwehr gegen Regelspiele)

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 Bearbeitungen aller Linter-Konfigurationen, bevor sie stattfinden
2. Stop-Hook — stop_config_guardian.sh erkennt Konfigurationsänderungen über git diff am Sitzungsende
3. Geschützte Dateiliste — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml und mehr

Durchsetzung von Paketmanagern

Ein PreToolUse-Hook auf Bash blockiert veraltete Paketmanager:

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

Einrichtung

Schnellstart

Hinweis: Plankton erfordert die manuelle Installation aus seinem Repository. Überprüfen Sie den Code vor der Installation.

# Installieren Sie die Kernabhängigkeiten
brew install jaq ruff uv

# Installieren Sie Python-Linter
uv sync --all-extras

# Starten Sie Claude Code – Hooks werden automatisch aktiviert
claude

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

Projektübergreifende Integration

Um Plankton-Hooks in Ihrem eigenen Projekt zu verwenden:

1. Kopieren Sie das Verzeichnis .claude/hooks/ in Ihr Projekt
2. Kopieren Sie die Hook-Konfiguration .claude/settings.json
3. Kopieren Sie die Linter-Konfigurationsdateien (.ruff.toml, biome.json, usw.)
4. Installieren Sie die Linter für Ihre 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

Ergänzend, nicht überlappend

Bereich	ECC	Plankton
Durchsetzung Code-Qualität	PostToolUse-Hooks (Prettier, tsc)	PostToolUse-Hooks (20+ Linter + Subprozess-Korrekturen)
Sicherheitsscans	AgentShield, security-reviewer Agent	Bandit (Python), Semgrep (TypeScript)
Konfigurationsschutz	—	PreToolUse-Blockaden + Stop-Hook-Erkennung
Paketmanager	Erkennung + Einrichtung	Durchsetzung (blockiert veraltete PMs)
CI-Integration	—	Pre-Commit-Hooks für Git
Modellrouting	Manuell (/model opus)	Automatisch (Verstoßkomplexität → Ebene)

Empfohlene Kombination

1. Installieren Sie ECC als Ihr Plugin (Agenten, Fähigkeiten, Befehle, Regeln)
2. Fügen Sie Plankton-Hooks für schreibzeitbasierte Qualitätssicherung hinzu
3. Verwenden Sie AgentShield für Sicherheitsaudits
4. Verwenden Sie ECCs Verifizierungsschleife als letztes Tor vor PRs

Vermeidung von Hook-Konflikten

Wenn sowohl ECC als auch Plankton-Hooks ausgeführt werden:

• ECCs Prettier-Hook und Planktons biome-Formatierer könnten bei JS/TS-Dateien in Konflikt geraten
• Lösung: Deaktivieren Sie ECCs Prettier-PostToolUse-Hook bei Verwendung von Plankton (Planktons biome ist umfassender)
• Beide können bei verschiedenen Dateitypen koexistieren (ECC übernimmt, 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:

• Deaktivieren Sie Sprachen, die Sie nicht verwenden, um Hooks zu beschleunigen
• volume_threshold — Verstöße > dieser Anzahl werden automatisch auf eine höhere Modellebene eskaliert
• subprocess_delegation: false — Phase 3 vollständig überspringen (nur Verstöße melden)

Umgebungsüberschreibungen

Variable	Zweck
HOOK_SKIP_SUBPROCESS=1	Phase 3 überspringen, Verstöße direkt melden
HOOK_SUBPROCESS_TIMEOUT=N	Eigenen Timeout für die Modellebene setzen
HOOK_DEBUG_MODEL=1	Entscheidungen bei der Modellauswahl protokollieren
HOOK_SKIP_PM=1	Paketmanager-Durchsetzung umgehen

Referenzen

• Plankton (Quelle: @alxfazio)
• Plankton REFERENCE.md — Vollständige Architektur-Dokumentation (Quelle: @alxfazio)
• Plankton SETUP.md — Detaillierte Installationsanleitung (Quelle: @alxfazio)

ECC v1.8 Ergänzungen

Kopierbares Hook-Profil

Stellen Sie striktes Qualitätsverhalten ein:

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

Sprachgate-Tabelle

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

Konfigurationsmanipulationsschutz

Markieren Sie während der Qualitätssicherung Änderungen an Konfigurationsdateien in derselben Iteration:

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

Wenn die Konfiguration geändert wird, um Verstöße zu unterdrücken, ist vor der Zusammenführung eine explizite Überprüfung erforderlich.

CI-Integrationsmuster

Verwenden Sie in CI dieselben Befehle wie in lokalen Hooks:

1. Formatierungsprüfungen ausführen
2. Lint-/Typ-Prüfungen ausführen
3. Im strikten Modus schnell fehlschlagen
4. Zusammenfassung der Korrekturmaßnahmen veröffentlichen

Gesundheitsmetriken

Verfolgen:

• von Gates markierte Bearbeitungen
• durchschnittliche Korrekturzeit
• wiederholte Verstöße nach Kategorie
• Zusammenführungsblockaden aufgrund von Gate-Fehlern