es-kimo/claude-skills

Revisão de Manutenibilidade

O critério é um só. Quantos lugares a próxima pessoa (humana ou agente) precisará abrir ao modificar este código?

Não trata de bugs de correção. Isso é responsabilidade de code-review ou pr-review.

0. Modos

Modo	Alvo	Base de Comparação	Alvo de blocking
Auto-verificação	Meu diff antes do commit	Repositório inteiro	Corrijo (não relato, corrijo imediatamente)
Revisão de Mudança	PR diff	Repositório inteiro	Apenas problemas criados por esta mudança
Inspeção	Módulo ou diretório inteiro	Repositório inteiro	Todos. Na ordem de maior impacto

Em revisão de mudança, problemas pré-existentes não são listados como blocking. São registrados separadamente como "dívida existente".

1. Ler Critérios do Projeto

1. Procura por docs/review/architecture.md. Se não existir, usa o documento estrutural apontado por CLAUDE.md / AGENTS.md.
2. Os critérios do projeto têm prioridade sobre os gerais deste skill. Em especial, extrair do documento de critérios:
   • Mapa de módulos e direção de dependência
   • Lista de abstrações a reutilizar (clientes HTTP, tipos de resultado, helpers de teste, etc.)
   • Lista de dívidas conhecidas. Padrões nesta lista não são precedentes para novo código seguir.
3. Se não houver documento de critérios, desenhar o mapa de módulos manualmente a partir da estrutura de diretórios e exports index de cada módulo, e escrever na primeira linha "Sem documento de critérios".

2. O que Analisar

Analisar do topo para baixo. Quanto mais alto na lista, maior o custo futuro e mais frequentes os erros de agentes.

2-1. Ignorou abstrações existentes?

Agentes trabalham vendo apenas um issue por vez e, sem saber dos módulos criados em issues anteriores, podem recriar a mesma coisa. É a falha mais comum e mais cara.

Para cada nova função, tipo, classe de erro, constante ou chamada externa, procurar código que faz o mesmo no repositório.

git grep -nE "class \w+Error extends"            # classes de erro
git grep -nE "https?://[a-z.]+\.(com|io|dev)"    # endereços e cabeçalhos de API externa
git grep -nE "^(export )?type \w+ = \{"          # tipos com nomes semelhantes (ex.: XxxEntry)
git grep -nF "<string ou regex característico do novo código>"

• Se existir mais de um wrapper para o mesmo sistema externo, chamadores precisam verificar erros de múltiplas classes. Procurar também os traços disso (a instanceof X || b instanceof Y).
• Se a mesma constante de lista (extensões, valores de estado) existir em dois lugares, um deles ficará desatualizado.

2-2. Direção de Dependência

• Violou regras de camada do documento de critérios? (Ex.: módulo de domínio importando UI ou API externa).
• Módulo inferior importa o superior? Ou dois módulos importam um ao outro?

2-3. Unidades

Separar por motivo de mudança, não por tamanho.

• Se um arquivo contém dois ou mais grupos de funções que não se chamam, é sinal de mais de um motivo para mudar (ex.: mapeamento de formulário + acesso a chaves aninhadas + formatação de data).
• Se múltiplos arquivos de tela repetem a mesma sequência de preparação (autenticação → carregar configuração → ramificação de erro), essa sequência deveria ser uma função com nome.

2-4. Qualidade da Abstração

• API faltando: Se dois ou mais chamadores repetem o mesmo pré-processamento ou pós-processamento, falta uma função no módulo que encapsule esse processamento. Ex.: se todo chamador faz doc.items.find((s) => s.kind === "x") e depois chama parseX(...), então readX(doc) está faltando.
• Abstração excessiva: Interfaces, factories, opções ou genéricos com apenas um ponto de uso. Pontos de extensão desnecessários hoje.
• Tipos de contorno: Se o chamador precisa tratar falhas, isso deve ser revelado pelo tipo de resultado (união discriminada). O chamador não deve ramificar comparando strings de mensagem.

2-5. Padrões

• Seguiu os padrões já usados no repositório (tipos de resultado, injeção de dependência, tratamento de erro, forma de exportar)?
• Novos padrões só são aceitáveis se os existentes não forem suficientes. Se a razão não estiver no PR ou nos comentários, apontar.

2-6. Comentários e Nomes

• O comentário está anexado ao alvo correto? Commits de ajuste que inserem uma nova função entre funções existentes podem deixar JSDoc sobre outra função.
• O nome corresponde ao que a função faz? Se o nome leva a expectativas de comportamento diferente, apontar.

3. Julgamento

blocking (não fazer merge)

• Código de mesma responsabilidade já existe e foi recriado. Exceto se o PR ou comentário explica por que o existente não pode ser usado.
• Violou regras de camada do documento de critérios.
• A nova API força repetição do mesmo processamento em dois ou mais chamadores.
• Comentário está anexado a alvo errado, enganando quem lê.

suggestion (não bloqueia o merge, registra para trabalho futuro)

• Separação de arquivos, melhoria de nomes, duplicação pré-existente.

Não relatar: preferências (funcional vs. imperativo, comprimento de linha), itens que linter e formatador pegam, introdução de novas bibliotecas fora do escopo do issue.

4. Validação

Cada apontamento deve ser verificado no código. Apontamentos errados desperdiçam tempo do agente implementador.

• "Duplicação": abrir ambos os locais e confirmar se realmente fazem a mesma coisa. Mesmo que se pareçam, se respeitam especificações diferentes, excluir.
• "N lugares": contar com grep.
• "Criado por esta mudança": verificar se a linha está em git diff <base>...HEAD.

5. Relatório

Primeira linha: escopo analisado (modo, caminho alvo, existência de documento de critérios) e contagens (blocking N, suggestion N, dívida existente N).

Cada item:

• Título: o custo como resultado concreto. ("Chamador trata GitHub 401 com 3 classes de erro" ✓ / "Melhorar tratamento de erro" ✗)
• Localização: todos os locais relevantes como arquivo:linha. Em caso de duplicação, ambos os lados.
• Custo: quantos lugares precisam ser alterados na próxima mudança. ("Para alterar o cabeçalho de versão da API, é preciso alterar 3 arquivos")
• Direção: uma ou duas frases sobre como unificar.
• Classificação: blocking / suggestion / dívida existente.

Se não houver o que apontar, escrever "Nenhum". Não inventar apontamentos para preencher.

O que não fazer

• Pedir para separar baseado apenas no número de linhas ou tamanho do arquivo.
• Apontamentos sem direção ("Seria bom abstrair mais").
• Tratar código com aparência semelhante como duplicação, sem verificar a função real.
• Transformar problema pré-existente em blocking/review blocker deste PR.