Ephasme/scan-code-quality

Escanear qualidade do código

Atue como o orquestrador de uma equipe sênior de revisão de código. Você não lê todos os arquivos pessoalmente — você define o escopo do trabalho, distribui para revisores especialistas (um por aspecto de qualidade) e, em seguida, encaminha as descobertas para um verificador mais barato que verifica e classifica cada uma delas. Você monta os sobreviventes em um único relatório baseado em evidências.

Dividir a revisão dessa forma mantém cada revisor focado em uma lente (então ele se aprofunda em vez de examinar seis preocupações ao mesmo tempo), executa as lentes em paralelo e gasta o modelo caro apenas encontrando — o trabalho mecânico de verificar uma afirmação concreta e pontuar sua prioridade está bem ao alcance de um modelo pequeno e rápido, então é executado lá.

Paralelismo é uma otimização, não um requisito. Se este agente puder despachar subagentes, dê a cada revisor e a cada verificador o seu próprio; é isso que torna o isolamento real e a execução rápida. Se não puder, trabalhe a mesma lista você mesmo — uma categoria de cada vez, escrevendo as descobertas de cada categoria em um arquivo antes de iniciar a próxima, e, em seguida, uma passada de verificação separada sobre as descobertas coletadas. Nunca pule uma categoria e nunca mescle as passadas de encontrar e verificar em uma única leitura: a verificação existe para ser uma análise independente do código citado.

Quando usar

• Revisão de código ou auditoria de qualidade
• Avaliação de dívida técnica ou preparação para refatoração
• Revisão de integração para entender a saúde da base de código
• Detecção de code smells antes de um lançamento

Opções

Leia estas a partir da invocação (por exemplo, --find-model <nível-médio> --check-model <barato> --depth minucioso src/). Se ausentes, use o padrão e declare o valor resolvido no topo do relatório.

Opção	Padrão	Significado
--find-model	nível médio: um modelo geral forte, não o maior disponível	Modelo para os revisores por aspecto (fase de encontrar).
--check-model	mais barato: o menor e mais rápido modelo disponível	Modelo para a passagem de verificação e classificação (fase de verificar).
--depth	minucioso	rápido = apenas as principais descobertas (cada revisor retorna no máximo suas 8 mais fortes), um lote de verificador; minucioso = catálogo completo, verificação por descoberta.
--focus	todas as categorias	Subconjunto separado por vírgulas das categorias, pelos nomes na lista de Categorias de Detecção ou os ids de lente (swift-concurrency, react-core, …) na tabela de Pacotes de pilha, correspondido sem distinção de maiúsculas/minúsculas — apenas esses revisores são executados. Um nome que não corresponda a nada é um erro a ser relatado, não uma varredura vazia.
--stack	detectado automaticamente	Forçar (--stack swift-ios, --stack react, separados por vírgulas) ou desabilitar (--stack none) os pacotes de pilha.
caminhos alvo	raiz do repositório	Args posicionais: diretórios/arquivos para escanear.
--exclude	vendor, gerado, saídas de build, lockfiles	Caminhos para pular.

Os valores de modelo passam diretamente para o seletor de modelo que este agente expõe — um alias ou um id de modelo completo, o que ele aceitar. Se não expuser nenhum, ignore ambas as flags e informe isso na linha de configuração do relatório; as fases ainda são executadas, apenas em um modelo. O orquestrador em si sempre executa no modelo da sessão.

Os níveis importam mais do que os nomes: encontrar problemas estruturais requer raciocínio, verificar uma afirmação concreta contra o código citado não. Enviar ambos para o mesmo modelo grande desperdiça a maior parte do custo da execução na metade mais barata do trabalho.

Arquitetura

orquestrador (esta sessão)
  │  1. escopo + construir um resumo de contexto compartilhado
  ├──► fase de encontrar  (paralela, modelo = --find-model) ───────────────┐
  │      revisor: coerência arquitetural                                  │
  │      revisor: adesão a princípios de design                           │  um subagente
  │      revisor: código morto e artefatos não utilizados                 │  por categoria
  │      revisor: complexidade apropriada                                 │  no escopo
  │      revisor: clareza do código                                       │
  │      revisor: gerenciamento de estado                                 │
  │      revisor: um por lente de pilha, se um pacote corresponder       │
  │  2. coletar descobertas brutas, atribuir ids estáveis              ◄───┘
  ├──► fase de verificar (paralela, modelo = --check-model) ──────────────┐
  │      verificador: reler o código citado, confirmar/refutar,          │  verificar + classificar
  │                   aplicar contra-sinais, pontuar prioridade          │  cada descoberta
  │  3. manter descobertas confirmadas, ordernar por prioridade       ◄───┘
  └──► 4. sintetizar o relatório

Fluxo de trabalho

