Plankton - Qualité du Code à l'Écriture

Compétence Plankton pour la Qualité du Code

Référence d'intégration pour Plankton (crédit : @alxfazio), un système d'application des règles de qualité du code à l'écriture pour Claude Code. Plankton exécute des formateurs et des linters sur chaque édition de fichier via des hooks PostToolUse, puis lance des sous-processus Claude pour corriger les violations que l'agent n'a pas détectées.

Quand l'Utiliser

• Vous voulez un formatage et un linting automatiques à chaque édition de fichier (pas seulement au moment du commit)
• Vous avez besoin d'une protection contre les agents qui modifient les configurations des linters pour passer les tests au lieu de corriger le code
• Vous voulez un routage hiérarchique des modèles pour les corrections (Haiku pour le style simple, Sonnet pour la logique, Opus pour les types)
• Vous travaillez avec plusieurs langages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)

Comment ça Fonctionne

Architecture en Trois Phases

Chaque fois que Claude Code édite ou écrit un fichier, le hook PostToolUse multi_linter.sh de Plankton s'exécute :

Phase 1 : Formatage Automatique (Silencieux)
├─ Exécute les formateurs (ruff format, biome, shfmt, taplo, markdownlint)
├─ Corrige 40 à 50 % des problèmes silencieusement
└─ Aucune sortie vers l'agent principal

Phase 2 : Collecte des Violations (JSON)
├─ Exécute les linters et collecte les violations non corrigeables
├─ Renvoie un JSON structuré : {line, column, code, message, linter}
└─ Toujours aucune sortie vers l'agent principal

Phase 3 : Délégation + Vérification
├─ Lance un sous-processus claude -p avec le JSON des violations
├─ Route vers le niveau de modèle en fonction de la complexité de la violation :
│   ├─ Haiku : formatage, imports, style (codes E/W/F) — timeout 120s
│   ├─ Sonnet : complexité, refactorisation (codes C901, PLR) — timeout 300s
│   └─ Opus : système de types, raisonnement profond (unresolved-attribute) — timeout 600s
├─ Relance les phases 1+2 pour vérifier les corrections
└─ Sortie 0 si propre, Sortie 2 si des violations persistent (signalé à l'agent principal)

Ce que Voit l'Agent Principal

Scénario	Ce que voit l'agent	Sortie du hook
Aucune violation	Rien	0
Tout corrigé par le sous-processus	Rien	0
Violations persistantes après le sous-processus	[hook] N violation(s) restante(s)	2
Avis (doublons, outils obsolètes)	[hook:advisory] ...	0

L'agent principal ne voit que les problèmes que le sous-processus n'a pas pu corriger. La plupart des problèmes de qualité sont résolus de manière transparente.

Protection des Configurations (Défense contre la Manipulation des Règles)

Les LLM peuvent modifier .ruff.toml ou biome.json pour désactiver les règles plutôt que de corriger le code. Plankton bloque cela avec trois couches :

1. Hook PreToolUse — protect_linter_configs.sh bloque les modifications de toutes les configurations de linter avant qu'elles ne se produisent
2. Hook Stop — stop_config_guardian.sh détecte les changements de configuration via git diff à la fin de la session
3. Liste de fichiers protégés — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml, et plus

Application du Gestionnaire de Paquets

Un hook PreToolUse sur Bash bloque les gestionnaires de paquets obsolètes :

• pip, pip3, poetry, pipenv → Bloqués (utilisez uv)
• npm, yarn, pnpm → Bloqués (utilisez bun)
• Exceptions autorisées : npm audit, npm view, npm publish

Configuration

Démarrage Rapide

Remarque : Plankton nécessite une installation manuelle depuis son dépôt. Examinez le code avant de l'installer.

# Installer les dépendances principales
brew install jaq ruff uv

# Installer les linters Python
uv sync --all-extras

# Lancer Claude Code — les hooks s'activent automatiquement
claude

Pas de commande d'installation, pas de configuration de plugin. Les hooks dans .claude/settings.json sont automatiquement détectés lorsque vous exécutez Claude Code dans le répertoire Plankton.

Intégration par Projet

Pour utiliser les hooks Plankton dans votre propre projet :

1. Copiez le répertoire .claude/hooks/ dans votre projet
2. Copiez la configuration des hooks .claude/settings.json
3. Copiez les fichiers de configuration des linters (.ruff.toml, biome.json, etc.)
4. Installez les linters pour vos langages

Dépendances par Langage

Langage	Requis	Optionnel
Python	ruff, uv	ty (types), vulture (code mort), bandit (sécurité)
TypeScript/JS	biome	oxlint, semgrep, knip (exports morts)
Shell	shellcheck, shfmt	—
YAML	yamllint	—
Markdown	markdownlint-cli2	—
Dockerfile	hadolint (>= 2.12.0)	—
TOML	taplo	—
JSON	jaq	—

Association avec ECC

Complémentaire, Pas Redondant

Préoccupation	ECC	Plankton
Application de la qualité du code	Hooks PostToolUse (Prettier, tsc)	Hooks PostToolUse (20+ linters + corrections par sous-processus)
Analyse de sécurité	AgentShield, agent security-reviewer	Bandit (Python), Semgrep (TypeScript)
Protection des configurations	—	Blocage PreToolUse + détection par hook Stop
Gestionnaire de paquets	Détection + configuration	Application (bloque les PM obsolètes)
Intégration CI	—	Hooks pre-commit pour git
Routage des modèles	Manuel (/model opus)	Automatique (complexité de violation → niveau)

Combinaison Recommandée

1. Installez ECC comme plugin (agents, compétences, commandes, règles)
2. Ajoutez les hooks Plankton pour l'application de la qualité à l'écriture
3. Utilisez AgentShield pour les audits de sécurité
4. Utilisez la boucle de vérification d'ECC comme porte finale avant les PR

Éviter les Conflits de Hooks

Si vous exécutez à la fois les hooks ECC et Plankton :

• Le hook Prettier d'ECC et le formateur biome de Plankton peuvent entrer en conflit sur les fichiers JS/TS
• Solution : désactivez le hook PostToolUse Prettier d'ECC lorsque vous utilisez Plankton (le biome de Plankton est plus complet)
• Les deux peuvent coexister sur différents types de fichiers (ECC gère ce que Plankton ne couvre pas)

Référence de Configuration

Le fichier .claude/hooks/config.json de Plankton contrôle tout le comportement :

{
  "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
  }
}

