CommunityProgramación y desarrollogithub.com

detección-deuda-técnica

Analiza un código fuente en busca de deuda técnica (código muerto, duplicación, olores arquitectónicos, trabajo diferido, antipatrones de framework, pruebas de bajo valor), clasifica los hallazgos por gravedad y los registra como issues de GitHub después de que el usuario confirme la lista. Útil cuando el usuario solicita una auditoría de deuda técnica, una revisión de calidad del código, una lista de candidatos a refactorización o quiere convertir la deuda en issues rastreables. Admite un ámbito de ruta, un escaneo completo, categorías seleccionadas y una ejecución en seco.

¿Qué es detección-deuda-técnica?

La habilidad 'detección-deuda-técnica' es una herramienta de auditoría de código diseñada para ayudar a los desarrolladores y equipos de ingeniería a identificar, documentar y rastrear la deuda técnica en sus repositorios. Realiza un análisis exhaustivo y de solo lectura del código fuente, buscando problemas como código muerto, duplicación, olores arquitectónicos (clases dios, alta cohesión, anidamiento profundo), antipatrones de frameworks, trabajo diferido (TODOs, FIXMEs) y pruebas de baja calidad (pruebas solo simuladas, afirmaciones tautológicas). Los hallazgos se clasifican por gravedad (P0 a P4) y complejidad (simple, moderada, compleja), y se pueden convertir automáticamente en issues de GitHub con formato, etiquetas y criterios de aceptación, previa confirmación del usuario. La habilidad soporta la detección automática del stack tecnológico (Ruby on Rails, Django, Next.js, Go, Rust, etc.) y las convenciones del proyecto, y permite ejecuciones paralelas por categoría para optimizar el rendimiento. Funciona en plataformas compatibles con agentes de IA (Claude Code, Cursor, Codex) y herramientas de línea de comandos como gh.

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Descubrimiento de Deuda Técnica

Analiza el código fuente en busca de deuda técnica y convierte los hallazgos en issues accionables de GitHub. El análisis es de solo lectura: nunca modifiques el código mientras ejecutas esta habilidad.

Opciones

Analiza estas opciones a partir de la solicitud del usuario o de los argumentos del comando:

  • Rutas de ámbito: directorios o archivos a analizar (por ejemplo src/services lib/).
  • --full: escanea todo el repositorio, excluyendo directorios de dependencias, compilación y VCS (node_modules, vendor, .git, dist, build, target, tmp, log, entornos virtuales, código generado).
  • --dry-run: informa los hallazgos sin crear issues.
  • --all: elimina el límite de 20 issues.
  • --force: crea issues incluso cuando existe un issue abierto similar.
  • --yes: omite la solicitud de confirmación (solo cuando el usuario lo pasa explícitamente).
  • --categories=X,Y: ejecuta solo estas categorías: dead-code, duplication, architecture, deferred-work, patterns, tests.

Modelo de ejecución

Cada categoría se analiza de forma independiente. Si tu agente puede generar subagentes en paralelo, asigna a cada categoría su propio subagente con el ámbito, el stack detectado y la lista de verificación de la categoría desde references/categories.md, y haz que cada uno devuelva el formato JSON a continuación. De lo contrario, ejecuta las categorías secuencialmente, una a la vez, para mantenerse dentro de los límites de contexto.

Una ejecución secuencial completa de las seis categorías toma aproximadamente de 15 a 30 minutos en un código base de tamaño mediano. Para obtener resultados más rápidos, sugiere --categories o un ámbito más reducido.

Paso 1: Determinar el ámbito

  1. Si se proporcionaron rutas, úsalas.
  2. Si se proporcionó --full, escanea el repositorio con las exclusiones anteriores.
  3. De lo contrario, detecta automáticamente los directorios principales de código fuente y pruebas que existan (comunes: src/, app/, lib/, pkg/, internal/, cmd/, test/, tests/, spec/). Muestra: Ámbito detectado automáticamente: [directorios]. Aproximadamente X archivos. ¿Continuar? (usa --full para un escaneo completo)