1. Escopo. Resolver caminhos alvo; identificar linguagens, frameworks, camadas e convenções do projeto a partir de arquivos de configuração e estrutura de diretórios. Aplicar exclusões. Capturar isso uma vez como um resumo de contexto curto (linguagens, frameworks, caminhos alvo, exclusões, observações notáveis sobre camadas) — você fornecerá o mesmo resumo para todos os subagentes de encontrar, para que nenhum deles tenha que redescobri-lo.

   Detectar a pilha em relação à tabela de Pacotes de pilha. Um pacote se aplica quando seus sinais de detecção são válidos para os caminhos alvo, não apenas em algum lugar do repositório. Registrar no resumo quais pacotes corresponderam e os fatos da toolchain dos quais suas regras dependem, por alvo quando diferirem (versão da linguagem e modo, isolamento padrão, SO mínimo, framework de UI): as regras se aplicam por alvo, e um repositório frequentemente mistura um alvo de aplicativo com extensões e pacotes em configurações diferentes. Nenhum pacote correspondido → apenas categorias genéricas; informe isso na linha de configuração.

2. Fase de encontrar — despachar um subagente revisor por categoria no escopo, todos em um único lote paralelo, cada um com model = --find-model. As categorias são as seis genéricas mais cada lente de cada pacote correspondido. Dar a cada subagente: o resumo de contexto, o nome de sua única categoria, o arquivo de referência e a seção a serem lidos (categorias genéricas: sua seção de references/generic.md; uma lente de pilha: todo o seu arquivo de pacote), e o contrato de saída de encontrar abaixo. Usar o modelo de prompt na próxima seção. Um revisor que vai amplo e superficial derrota o propósito — cada um possui exatamente uma lente.

   Revisores genéricos em uma pilha correspondida também aplicam o idioma do pacote: um "god object" no SwiftUI é um view model de tela inteira, não uma classe de 20 métodos. Dizer a eles qual pacote correspondeu; eles podem lê-lo, mas relatar apenas sua própria categoria.

   Sobreposição. Um defeito, uma descoberta: as lentes frequentemente veem o mesmo código — estado mutável compartilhado é tanto "Swift concorrência" quanto "gerenciamento de estado"; dados do servidor copiados em useState por um Effect são tanto react-core quanto react-architecture. Uma lente de pilha vence uma categoria genérica quando uma de suas regras nomeia o construto; entre duas lentes de pilha, vence aquela cuja regra é sobre a causa raiz (o cache, não o Effect que copia dele). Na coleta, mesclar descobertas cuja localização se sobrepõe e cujo padrão nomeia o mesmo mecanismo, manter o proprietário e listar os outros abaixo dele.

3. Coletar. Reunir a saída JSON de cada revisor, concatenar e atribuir a cada descoberta um id estável (por exemplo, arch-1, complexity-3). Descartar duplicatas exatas (mesma localização + padrão) e mesclar sobreposições de acordo com a regra acima.

4. Fase de verificar — verificar e classificar cada descoberta com model = --check-model. Despachar subagentes verificadores em paralelo usando o modelo de prompt de verificar abaixo. Cada verificador relê independentemente o código citado e decide se a descoberta é real, aplica os contra-sinais, ajusta a gravidade e atribui uma pontuação de prioridade de 0 a 100. Na profundidade minuciosa, dar a cada descoberta (ou a um pequeno lote) seu próprio verificador para uma verificação independente genuína; na profundidade rápida, agrupar todas as descobertas de uma categoria em um verificador. Descartar descobertas refutadas (mostrá-las em "considerado, mas não sinalizado"); manter confirmadas e sinalizar incertas.

5. Relatório. Ordenar as descobertas sobreviventes por priority_score descendente (desempates por gravidade). Emitir a estrutura do relatório abaixo. Começar com a configuração resolvida (alvo, profundidade, foco, find-model, check-model) para que a execução seja reproduzível.

Subagente de encontrar — modelo de prompt

Preencher os placeholders e despachar com model = --find-model, um por categoria:

Você é um revisor de código sênior auditando código para UM aspecto de qualidade: {NOME_DA_CATEGORIA}. Ignore todos os outros aspectos — outros revisores os cobrem.

Resumo de contexto: {linguagens, frameworks, caminhos alvo, exclusões, observações sobre camadas}

Leia a {seção {NOME_DA_CATEGORIA} de {caminho absoluto para references/generic.md} | totalidade de {caminho absoluto para o arquivo do pacote}} para os sinais de detecção, limites e receitas de refatoração para este aspecto. Use-os — não confie na memória. O Desde de cada regra do pacote nomeia a versão necessária. Se a versão do projeto for mais antiga, a correção da regra pode não existir lá: relatar o defeito quando o problema em si existir naquela versão, dar uma refatoração que funcione naquela versão e mencionar a correção mais recente apenas como o caminho de atualização. Descartar uma regra completamente quando seu assunto não existir naquela versão (uma API, um roteador, um compilador). Escanear apenas os caminhos alvo.

Para cada problema com evidência concreta (caminho do arquivo, símbolo, uma métrica/contagem ou um construto específico), emitir uma descoberta. Se você não puder apontar para evidências, não a emita — sinalizações não fundamentadas desperdiçam o tempo do revisor. Respeitar as convenções existentes do projeto; as direções de refatoração devem ser não disruptivas e preservar o comportamento.

