Descoberta de Dívida Técnica
Analise a base de código em busca de dívida técnica e transforme os achados em issues acionáveis no GitHub. A análise é somente leitura: nunca altere o código ao executar esta skill.
Opções
Analise estas a partir da solicitação do usuário ou dos argumentos do comando:
- Caminhos de escopo: diretórios ou arquivos para analisar (por exemplo
src/services lib/). - --full: varre todo o repositório, excluindo diretórios de dependência, build e VCS (
node_modules,vendor,.git,dist,build,target,tmp,log, virtualenvs, código gerado). - --dry-run: relata os achados sem criar issues.
- --all: remove o limite de 20 issues.
- --force: cria issues mesmo quando uma issue aberta semelhante já existe.
- --yes: pula o prompt de confirmação (apenas quando o usuário o passa explicitamente).
- --categories=X,Y: executa apenas estas categorias:
dead-code,duplication,architecture,deferred-work,patterns,tests.
Modelo de execução
Cada categoria é analisada de forma independente. Se seu agente puder gerar subagentes paralelos, atribua a cada categoria seu próprio subagente com o escopo, a pilha detectada e a lista de verificação da categoria de references/categories.md, e faça cada um retornar o formato JSON abaixo. Caso contrário, execute as categorias sequencialmente, uma de cada vez, para permanecer dentro dos limites de contexto.
Uma execução sequencial completa de seis categorias leva aproximadamente de 15 a 30 minutos em uma base de código de médio porte. Para resultados mais rápidos, sugira --categories ou um escopo mais restrito.
Etapa 1: Determinar o escopo
- Se caminhos foram fornecidos, use-os.
- Se
--fullfoi fornecido, varra o repositório com as exclusões acima. - Caso contrário, detecte automaticamente os diretórios principais de origem e teste que existem (comuns:
src/,app/,lib/,pkg/,internal/,cmd/,test/,tests/,spec/). Mostre:Escopo detectado automaticamente: [diretórios]. Cerca de X arquivos. Continuar? (use --full para uma varredura completa)
Conte os arquivos de origem no escopo com as extensões que o repositório realmente usa (por exemplo git ls-files -- <escopo> | grep -E '\.(rb|py|ts|tsx|js|go|java|kt|rs|php|cs)$' | wc -l).
- Mais de 1.000 arquivos: avise que a execução será longa e sugira
--categories. - Mais de 5.000 arquivos: recomende fortemente executar uma categoria de cada vez e dê um tempo aproximado por categoria.
Etapa 2: Verificações de pré-análise
A menos que --dry-run, verifique a CLI do GitHub:
gh auth status
Se falhar, defina gh_available=false e diga: "CLI gh não encontrada ou não autenticada. Os achados serão relatados sem criar issues. Execute gh auth login para habilitar a criação de issues."
Se disponível, busque o que for necessário mais tarde:
gh issue list --state open --limit 200 --json number,title,body,labels
gh label list --limit 200 --json name,description
Mantenha a lista de issues para detecção de duplicatas e a lista de labels para rotulagem.
Etapa 3: Detectar a pilha
Detecte a linguagem, framework e runner de testes do repositório em vez de assumir um. Indicadores típicos:
| Indicador | Pilha |
|---|---|
Gemfile com rails, ou config/application.rb | Ruby on Rails |
manage.py ou django em requirements / pyproject.toml | Django |
pyproject.toml / requirements.txt com fastapi ou flask | Python web |
package.json com next, react, vue, svelte, express, nestjs | Framework JS/TS |
go.mod | Go |
Cargo.toml | Rust |
pom.xml / build.gradle* | JVM (Spring se presente) |
composer.json com laravel/framework | Laravel |
*.csproj | .NET |
Também detecte o framework de testes (RSpec, Minitest, pytest, unittest, Jest, Vitest, Mocha, Go testing, JUnit, PHPUnit e assim por diante) e os diretórios de teste.
Leia as próprias convenções do projeto antes de julgar qualquer coisa: README, CONTRIBUTING, arquivos de instrução do agente (AGENTS.md, CLAUDE.md, GEMINI.md), configurações de linter e quaisquer documentos de arquitetura. Um padrão que o projeto escolheu deliberadamente não é dívida.
Relate: Pilha detectada: [linguagem / framework / runner de testes]. Regras de análise ajustadas de acordo.
Etapa 4: Executar as análises de categoria
Para cada categoria habilitada (todas as seis por padrão):
- Anuncie
Analisando [Categoria]... (X de N). - Aplique a lista de verificação para essa categoria em
references/categories.md, adaptada à pilha detectada. - Colete os achados no formato JSON abaixo.
- Relate
[Categoria] completa: X achados.
Se uma categoria demorar muito mais que as outras (cerca de 5 minutos de análise ativa), pare-a e marque-a como Incompleta (truncada) no relatório, em vez de travar a execução.
Formato do achado
Cada categoria retorna:
{
"category": "Dead Code",
"findings": [
{
"type": "Importação não utilizada",
"severity": "P3",
"location": "src/utils/format.ts:5",
"line_number": 5,
"description": "A importação 'date-fns' nunca é usada neste arquivo",
"evidence": "import { format } from 'date-fns'",
"remediation": "Remova a importação não utilizada",
"complexity": "simple"
}
]
}
Para duplicação, coloque cada localização em location, separada por , . Para achados de arquitetura, coloque as métricas em description (por exemplo "567 linhas, 23 métodos públicos").
Referência de gravidade
| Padrão | Gravidade | Categoria |
|---|---|---|
| Testes que escondem problemas de segurança | P0 | Qualidade de Teste |
| Verificação de autorização ausente no acesso a recursos | P1 | Violações de Padrão |
| God classes (>500 linhas ou >20 métodos públicos) | P1 | Arquitetura |
| Dependências circulares | P1 | Arquitetura |
| Código inalcançável | P1 | Código Morto |
| Testes apenas com mocks (o teste simula o que está testando) | P1 | Qualidade de Teste |
| Stub do sujeito e depois afirmação sobre ele | P1 | Qualidade de Teste |
| Testes tautológicos | P1 | Qualidade de Teste |
| Corpos de teste vazios | P1 | Qualidade de Teste |
| Mock excessivo (>50% do teste é configuração) | P1 | Qualidade de Teste |
| Stub de toda instância de uma classe | P1 | Qualidade de Teste |
| Estado mutável compartilhado entre testes | P1 | Qualidade de Teste |
| Funções longas (>50 linhas) | P2 | Arquitetura |
| Alto acoplamento (>10 importações do projeto) | P2 | Arquitetura |
| Duplicatas exatas ou próximas | P2 | Duplicação |
| Avisos de depreciação | P2 | Trabalho Adiado |
| Marcadores temporários ou de workaround | P2 | Trabalho Adiado |
| Anti-padrões de framework | P2 | Violações de Padrão |
| Testes acoplados à implementação | P2 | Qualidade de Teste |
| Testes que apenas afirmam "não levanta exceção" | P2 | Qualidade de Teste |
| Funções não referenciadas, branches mortos, arquivos órfãos | P2 | Código Morto |
| Aninhamento profundo (>4 níveis) | P3 | Arquitetura |
| Importações não utilizadas | P3 | Código Morto |
| Comentários TODO / FIXME | P3 | Trabalho Adiado |
| Código comentado | P3 | Trabalho Adiado |
| Violações de convenção | P3 | Violações de Padrão |
| Afirmações de teste frágeis | P3 | Qualidade de Teste |
| TODOs que referenciam um ticket | P4 | Trabalho Adiado |
Guia de complexidade
- simples: abaixo de 10 linhas, um arquivo, correção óbvia (remover uma importação não utilizada).
- moderado: 10 a 50 linhas, 2 ou 3 arquivos, refatoração direta (extrair uma função).
- complexo: acima de 50 linhas, precisa de uma decisão arquitetural ou abrange a base de código (dividir uma god class). Observe na remediação que provavelmente precisa de um design ou proposta antes da implementação.
Etapa 5: Coletar e deduplicar
- Agrupe achados por categoria + arquivo + linha (dentro de 10 linhas). Em cada grupo, mantenha o achado com a evidência mais detalhada, na maior gravidade do grupo.
- Entre categorias: se Código Morto e Arquitetura sinalizarem a mesma classe, mantenha o achado de Arquitetura. Se várias categorias sinalizarem a mesma linha, mescle-as e mantenha a maior gravidade.
- Ordene P0 primeiro, depois P1 a P4.
Etapa 6: Verificar issues existentes
Pule esta etapa apenas se --force estiver definido. Para cada achado, procure uma issue aberta que:
- mencione o mesmo caminho de arquivo em seu título ou corpo, E
- cubra o mesmo tipo de problema, ou uma linha dentro de 20 linhas deste.
Prefira issues intituladas [TechDebt] ou que carreguem uma label de dívida técnica, mas corresponda a qualquer issue aberta que claramente rastreie o mesmo problema. Em caso de correspondência, marque o achado como já rastreado como #N e não o registre. Diferentes tipos de problema no mesmo arquivo são achados separados.
Etapa 7: Confirmar e depois criar issues
Pule a criação se --dry-run ou gh_available=false; vá direto para o relatório.
Limite: no máximo 20 issues a menos que --all. Preencha as vagas em ordem: todos P0 e P1, depois P2 (prefira distribuir entre arquivos em vez de muitas issues em um arquivo), depois P3, depois P4. Com --all e mais de 50 issues, avise que demorará um pouco.
Labels: use apenas labels que já existam em gh label list. Escolha a correspondência mais próxima para dívida técnica (por exemplo tech-debt, technical-debt, debt, refactor, chore) e, se o repositório as tiver, uma label de prioridade correspondente à gravidade e uma label de tipo (por exemplo testing). Nunca crie labels sem perguntar. Se nenhuma label adequada existir, diga isso e registre sem uma ou pergunte ao usuário se deseja criar tech-debt.
Confirmação (obrigatória): antes de criar qualquer coisa, mostre a lista completa e aguarde a resposta do usuário. Nunca registre issues sem ela, a menos que ele tenha passado --yes.
Serão criadas X issues (labels: tech-debt, P2):
1. [P1] [TechDebt] Arquitetura: Dividir OrderService (612 linhas, 27 métodos públicos)
2. [P1] [TechDebt] Qualidade de Teste: Corrigir teste apenas com mock em payment_test.py:45
3. [P2] [TechDebt] Duplicação: Extrair validação de endereço (user.ts:40, account.ts:88)
...
Já rastreadas (puladas): 3. Acima do limite (não registradas): 12.
Prosseguir? Você também pode remover itens por número ou alterar labels.
Aplique quaisquer edições que o usuário fizer e, em seguida, crie cada issue. Cada corpo deve ser independente, legível por alguém que não viu este relatório:
gh issue create \
--title "[TechDebt] <Categoria>: <Breve descrição>" \
--label "<label-existente>" \
--body "$(cat <<'EOF'
**Categoria:** <Categoria>
**Gravidade:** P<N>
**Localização:** <arquivo:linha>
## Problema
<descrição>
## Evidência
```
<evidência>
```
## Correção sugerida
<remediação>
**Complexidade:** <simples|moderado|complexo>
## Critérios de aceitação
- <verificação observável de que a dívida foi resolvida>
- A suíte de testes completa do projeto passa
EOF
)"
Exemplos de título:
[TechDebt] Código Morto: Remover importações não utilizadas em format.ts:5-12[TechDebt] Arquitetura: Dividir OrdersController (567 linhas, 23 ações)[TechDebt] Qualidade de Teste: Corrigir teste apenas com mock em payment_service_test.go:45
Se uma chamada gh issue create falhar, registre o erro e o comando, continue com o restante e relate Criadas X issues, Y falharam no final.
Se o repositório rastreia o trabalho em um quadro de Projeto do GitHub (a seção Issue tracking de suas instruções do agente diz Mode: project, ou não há tal seção e gh repo view --json projectsV2 mostra um quadro vinculado), ofereça-se para executar a skill place-issues nas novas issues.
Etapa 8: Relatório resumido
=== Relatório de Descoberta de Dívida Técnica ===
Escopo: [caminhos analisados]
Arquivos analisados: [contagem]
Pilha: [linguagem / framework / runner de testes]
Duração: [tempo gasto]
## Resumo
- Total de achados: X | Issues criadas: Y | Já rastreados: Z | Acima do limite: W
- Por gravidade: P0: A, P1: B, P2: C, P3: D, P4: E
## Achados por Categoria
### Código Morto (X)
- [ ] #N: Remover importações não utilizadas em format.ts:5-12 (P3)
### Duplicação (X)
- [ ] #N: Extrair validação de endereço (user.ts:40, account.ts:88) (P2)
### Arquitetura (X)
- [ ] #N: Dividir OrderService (612 linhas, 27 métodos públicos) (P1)
### Trabalho Adiado (X)
- [ ] #N: Resolver TODO em billing.py:123 (P3)
### Violações de Padrão (X)
- [ ] #N: Corrigir risco de consulta N+1 em OrdersController#index (P2)
### Qualidade de Teste (X)
- [ ] #N: Corrigir teste apenas com mock em payment_test.py:45 (P1)
## Já Rastreados
- billing.py:100 TODO → #N
## Achados Adicionais (acima do limite, não registrados)
[lista]
Execute com --all para registrar os X achados restantes.
## Pulados (falso positivo ou intencional)
- tests/fixtures/** : fixtures excluídas
- TODO(#42) em conftest.py : tem um ticket vinculado (P4)
## Status da Análise
- Código Morto: Completa
- ...
- Qualidade de Teste: Incompleta (truncada)
## Erros
[quaisquer comandos gh que falharam]
Para --dry-run, substitua os números de issue por [criaria].
Princípios
- Somente leitura. Nenhuma alteração de código durante a análise.
- Conservador. Quando estiver em dúvida, pule em vez de relatar um falso positivo. Um relatório ruidoso é ignorado.
- Respeite o projeto. Convenções do framework (callbacks, decoradores, injeção de dependência, roteamento baseado em convenção) e escolhas documentadas no repositório não são dívida.
- Evidência primeiro. Cada achado cita um arquivo, uma linha e o código que o comprova.
- Saída estruturada. As análises de categoria retornam JSON para que a mesclagem e a deduplicação sejam confiáveis.
- Usuário confirma antes de registrar. A lista é sempre mostrada primeiro.