Paramètres clés :

• Désactivez les langages que vous n'utilisez pas pour accélérer les hooks
• volume_threshold — les violations > ce nombre sont automatiquement escaladées vers un niveau de modèle supérieur
• subprocess_delegation: false — saute complètement la phase 3 (signale simplement les violations)

Surcharges d'Environnement

Variable	Objectif
HOOK_SKIP_SUBPROCESS=1	Ignorer la phase 3, signaler directement les violations
HOOK_SUBPROCESS_TIMEOUT=N	Remplacer le délai d'attente du niveau
HOOK_DEBUG_MODEL=1	Journaliser les décisions de sélection du modèle
HOOK_SKIP_PM=1	Contourner l'application du gestionnaire de paquets

Références

• Plankton (crédit : @alxfazio)
• Plankton REFERENCE.md — Documentation complète de l'architecture (crédit : @alxfazio)
• Plankton SETUP.md — Guide d'installation détaillé (crédit : @alxfazio)

Ajouts ECC v1.8

Profil de Hook Copiable

Définir un comportement de qualité strict :

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

Tableau des Portes de Langage

• TypeScript/JavaScript : Biome préféré, Prettier en fallback
• Python : Ruff format/check
• Go : gofmt

Garde de Modification de Configuration

Pendant l'application de la qualité, signalez les modifications des fichiers de configuration dans la même itération :

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

Si la configuration est modifiée pour supprimer des violations, exigez une révision explicite avant la fusion.

Modèle d'Intégration CI

Utilisez les mêmes commandes dans CI que les hooks locaux :

1. exécuter les vérifications de formatage
2. exécuter les vérifications de lint/type
3. échouer rapidement en mode strict
4. publier un résumé des corrections

Métriques de Santé

Suivez :

• les modifications signalées par les portes
• le temps de correction moyen
• les violations répétées par catégorie
• les blocages de fusion dus aux échecs des portes