plankton-code-quality

Skill de Qualidade de Código com Plankton

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

Quando Usar

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

Como Funciona

Arquitetura de Três Fases

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

Fase 1: Auto-Format (Silencioso)
├─ Executa formatadores (ruff format, biome, shfmt, taplo, markdownlint)
├─ Corrige 40-50% dos problemas silenciosamente
└─ Sem saída para o agente principal

Fase 2: Coletar Violações (JSON)
├─ Executa linters e coleta violações não corrigíveis
├─ Retorna JSON estruturado: {line, column, code, message, linter}
└─ Ainda sem saída para o agente principal

Fase 3: Delegar + Verificar
├─ Gera subprocesso claude -p com o JSON de violações
├─ Roteia para o nível de modelo baseado na complexidade da violação:
│   ├─ Haiku: formatação, imports, estilo (códigos E/W/F) — timeout de 120s
│   ├─ Sonnet: complexidade, refatoração (códigos C901, PLR) — timeout de 300s
│   └─ Opus: sistema de tipos, raciocínio profundo (atributo não resolvido) — timeout de 600s
├─ Reexecuta Fase 1+2 para verificar correções
└─ Exit 0 se limpo, Exit 2 se violações permanecerem (reportado ao agente principal)

O que o Agente Principal Vê

Cenário	Agente vê	Exit do hook
Sem violações	Nada	0
Todas corrigidas pelo subprocesso	Nada	0
Violações permanecem após subprocesso	[hook] N violação(ões) permanece(m)	2
Aviso (duplicatas, ferramentas antigas)	[hook:aviso] ...	0

O agente principal só vê problemas que o subprocesso não pôde 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 código. O 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 elas aconteçam
2. Hook Stop — stop_config_guardian.sh detecta alterações 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 de Gerenciador de Pacotes

Um hook PreToolUse em Bash bloqueia gerenciadores de pacotes legados:

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

Configuração

Início Rápido

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

# Instalar dependências principais
brew install jaq ruff uv

# Instalar linters Python
uv sync --all-extras

# Iniciar Claude Code — hooks ativam automaticamente
claude

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

Integração por Projeto

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

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

Dependências por Linguagem

Linguagem	Obrigatório	Opcional
Python	ruff, uv	ty (tipos), vulture (código morto), bandit (segurança)
TypeScript/JS	biome	oxlint, semgrep, knip (exportações mortas)
Shell	shellcheck, shfmt	—
YAML	yamllint	—
Markdown	markdownlint-cli2	—
Dockerfile	hadolint (>= 2.12.0)	—
TOML	taplo	—
JSON	jaq	—

Emparelhamento com ECC

Complementares, Não Sobrepostos

Aspecto	ECC	Plankton
Reforço de qualidade de código	Hooks PostToolUse (Prettier, tsc)	Hooks PostToolUse (20+ linters + correções subprocesso)
Varredura de segurança	AgentShield, agente security-reviewer	Bandit (Python), Semgrep (TypeScript)
Proteção de configuração	—	Bloqueio PreToolUse + detecção Stop hook
Gerenciador de pacotes	Detecção + configuração	Aplicação (bloqueia PMs legados)
Integração CI	—	Hooks pré-commit para git
Roteamento de modelo	Manual (/model opus)	Automático (complexidade da violação → nível)

Combinação Recomendada

1. Instale ECC como seu plugin (agentes, skills, comandos, regras)
2. Adicione hooks do Plankton para reforço de qualidade em tempo de escrita
3. Use AgentShield para auditorias de segurança
4. Use o loop de verificação do ECC como porta final antes de PRs

Evitando Conflitos de Hook

Se estiver executando hooks de ambos ECC e Plankton:

• O hook Prettier do ECC e o formatador biome do Plankton podem conflitar em arquivos JS/TS
• Resolução: desabilite o hook PostToolUse do Prettier do ECC ao usar Plankton (o biome do Plankton é mais abrangente)
• Ambos podem coexistir em diferentes tipos de arquivo (ECC cuida do que o Plankton não cobre)

Referência de Configuração

O arquivo .claude/hooks/config.json do Plankton controla todo o comportamento:

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

Configurações-chave:

• Desabilite linguagens que você não usa para acelerar hooks
• volume_threshold — violações > este número sobem automaticamente para um nível de modelo superior
• subprocess_delegation: false — pule a Fase 3 completamente (apenas reporte violações)

Substituições por Ambiente

Variável	Propósito
HOOK_SKIP_SUBPROCESS=1	Pule Fase 3, reporte violações diretamente
HOOK_SUBPROCESS_TIMEOUT=N	Substitua o timeout do nível
HOOK_DEBUG_MODEL=1	Registre decisões de seleção de modelo
HOOK_SKIP_PM=1	Ignore a aplicação do gerenciador de pacotes

Referências

• Plankton (crédito: @alxfazio)
• Plankton REFERENCE.md — Documentação completa da arquitetura (crédito: @alxfazio)
• Plankton SETUP.md — Guia de instalação detalhado (crédito: @alxfazio)

Adições ECC v1.8

Perfil de Hook Copiável

Configure comportamento de qualidade estrito:

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

Tabela de Portão de Linguagem

• TypeScript/JavaScript: Biome preferido, Prettier como fallback
• Python: ruff format/check
• Go: gofmt

Guarda de Violação de Configuração

Durante o reforço de qualidade, sinalize alterações em arquivos de configuração na mesma iteração:

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

Se a configuração for alterada para suprimir violações, exija revisão explícita antes do merge.

Padrão de Integração CI

Use os mesmos comandos no CI que nos hooks locais:

1. execute verificações de formatador
2. execute verificações de lint/tipo
3. falhe rapidamente no modo estrito
4. publique resumo de remediação

Métricas de Saúde

Acompanhe:

• edições sinalizadas por portões
• tempo médio de remediação
• violações repetidas por categoria
• bloqueios de merge devido a falhas de portão