Personalização
Preferências pessoais opcionais: ${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/CodeQuality/PREFERENCES.md.
Se esse arquivo existir, leia e aplique; caso contrário, prossiga com as configurações padrão da skill. Apenas preferências pessoais: qualquer fato sobre um repositório ou produto pertence ao repositório (seu .claude/workflow-profile.sh ou configurações de ferramentas), nunca aqui.
O que QualidadeDeCodigo faz?
Um loop, duas lentes. O loop é sempre detectar → escolher um item → corrigir com testes → verificar → repetir. A lente de ferramentas corrige o que os scanners sinalizam, em ordem de prioridade, com os testes existentes como proteção. A lente de princípios corrige o que torna o código difícil de mudar (classes god, duplicação, núcleos não testáveis), um princípio SOLID / Clean Code de cada vez, e nunca aplica uma mudança de design sem mostrá-la primeiro. Ambas as lentes leem o mesmo manifesto de ferramentas, escrevem no mesmo diretório de relatórios e terminam com o mesmo Relatório de Melhoria de Qualidade.
Duas lentes
| Lente de ferramentas | Lente de princípios | |
|---|---|---|
| Direcionador | saída do scanner (summary.md) | smells de design mapeados para Principles.md (smell-inventory.md, roadmap.md) |
| Unidade de trabalho | um achado: uma regra em um arquivo:linha | um princípio em um hotspot delimitado: uma Extração, uma divisão de classe, uma inversão de dependência |
| Ordem | P0 segurança → P1 correção → P2 manutenibilidade | escada de alavancagem (abaixo), ajustada por repositório |
| Autonomia | corrige, depois mostra o diff | propor → confirmar → aplicar; nada é editado antes da aprovação |
| Rede de segurança | testes existentes permanecem verdes | testes de caracterização escritos primeiro quando o alvo não é testado |
| Métrica | menos achados, nova execução da ferramenta limpa | % de duplicação, complexidade ciclomática, tamanho de função, fan-in/out, "agora testável unitariamente" |
| Escolha quando | dívida de lint/tipo/segurança, CI vermelho, "faça os scanners felizes" | código que resiste a mudanças; o nível estrutural de um sprint de remediação |
O loop
VARRER → SELECIONAR → REDE DE SEGURANÇA → [PROPOR → CONFIRMAR] → CORRIGIR → VERIFICAR → RELATAR → REPETIR
└─ obrigatório no modo princípio, ignorado no modo ferramenta ─┘
Roteamento de workflow
| Gatilho | Workflow | Produz |
|---|---|---|
| "instalar ferramentas de qualidade", "configurar qualidade de código" | Workflows/Install.md | ferramentas do manifesto instaladas e verificadas |
| "varrer", "baseline", "analisar qualidade de código", "relatório de smells", "o que devemos corrigir primeiro", "roadmap de refatoração" | Workflows/Scan.md | summary.md (A), smell-inventory.md (B), roadmap.md (C) |
| "melhorar qualidade de código", "corrigir lint", "loop de qualidade", "corrigir [achado]" | Workflows/Loop.md no modo ferramenta | correções, session-log.md, relatório |
| "refatorar", "aplicar SOLID", "limpar isso", "iniciar o loop" | Workflows/Loop.md no modo princípio | correções, session-log.md, relatório |
| "limpar este repositório" sem qualificador | Varredura A + B + C, depois Loop no modo princípio | tudo acima |
| "sprint de remediação", "ciclo de remediação" | IssueFlow Remediação é dono do branch, PR e merge; Varredura escopa o ciclo, Loop executa | um PR por ciclo |
O Loop escolhe seu modo por conta própria quando nenhum é fornecido: ferramenta quando não existe roadmap.md para o repositório, princípio quando existe. O usuário pode forçar qualquer um.
O manifesto
Tools/tools.tsv é a única lista de ferramentas nesta skill. Separado por tabulações, uma linha por ferramenta e idioma: linguagem categoria prioridade instalação execução notas, com linguagem em js | python | yaml, categoria em lint | format | types | security | deadcode | duplication | complexity | deps | coverage, prioridade em P0 | P1 | P2. Ambos os scripts leem; os workflows nunca listam ferramentas inline. Para adicionar ou remover uma ferramenta, edite uma linha.
| Script | Lê do manifesto | Faz |
|---|---|---|
Tools/install-quality-tools.sh [--dry-run] [lingua ...] | células instalação das linguagens escolhidas | detecta linguagens (package.json → js; pyproject.toml, requirements.txt ou *.py → python; *.yaml/*.yml → yaml); instala ferramentas js como devDependencies com o gerenciador de pacotes do repositório (lockfile → npm/pnpm/bun), ferramentas python e yaml com uv pip install ou pip; prefixos npm:/pip: substituem o canal, - não instala nada |
Tools/run-quality-baseline.sh [--dry-run] [lingua ...] | células execução | executa cada ferramenta em reports/codequality/<YYYY-MM-DD>-<HHMMSS>/, substituindo $OUT (diretório do relatório), $SRC (QUALITY_SRC_DIRS, padrão src se existir senão .), $PM e $NPX; uma ferramenta que não está instalada é MISSING, uma que trava é FAILED, nenhuma para a execução; escreve summary.md com status por ferramenta, contagens de problemas analisados e totais P0/P1/P2; imprime o caminho do relatório |
Linhas cujo execução é - (ferramentas de cobertura) são instaladas mas não executadas pela baseline: a cobertura é medida no Loop, escopo do alvo. Toda ferramenta é gratuita e executa localmente; npm audit, pip-audit e checkov alcançam a rede apenas para seus bancos de vulnerabilidades.
Escada de alavancagem (ordem padrão da lente de princípios)
- Nomes — código que você não consegue ler, você não consegue alterar com segurança. Barato, desbloqueia tudo.
- DRY / duplicação — remove a maior quantidade de código com o menor risco; expõe abstrações ocultas.
- Funções pequenas — Método Longo → Extrair; um nível de abstração por função.
- SRP — dividir classes e módulos que mudam por mais de um motivo.
- OCP / DIP — inverter dependências, adicionar costuras; alto impacto, maior risco, rede de segurança primeiro.
- ISP / LSP — interfaces gordas e substituibilidade quebrada; precisam das costuras do passo 5.
A parte C da Varredura ajusta esta ordem ao inventário real (alavancagem = impacto ÷ risco; veja Principles.md Parte 3).
Inegociáveis
- Um item por iteração. Um achado, ou um princípio em um alvo delimitado. Diffs pequenos e revisáveis.
- Preservação de comportamento. Estrutura muda, comportamento não. Se o comportamento precisar mudar, pare e sinalize: isso é uma funcionalidade, não uma correção.
- Verde para verde. Testes passam antes e depois. Vermelho após uma mudança significa reverter, nunca corrigir adiante.
- Testes de caracterização primeiro quando as linhas a serem tocadas não são testadas. Sem rede, sem refatoração.
- Propor antes de aplicar qualquer movimento de design (modo princípio). Modo ferramenta pode corrigir diretamente, depois mostra o diff.
- P0 → P1 → P2 para achados de ferramentas, entre linguagens, nunca por linguagem.
- Nunca enfraquecer um teste ou uma regra de lint para ficar verde. Testes obsoletos mudam para o novo comportamento correto; regras são satisfeitas no código.
- Escoteiro, delimitado. Deixe arquivos tocados mais limpos, mas não expanda o escopo além do item atual.
- Evidência, não opinião. Nomeie a regra ou princípio, e uma métrica onde existir.
Artefatos de saída
Todos em reports/codequality/ (ignorados pelo git):
| Arquivo | Escrito por |
|---|---|
<YYYY-MM-DD>-<HHMMSS>/summary.md + saída bruta da ferramenta | run-quality-baseline.sh (Varredura A) |
<YYYY-MM-DD>/smell-inventory.md | Varredura B |
<YYYY-MM-DD>/roadmap.md | Varredura C |
<YYYY-MM-DD>/session-log.md | Loop, uma entrada por iteração |
<YYYY-MM-DD>/quality-report.md | Loop, ao final da sessão (abaixo) |
Relatório de Melhoria de Qualidade (obrigatório)
Toda sessão do Loop termina com este relatório, em qualquer modo. Ele é a entrega junto com a mudança de código e o corpo do PR ou comentário do tracker quando o trabalho é enviado pelo IssueFlow.
| Seção | Conteúdo |
|---|---|
| Tabela resumo | linhas adicionadas / removidas / líquido; problemas antes → depois por prioridade; hotspots de código morto removidos; testes antes → depois (contagem, todos verdes) |
| Código removido | arquivo, o quê, linhas, risco |
| Código adicionado ou modificado | arquivo, o quê, linhas, propósito |
| Bugs corrigidos | severidade, descrição, causa raiz (apenas se algum surgir) |
| Delta de complexidade | complexidade ciclomática máxima e média antes → depois, com uma barra ASCII por hotspot |
| Adiados | itens vistos mas fora de escopo, e por quê |