plankton-code-quality

Plankton Code Quality Skill

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

Quando Usar

• Você deseja formatação e linting automáticos em toda edição de arquivo (não apenas no momento do commit)
• Você precisa de defesa contra agentes que modificam configurações de linters para passar em vez de corrigir 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últiplas linguagens (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)

Como Funciona

Arquitetura em Três Fases

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

Fase 1: Auto-Formatação (Silenciosa)
├─ Executa formatadores (ruff format, biome, shfmt, taplo, markdownlint)
├─ Corrige 40-50% dos problemas silenciosamente
└─ Nenhuma 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: {linha, coluna, código, mensagem, linter}
└─ Ainda sem saída para o agente principal

Fase 3: Delegar + Verificar
├─ Dispara subprocesso claude -p com JSON de violações
├─ Roteia para camada de modelo com base 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 (unresolved-attribute) — timeout de 600s
├─ Executa novamente a Fase 1+2 para verificar correções
└─ Saída 0 se limpo, Saída 2 se violações permanecerem (relatadas ao agente principal)

O que o Agente Principal Vê

Cenário	O agente vê	Saída do hook
Nenhuma violação	Nada	0
Todas corrigidas pelo subprocesso	Nada	0
Violações permanecem após subprocesso	[hook] N violação(ões) restante(s)	2
Aviso (duplicatas, ferramentas antigas)	[hook:advisory] ...	0

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. 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 aconteçam
2. Hook Stop — stop_config_guardian.sh detecta alterações de configuração via git diff ao final da sessão
3. Lista de arquivos protegidos — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml e outros

Reforç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: 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 — os hooks ativam automaticamente
claude

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

Integração por Projeto

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

1. Copie o diretório .claude/hooks/ para seu projeto
2. Copie a configuração de hook .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 Específicas 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	—

Combinação 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	—	Bloqueios PreToolUse + detecção Hook Stop
Gerenciador de pacotes	Detecção + configuração	Reforço (bloqueia PMs legados)
Integração CI	—	Hooks pre-commit para git
Roteamento de modelo	Manual (/model opus)	Automático (complexidade da violação → camada)

Combinação Recomendada

1. Instale o ECC como seu plugin (agentes, skills, comandos, regras)
2. Adicione os hooks do Plankton para reforço de qualidade em tempo de escrita
3. Use o 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 do ECC e do Plankton simultaneamente:

• O hook Prettier do ECC e o formatador biome do Plankton podem entrar em conflito em arquivos JS/TS
• Resolução: desabilite o hook PostToolUse Prettier do ECC ao usar o Plankton (o biome do Plankton é mais abrangente)
• Ambos podem coexistir em diferentes tipos de arquivo (ECC lida com o 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 principais:

• Desabilite linguagens que você não usa para acelerar os hooks
• volume_threshold — violações > este número são automaticamente escaladas para uma camada de modelo superior
• subprocess_delegation: false — pule a Fase 3 completamente (apenas relate violações)

Sobrescritas de Ambiente

Variável	Finalidade
HOOK_SKIP_SUBPROCESS=1	Pular a Fase 3, relatar violações diretamente
HOOK_SUBPROCESS_TIMEOUT=N	Sobrescrever o timeout da camada
HOOK_DEBUG_MODEL=1	Registrar decisões de seleção de modelo
HOOK_SKIP_PM=1	Ignorar o reforç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

Defina comportamento de qualidade rigoroso:

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

Guardião contra Alteração de Configuração

Durante o reforço de qualidade, sinalize alterações nos 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. executar verificações do formatador
2. executar verificações de lint/type
3. falhar rapidamente no modo estrito
4. publicar resumo de remediação

Métricas de Saúde

Rastreie:

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