Cuenta los archivos fuente en el ámbito con las extensiones que el repositorio realmente usa (por ejemplo git ls-files -- <scope> | grep -E '\.(rb|py|ts|tsx|js|go|java|kt|rs|php|cs)$' | wc -l).

  • Más de 1.000 archivos: advierte que la ejecución será larga y sugiere --categories.
  • Más de 5.000 archivos: recomienda enfáticamente ejecutar una categoría a la vez y proporciona un tiempo estimado por categoría.

Paso 2: Verificaciones previas al análisis

A menos que sea --dry-run, verifica la CLI de GitHub:

gh auth status

Si falla, establece gh_available=false y di: "gh CLI no encontrada o no autenticada. Los hallazgos se informarán sin crear issues. Ejecuta gh auth login para habilitar la creación de issues."

Si está disponible, obtén lo que se necesitará después:

gh issue list --state open --limit 200 --json number,title,body,labels
gh label list --limit 200 --json name,description

Mantén la lista de issues para la detección de duplicados y la lista de etiquetas para el etiquetado.

Paso 3: Detectar el stack

Detecta el lenguaje, framework y ejecutor de pruebas del repositorio en lugar de asumir uno. Indicadores típicos:

IndicadorStack
Gemfile con rails, o config/application.rbRuby on Rails
manage.py o django en requirements / pyproject.tomlDjango
pyproject.toml / requirements.txt con fastapi o flaskPython web
package.json con next, react, vue, svelte, express, nestjsJS/TS framework
go.modGo
Cargo.tomlRust
pom.xml / build.gradle*JVM (Spring si está presente)
composer.json con laravel/frameworkLaravel
*.csproj.NET

También detecta el framework de pruebas (RSpec, Minitest, pytest, unittest, Jest, Vitest, Mocha, Go testing, JUnit, PHPUnit, etc.) y los directorios de pruebas.

Lee las convenciones propias del proyecto antes de juzgar cualquier cosa: README, CONTRIBUTING, archivos de instrucciones para el agente (AGENTS.md, CLAUDE.md, GEMINI.md), configuraciones de linter y cualquier documento de arquitectura. Un patrón que el proyecto eligió deliberadamente no es deuda.

Informa: Stack detectado: [lenguaje / framework / ejecutor de pruebas]. Reglas de análisis ajustadas en consecuencia.

Paso 4: Ejecutar los análisis de categorías

Para cada categoría habilitada (las seis por defecto):

  1. Anuncia Analizando [Categoría]... (X de N).
  2. Aplica la lista de verificación para esa categoría en references/categories.md, adaptada al stack detectado.
  3. Recopila los hallazgos en el formato JSON a continuación.
  4. Informa [Categoría] completada: X hallazgos.

Si una categoría se ejecuta mucho más tiempo que las demás (aproximadamente 5 minutos de análisis activo), detenla y márcala como Incompleta (truncada) en el informe en lugar de estancar la ejecución.

Formato de hallazgo

Cada categoría devuelve:

{
  "category": "Código Muerto",
  "findings": [
    {
      "type": "Importación no utilizada",
      "severity": "P3",
      "location": "src/utils/format.ts:5",
      "line_number": 5,
      "description": "La importación 'date-fns' nunca se usa en este archivo",
      "evidence": "import { format } from 'date-fns'",
      "remediation": "Eliminar la importación no utilizada",
      "complexity": "simple"
    }
  ]
}

Para duplicación, coloca cada ubicación en location, separada por , . Para hallazgos de arquitectura, coloca las métricas en description (por ejemplo "567 líneas, 23 métodos públicos").

Referencia de gravedad

PatrónGravedadCategoría
Pruebas que ocultan problemas de seguridadP0Calidad de Pruebas
Falta de verificación de autorización en el acceso a recursosP1Violaciones de Patrones
Clases dios (>500 líneas o >20 métodos públicos)P1Arquitectura
Dependencias circularesP1Arquitectura
Código inalcanzableP1Código Muerto
Pruebas solo simuladas (la prueba simula lo que está probando)P1Calidad de Pruebas
Simular el sujeto y luego afirmar sobre élP1Calidad de Pruebas
Pruebas tautológicasP1Calidad de Pruebas
Cuerpos de prueba vacíosP1Calidad de Pruebas
Simulación excesiva (>50% de la prueba es configuración)P1Calidad de Pruebas
Simular cada instancia de una claseP1Calidad de Pruebas
Estado mutable compartido entre pruebasP1Calidad de Pruebas
Funciones largas (>50 líneas)P2Arquitectura
Alto acoplamiento (>10 importaciones del proyecto)P2Arquitectura
Duplicados exactos o casi exactosP2Duplicación
Avisos de obsolescenciaP2Trabajo Diferido
Marcadores temporales o de solución provisionalP2Trabajo Diferido
Antipatrones de frameworkP2Violaciones de Patrones
Pruebas acopladas a la implementaciónP2Calidad de Pruebas
Pruebas que solo afirman "no lanza excepción"P2Calidad de Pruebas
Funciones no referenciadas, ramas muertas, archivos huérfanosP2Código Muerto
Anidamiento profundo (>4 niveles)P3Arquitectura
Importaciones no utilizadasP3Código Muerto
Comentarios TODO / FIXMEP3Trabajo Diferido
Código comentadoP3Trabajo Diferido
Violaciones de convencionesP3Violaciones de Patrones
Afirmaciones de prueba frágilesP3Calidad de Pruebas
TODOs que hacen referencia a un ticketP4Trabajo Diferido

Guía de complejidad

  • simple: menos de 10 líneas, un archivo, corrección obvia (eliminar una importación no utilizada).
  • moderate: de 10 a 50 líneas, 2 o 3 archivos, refactorización directa (extraer una función).
  • complex: más de 50 líneas, necesita una decisión arquitectónica, o abarca todo el código base (dividir una clase dios). Nota en la corrección que probablemente necesita un diseño o propuesta antes de la implementación.

Paso 5: Recopilar y deduplicar

  1. Agrupa los hallazgos por categoría + archivo + línea (dentro de 10 líneas). En cada grupo, conserva el hallazgo con la evidencia más detallada, con la gravedad más alta del grupo.
  2. Entre categorías: si Código Muerto y Arquitectura marcan la misma clase, conserva el hallazgo de Arquitectura. Si varias categorías marcan la misma línea, combínalos y conserva la gravedad más alta.
  3. Ordena primero P0, luego P1 a P4.

Paso 6: Verificar issues existentes

Omite este paso solo si se establece --force. Para cada hallazgo, busca un issue abierto que:

  • mencione la misma ruta de archivo en su título o cuerpo, Y
  • cubra el mismo tipo de problema, o una línea dentro de 20 líneas de esta.

Prefiere issues titulados [TechDebt] o que lleven una etiqueta de deuda técnica, pero coincide con cualquier issue abierto que claramente rastree el mismo problema. En caso de coincidencia, marca el hallazgo como ya rastreado como #N y no lo registres. Los diferentes tipos de problema en el mismo archivo son hallazgos separados.

Paso 7: Confirmar, luego crear issues

Omite la creación si es --dry-run o gh_available=false; ve directamente al informe.

Límite: máximo 20 issues a menos que se use --all. Llena los espacios en orden: todos los P0 y P1, luego P2 (prefiere distribuir entre archivos en lugar de muchos issues en un archivo), luego P3, luego P4. Con --all y más de 50 issues, advierte que llevará tiempo.

Etiquetas: usa solo etiquetas que ya existan en gh label list. Elige la coincidencia más cercana para deuda técnica (por ejemplo tech-debt, technical-debt, debt, refactor, chore) y, si el repositorio las tiene, una etiqueta de prioridad que coincida con la gravedad y una etiqueta de tipo (por ejemplo testing). Nunca crees etiquetas sin preguntar. Si no existe una etiqueta adecuada, indícalo y registra sin una o pregunta al usuario si desea crear tech-debt.

Confirmación (obligatoria): antes de crear cualquier cosa, muestra la lista completa y espera la respuesta del usuario. Nunca registres issues sin ella, a menos que hayan pasado --yes.

Se crearán X issues (etiquetas: tech-debt, P2):

1. [P1] [TechDebt] Arquitectura: Dividir OrderService (612 líneas, 27 métodos públicos)
2. [P1] [TechDebt] Calidad de Pruebas: Corregir prueba solo simulada en payment_test.py:45
3. [P2] [TechDebt] Duplicación: Extraer validación de dirección (user.ts:40, account.ts:88)
...

Ya rastreados (omitidos): 3. Por encima del límite (no registrados): 12.
¿Proceder? También puedes eliminar elementos por número o cambiar etiquetas.

Aplica cualquier edición que haga el usuario, luego crea cada issue. Cada cuerpo debe ser independiente, legible por alguien que no haya visto este informe:

gh issue create \
  --title "[TechDebt] <Categoría>: <Descripción breve>" \
  --label "<etiqueta-existente>" \
  --body "$(cat <<'EOF'
**Categoría:** <Categoría>
**Gravedad:** P<N>
**Ubicación:** <archivo:línea>

## Problema
<descripción>

## Evidencia
```
<evidencia>
```

## Corrección sugerida
<corrección>

**Complejidad:** <simple|moderate|complex>

## Criterios de aceptación
- <verificación observable de que la deuda está resuelta>
- El conjunto de pruebas completo del proyecto pasa
EOF
)"

Ejemplos de título:

  • [TechDebt] Código Muerto: Eliminar importaciones no utilizadas en format.ts:5-12
  • [TechDebt] Arquitectura: Dividir OrdersController (567 líneas, 23 acciones)
  • [TechDebt] Calidad de Pruebas: Corregir prueba solo simulada en payment_service_test.go:45

Si una llamada gh issue create falla, registra el error y el comando, continúa con el resto, e informa Creados X issues, Y fallaron al final.

Si el repositorio rastrea el trabajo en un tablero de Proyectos de GitHub (su sección Issue tracking de las instrucciones del agente dice Mode: project, o no existe tal sección y gh repo view --json projectsV2 muestra un tablero vinculado), ofrece ejecutar la habilidad place-issues en los nuevos issues.

Paso 8: Informe resumido

=== Informe de Descubrimiento de Deuda Técnica ===

Ámbito: [rutas analizadas]
Archivos analizados: [recuento]
Stack: [lenguaje / framework / ejecutor de pruebas]
Duración: [tiempo empleado]

## Resumen
- Total de hallazgos: X | Issues creados: Y | Ya rastreados: Z | Por encima del límite: W
- Por gravedad: P0: A, P1: B, P2: C, P3: D, P4: E

## Hallazgos por Categoría

### Código Muerto (X)
- [ ] #N: Eliminar importaciones no utilizadas en format.ts:5-12 (P3)

### Duplicación (X)
- [ ] #N: Extraer validación de dirección (user.ts:40, account.ts:88) (P2)

### Arquitectura (X)
- [ ] #N: Dividir OrderService (612 líneas, 27 métodos públicos) (P1)

### Trabajo Diferido (X)
- [ ] #N: Resolver TODO en billing.py:123 (P3)

### Violaciones de Patrones (X)
- [ ] #N: Corregir riesgo de consulta N+1 en OrdersController#index (P2)

### Calidad de Pruebas (X)
- [ ] #N: Corregir prueba solo simulada en payment_test.py:45 (P1)

## Ya Rastreados
- billing.py:100 TODO → #N

## Hallazgos Adicionales (por encima del límite, no registrados)
[lista]
Ejecuta con --all para registrar los X hallazgos restantes.

## Omitidos (falso positivo o intencional)
- tests/fixtures/** : fixtures excluidos
- TODO(#42) en conftest.py : tiene un ticket vinculado (P4)

## Estado del Análisis
- Código Muerto: Completado
- ...
- Calidad de Pruebas: Incompleto (truncado)

## Errores
[cualquier comando gh fallido]

Para --dry-run, reemplaza los números de issue con [crearía].

Principios

  1. Solo lectura. Sin cambios en el código durante el análisis.
  2. Conservador. Cuando no estés seguro, omite en lugar de informar un falso positivo. Un informe ruidoso se ignora.
  3. Respeta el proyecto. Las convenciones del framework (callbacks, decoradores, inyección de dependencias, enrutamiento basado en convenciones) y las elecciones documentadas en el repositorio no son deuda.
  4. Evidencia primero. Cada hallazgo cita un archivo, una línea y el código que lo demuestra.
  5. Salida estructurada. Los análisis de categorías devuelven JSON para que la fusión y deduplicación sean confiables.
  6. El usuario confirma antes de registrar. La lista siempre se muestra primero.

Individual skills in this repo

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

Skills relacionados