Retornar apenas um array JSON (sem prosa), cada elemento com estes campos: { "category", "pattern", "location", "evidence", "impact", "refactor_direction", "severity" } onde severity ∈ high|medium|low de acordo com a rubrica que lhe dei. Retornar [] se você não encontrar nada.

Subagente de verificar — modelo de prompt

Preencher com as descobertas coletadas e despachar com model = --check-model:

Você é um verificador adversário e triador. Para cada descoberta candidata abaixo, releia independentemente o código citado e julgue se é um defeito real — não confie nas próprias afirmações da descoberta.

Descobertas: {array JSON de descobertas, cada uma incluindo seu id}

Para cada descoberta, decidir:

• verdict: confirmed (a evidência é válida e é um defeito genuíno), refuted (a evidência não é válida, o código citado difere ou um contra-sinal se aplica) ou uncertain (não é possível determinar a partir da localização citada). Padrão para refuted quando a evidência é fraca e você não pode substanciá-la.
• confidence: 0,0–1,0.
• adjusted_severity: high|medium|low (você pode anular a gravidade do revisor).
• priority_score: 0–100 — classificar por gravidade × raio de explosão × alavancagem de correção: quão ruim é se deixado, quantos arquivos/consumidores/caminhos afeta e quanta melhoria uma correção não disruptiva compra por unidade de esforço. Um problema de alta gravidade confinado a um arquivo morto não supera nada; um problema médio que se espalha pelo caminho crítico supera um problema isolado de alta gravidade.
• rationale: uma ou duas frases, citando o que você viu no código.

Contra-sinais que devem empurrar uma descoberta para refuted: reutilização comprovada em 3+ consumidores independentes; um mandato regulatório/de conformidade; um ponto de extensão ativamente usado; duplicação AHA intencional (mais barata que a abstração errada); para uma descoberta de lente de pilha, os próprios Contra-sinais da regra, um assunto que não existe na versão do projeto ou uma refatoração que precisa de uma versão mais nova do que a que o projeto executa, sem alternativa fornecida.

Retornar apenas um array JSON, cada elemento: { "id", "verdict", "confidence", "adjusted_severity", "priority_score", "rationale" }.

Categorias de Detecção

Listadas na ordem de prioridade padrão. Cada uma descreve como o código saudável se parece; desvios são descobertas. Passar exatamente uma para cada subagente de encontrar.

1. Coerência arquitetural — cada módulo tem um limite claro e um único propósito; as dependências fluem em uma direção; as mudanças em um recurso permanecem dentro de seu limite.
2. Adesão a princípios de design — o código segue SOLID, DRY, YAGNI, KISS; abstrações existem apenas para necessidades comprovadas e atuais; cada classe tem uma razão para mudar.
3. Código morto e artefatos não utilizados — todo símbolo exportado, arquivo, branch e parâmetro é acessível e exercitado pelos caminhos de código atuais.
4. Complexidade apropriada — funções têm baixa ramificação (CC ≤ 15), aninhamento raso (≤ 3 níveis) e poucos parâmetros (≤ 4); camadas de indireção são justificadas por reutilização.
5. Clareza do código — nomes revelam intenção; constantes substituem valores mágicos; o fluxo de controle é lido linearmente; a terminologia é consistente em toda a base de código.
6. Gerenciamento de estado — dependências são passadas explicitamente; o escopo mutável é o mais estreito possível; efeitos colaterais são visíveis nas assinaturas.

Cada subagente de encontrar lê apenas sua seção correspondente de references/generic.md para os sinais, limites e receitas de refatoração específicos — esse arquivo carrega os detalhes por categoria para que os revisores não trabalhem de memória.

Pacotes de pilha

Um pacote adiciona lentes para uma pilha: regras que são específicas a ela ou assumem uma forma específica lá, cada uma com sinais de detecção, a versão a partir da qual se aplica, gravidade, refatoração, contra-sinais e fontes. As lentes do pacote são executadas após as categorias genéricas em ordem de prioridade.

Pacote	Detectar quando	Lentes (um revisor cada)
swift-ios	Fontes *.swift mais um *.xcodeproj, project.yml (XcodeGen), Tuist/ ou um Package.swift com uma plataforma .iOS	swift-concurrency — segurança de concorrência e corrida de dados, references/swift-concurrency.md; swift-language — design de linguagem e API, references/swift-language.md; swiftui — estado e renderização, apenas quando import SwiftUI aparece, references/swiftui.md; ios-platform — correção da plataforma e risco da App Store, references/ios-platform.md
react	react em um package.json dependencies que rege os caminhos alvo, mais fontes *.jsx/*.tsx	react-core — componentes, hooks e renderização, references/react-core.md; react-architecture — dados, estado e frameworks, references/react-architecture.md; react-performance — desempenho e memoização, references/react-performance.md