Habilidade de Qualidade de Código Plankton

Referência de integração para Plankton (crédito: @alxfazio), um sistema de aplicação de qualidade de código no momento da escrita para Claude Code. Plankton executa formatadores e linters em cada edição de arquivo via hooks PostToolUse, então gera subprocessos Claude para corrigir violações que o agente não capturou.

Quando Usar

• Você quer formatação e linting automáticos em cada edição de arquivo (não apenas no momento do commit)
• Você precisa de defesa contra agentes que modificam configurações de linter para passar em vez de corrigir o código
• Você quer roteamento de modelo em camadas para correções (Haiku para estilo simples, Sonnet para lógica, Opus para tipos)
• Você trabalha com múltiplos idiomas (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)

Como Funciona

Arquitetura de Três Fases

Toda vez que Claude Code edita ou escreve um arquivo, o hook multi_linter.sh PostToolUse do Plankton é executado:

Phase 1: Auto-Format (Silent)
├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
├─ Fixes 40-50% of issues silently
└─ No output to main agent

Phase 2: Collect Violations (JSON)
├─ Runs linters and collects unfixable violations
├─ Returns structured JSON: {line, column, code, message, linter}
└─ Still no output to main agent

Phase 3: Delegate + Verify
├─ Spawns claude -p subprocess with violations JSON
├─ Routes to model tier based on violation complexity:
│   ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout
│   ├─ Sonnet: complexity, refactoring (C901, PLR codes, oxlint complexity) — 300s timeout
│   └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout
├─ Re-runs Phase 1+2 to verify fixes
└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)

O Que o Agente Principal Vê

O agente principal só vê problemas que o subprocesso não conseguiu corrigir. A maioria dos problemas de qualidade é resolvida de forma transparente.

Proteção de Configuração (Defesa Contra Manipulação de Regras)

LLMs modificarão .ruff.toml ou biome.json para desabilitar regras em vez de corrigir o código. Plankton bloqueia isso com três camadas:

1. Hook PreToolUse — protect_linter_configs.sh bloqueia edições em todas as configurações de linter antes que aconteçam
2. Hook Stop — stop_config_guardian.sh detecta mudanças de configuração via git diff no final da sessão
3. Lista de arquivos protegidos — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml, e mais

Aplicação do Gerenciador de Pacotes

Um hook PreToolUse no Bash bloqueia gerenciadores de pacotes legados:

• pip, pip3, poetry, pipenv → Bloqueado (use uv)
• npm, yarn, pnpm → Bloqueado (use bun)
• Exceções permitidas: npm audit, npm view, npm publish

Configuração

Início Rápido

Nota: Plankton requer instalação manual do seu repositório. Revise o código antes de instalar.

# Install core dependencies
brew install jaq ruff uv

# Install Python linters
uv sync --all-extras

# Start Claude Code — hooks activate automatically
claude

Sem comando de instalação, sem configuração de plugin. Os hooks em .claude/settings.json são capturados automaticamente quando você executa Claude Code no diretório Plankton.

Integração Por Projeto

Para usar os hooks do Plankton em seu próprio projeto:

1. Copie o diretório .claude/hooks/ para o seu projeto
2. Copie a configuração do hook .claude/settings.json
3. Copie os arquivos de configuração do linter (.ruff.toml, biome.json, etc.)
4. Instale os linters para seus idiomas

Dependências Específicas de Idioma

Emparelhamento com ECC

Complementares, Não Sobrepostos

…