tech-debt

Analisa uma base de código em busca de dívida técnica (código morto, duplicação, cheiros de arquitetura, trabalho adiado, anti-padrões de framework, testes de baixo valor), classifica os achados por gravidade e os registra como issues no GitHub após confirmação do usuário. Use quando o usuário pedir uma auditoria de dívida técnica, uma varredura de qualidade de código, uma lista de candidatos a refatoração ou quiser transformar dívida em issues rastreáveis. Suporta escopo de caminho, varredura completa, categorias selecionadas e simulação.

O que é tech-debt?

Esta skill permite que agentes de IA (como Claude Code, Cursor, Codex) analisem uma base de código em busca de dívida técnica e transformem os achados em issues acionáveis no GitHub. Ela percorre categorias como código morto, duplicação, cheiros de arquitetura, trabalho adiado, anti-padrões de framework e qualidade de testes, classificando cada achado por gravidade (P0 a P4). A skill é conservadora e somente leitura: nunca modifica o código durante a análise. Ela oferece modos flexíveis, como escopo de caminho, varredura completa (`--full`), simulação (`--dry-run`), categorias filtradas (`--categories`), e opções para ignorar limites ou confirmações (`--all`, `--yes`, `--force`). Antes de criar issues, a skill exibe uma lista completa para o usuário revisar e aprovar, garantindo que nenhuma issue seja criada sem permissão explícita. O fluxo inclui detecção automática da pilha tecnológica (linguagem, framework, runner de testes) e verificação de duplicatas com issues existentes, resultando em um relatório final detalhado e organizado por categoria. A skill é particularmente útil para desenvolvedores que desejam realizar auditorias regulares de qualidade de código, priorizar refatorações ou transformar dívida técnica em tarefas rastreáveis dentro do fluxo de trabalho do GitHub.

Funciona com✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/JAdshead/toolkit/tree/HEAD/skills/tech-debt

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

  1. Se caminhos foram fornecidos, use-os.
  2. Se --full foi fornecido, varra o repositório com as exclusões acima.
  3. 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:

IndicadorPilha
Gemfile com rails, ou config/application.rbRuby on Rails
manage.py ou django em requirements / pyproject.tomlDjango
pyproject.toml / requirements.txt com fastapi ou flaskPython web
package.json com next, react, vue, svelte, express, nestjsFramework JS/TS
go.modGo
Cargo.tomlRust
pom.xml / build.gradle*JVM (Spring se presente)
composer.json com laravel/frameworkLaravel
*.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):

  1. Anuncie Analisando [Categoria]... (X de N).
  2. Aplique a lista de verificação para essa categoria em references/categories.md, adaptada à pilha detectada.
  3. Colete os achados no formato JSON abaixo.
  4. 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ãoGravidadeCategoria
Testes que escondem problemas de segurançaP0Qualidade de Teste
Verificação de autorização ausente no acesso a recursosP1Violações de Padrão
God classes (>500 linhas ou >20 métodos públicos)P1Arquitetura
Dependências circularesP1Arquitetura
Código inalcançávelP1Código Morto
Testes apenas com mocks (o teste simula o que está testando)P1Qualidade de Teste
Stub do sujeito e depois afirmação sobre eleP1Qualidade de Teste
Testes tautológicosP1Qualidade de Teste
Corpos de teste vaziosP1Qualidade de Teste
Mock excessivo (>50% do teste é configuração)P1Qualidade de Teste
Stub de toda instância de uma classeP1Qualidade de Teste
Estado mutável compartilhado entre testesP1Qualidade de Teste
Funções longas (>50 linhas)P2Arquitetura
Alto acoplamento (>10 importações do projeto)P2Arquitetura
Duplicatas exatas ou próximasP2Duplicação
Avisos de depreciaçãoP2Trabalho Adiado
Marcadores temporários ou de workaroundP2Trabalho Adiado
Anti-padrões de frameworkP2Violações de Padrão
Testes acoplados à implementaçãoP2Qualidade de Teste
Testes que apenas afirmam "não levanta exceção"P2Qualidade de Teste
Funções não referenciadas, branches mortos, arquivos órfãosP2Código Morto
Aninhamento profundo (>4 níveis)P3Arquitetura
Importações não utilizadasP3Código Morto
Comentários TODO / FIXMEP3Trabalho Adiado
Código comentadoP3Trabalho Adiado
Violações de convençãoP3Violações de Padrão
Afirmações de teste frágeisP3Qualidade de Teste
TODOs que referenciam um ticketP4Trabalho 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

  1. 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.
  2. 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.
  3. 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

  1. Somente leitura. Nenhuma alteração de código durante a análise.
  2. Conservador. Quando estiver em dúvida, pule em vez de relatar um falso positivo. Um relatório ruidoso é ignorado.
  3. 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.
  4. Evidência primeiro. Cada achado cita um arquivo, uma linha e o código que o comprova.
  5. Saída estruturada. As análises de categoria retornam JSON para que a mesclagem e a deduplicação sejam confiáveis.
  6. Usuário confirma antes de registrar. A lista é sempre mostrada primeiro.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas