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
- Si se proporcionaron rutas, úsalas.
- Si se proporcionó
--full, escanea el repositorio con las exclusiones anteriores. - 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:
| Indicador | Stack |
|---|---|
Gemfile con rails, o config/application.rb | Ruby on Rails |
manage.py o django en requirements / pyproject.toml | Django |
pyproject.toml / requirements.txt con fastapi o flask | Python web |
package.json con next, react, vue, svelte, express, nestjs | JS/TS framework |
go.mod | Go |
Cargo.toml | Rust |
pom.xml / build.gradle* | JVM (Spring si está presente) |
composer.json con laravel/framework | Laravel |
*.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):
- Anuncia
Analizando [Categoría]... (X de N). - Aplica la lista de verificación para esa categoría en
references/categories.md, adaptada al stack detectado. - Recopila los hallazgos en el formato JSON a continuación.
- 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ón | Gravedad | Categoría |
|---|---|---|
| Pruebas que ocultan problemas de seguridad | P0 | Calidad de Pruebas |
| Falta de verificación de autorización en el acceso a recursos | P1 | Violaciones de Patrones |
| Clases dios (>500 líneas o >20 métodos públicos) | P1 | Arquitectura |
| Dependencias circulares | P1 | Arquitectura |
| Código inalcanzable | P1 | Código Muerto |
| Pruebas solo simuladas (la prueba simula lo que está probando) | P1 | Calidad de Pruebas |
| Simular el sujeto y luego afirmar sobre él | P1 | Calidad de Pruebas |
| Pruebas tautológicas | P1 | Calidad de Pruebas |
| Cuerpos de prueba vacíos | P1 | Calidad de Pruebas |
| Simulación excesiva (>50% de la prueba es configuración) | P1 | Calidad de Pruebas |
| Simular cada instancia de una clase | P1 | Calidad de Pruebas |
| Estado mutable compartido entre pruebas | P1 | Calidad de Pruebas |
| Funciones largas (>50 líneas) | P2 | Arquitectura |
| Alto acoplamiento (>10 importaciones del proyecto) | P2 | Arquitectura |
| Duplicados exactos o casi exactos | P2 | Duplicación |
| Avisos de obsolescencia | P2 | Trabajo Diferido |
| Marcadores temporales o de solución provisional | P2 | Trabajo Diferido |
| Antipatrones de framework | P2 | Violaciones de Patrones |
| Pruebas acopladas a la implementación | P2 | Calidad de Pruebas |
| Pruebas que solo afirman "no lanza excepción" | P2 | Calidad de Pruebas |
| Funciones no referenciadas, ramas muertas, archivos huérfanos | P2 | Código Muerto |
| Anidamiento profundo (>4 niveles) | P3 | Arquitectura |
| Importaciones no utilizadas | P3 | Código Muerto |
| Comentarios TODO / FIXME | P3 | Trabajo Diferido |
| Código comentado | P3 | Trabajo Diferido |
| Violaciones de convenciones | P3 | Violaciones de Patrones |
| Afirmaciones de prueba frágiles | P3 | Calidad de Pruebas |
| TODOs que hacen referencia a un ticket | P4 | Trabajo 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
- 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.
- 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.
- 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
- Solo lectura. Sin cambios en el código durante el análisis.
- Conservador. Cuando no estés seguro, omite en lugar de informar un falso positivo. Un informe ruidoso se ignora.
- 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.
- Evidencia primero. Cada hallazgo cita un archivo, una línea y el código que lo demuestra.
- Salida estructurada. Los análisis de categorías devuelven JSON para que la fusión y deduplicación sean confiables.
- El usuario confirma antes de registrar. La lista siempre se muestra primero.