Plankton Qualité du Code

Compétence Plankton Qualité du Code

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

Quand l'utiliser

• Vous souhaitez un formatage et un linting automatiques sur chaque édition de fichier (pas seulement au commit)
• Vous avez besoin d'une défense contre les agents qui modifient les configurations des linters pour contourner les règles au lieu de corriger le code
• Vous voulez un routage par modèle 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)

Fonctionnement

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 : Auto-formatage (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 du 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 les violations JSON
├─ Route vers le niveau de modèle selon la complexité de la violation :
│   ├─ Haiku : formatage, imports, style (codes E/W/F) — délai de 120s
│   ├─ Sonnet : complexité, refactorisation (codes C901, PLR) — délai de 300s
│   └─ Opus : système de types, raisonnement avancé (attribut non résolu) — délai de 600s
├─ Réexécute les phases 1 et 2 pour vérifier les corrections
└─ Code de sortie 0 si tout est propre, code 2 si des violations persistent (signalé à l'agent principal)

Ce que voit l'agent principal

Scénario	Ce que voit l'agent	Code de sortie du hook
Aucune violation	Rien	0
Tout corrigé par le sous-processus	Rien	0
Violations restantes 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 les contournements de règles)

Les LLMs vont modifier .ruff.toml ou biome.json pour désactiver des 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 linters avant qu'elles n'aient lieu
2. Hook Stop — stop_config_guardian.sh détecte les modifications de configuration via git diff à la fin de la session
3. Liste des fichiers protégés — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml, et d'autres

Application du gestionnaire de paquets

Un hook PreToolUse sur Bash bloque les gestionnaires de paquets hérités :

• 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 d'installer.

# Installer les dépendances de base
brew install jaq ruff uv

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

# Démarrer 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 pris en charge automatiquement 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émentaires, pas en conflit

Préoccupation	ECC	Plankton
Renforcement 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 hérités)
Intégration CI	—	Hooks de pré-commit pour git
Routage de modèle	Manuel (/model opus)	Automatique (complexité de violation → niveau)

Combinaison recommandée

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

É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 PreToolUse 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
  }
}

Réglages 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 — ignore la phase 3 (signale simplement les violations)

Variables d'environnement

Variable	Utilité
HOOK_SKIP_SUBPROCESS=1	Ignorer la phase 3, signaler les violations directement
HOOK_SUBPROCESS_TIMEOUT=N	Remplacer le délai 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 repli
• Python : Ruff format/check
• Go : gofmt

Garde anti-sabotage de configuration

Pendant le renforcement 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 l'CI que dans les hooks locaux :

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

Métriques de santé

Suivez :

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