Personalización
Preferencias personales opcionales: ${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/CodeQuality/PREFERENCES.md.
Si ese archivo existe, léelo y aplícalo; de lo contrario, continúa con los valores predeterminados de la skill. Solo preferencias personales: cualquier
cosa que sea un hecho sobre un repositorio o producto pertenece a ese repositorio (su .claude/workflow-profile.sh
o configuraciones de herramientas), nunca aquí.
¿Qué hace CodeQuality?
Un bucle, dos lentes. El bucle siempre es detectar → elegir un elemento → corregir detrás de pruebas → verificar → repetir. La lente de herramientas corrige lo que los escáneres señalan, en orden de prioridad, con las pruebas existentes como salvaguarda. La lente de principios corrige lo que hace que el código sea difícil de cambiar (clases dios, duplicación, núcleos no testeables), un principio SOLID / Clean Code a la vez, y nunca aplica un movimiento de diseño sin mostrarlo primero. Ambas lentes leen el mismo manifiesto de herramientas, escriben en el mismo directorio de informes y terminan con el mismo Informe de Mejora de Calidad.
Dos lentes
| Lente de herramientas | Lente de principios | |
|---|---|---|
| Controlador | salida del escáner (summary.md) | olores de diseño mapeados a Principles.md (smell-inventory.md, roadmap.md) |
| Unidad de trabajo | un hallazgo: una regla en un archivo:línea | un principio en un punto crítico acotado: una Extracción, una división de clase, una inversión de dependencia |
| Orden | P0 seguridad → P1 corrección → P2 mantenibilidad | escalera de apalancamiento (abajo), ajustada por repositorio |
| Autonomía | corregir, luego mostrar el diff | proponer → confirmar → aplicar; nada se edita antes de la aprobación |
| Red de seguridad | las pruebas existentes siguen en verde | las pruebas de caracterización se escriben primero cuando el objetivo no está probado |
| Métrica | menos hallazgos, herramienta reejecutada limpia | % de duplicación, complejidad ciclomática, longitud de funciones, fan-in/out, "ahora testeable unitariamente" |
| Cuándo elegirla | deuda de lint/tipos/seguridad, CI en rojo, "haz felices a los escáneres" | código que resiste el cambio; nivel estructural de un sprint de remediación |
El bucle
ANALIZAR → SELECCIONAR → RED DE SEGURIDAD → [PROPONER → CONFIRMAR] → CORREGIR → VERIFICAR → INFORMAR → REPETIR
└─ obligatorio en modo principio, se omite en modo herramienta ─┘
Enrutamiento de flujos de trabajo
| Disparador | Flujo de trabajo | Produce |
|---|---|---|
| "instalar herramientas de calidad", "configurar calidad de código" | Workflows/Install.md | herramientas del manifiesto instaladas y verificadas |
| "analizar", "línea base", "analizar calidad de código", "informe de olores", "qué deberíamos arreglar primero", "hoja de ruta de refactorización" | Workflows/Scan.md | summary.md (A), smell-inventory.md (B), roadmap.md (C) |
| "mejorar calidad de código", "corregir lint", "bucle de calidad", "corregir [hallazgo]" | Workflows/Loop.md en modo herramienta | correcciones, session-log.md, informe |
| "refactorizar", "aplicar SOLID", "limpiar esto", "iniciar el bucle" | Workflows/Loop.md en modo principio | correcciones, session-log.md, informe |
| "limpiar este repositorio" sin calificador | Analizar A + B + C, luego Bucle en modo principio | todo lo anterior |
| "sprint de remediación", "ciclo de remediación" | IssueFlow Remediation posee la rama, PR y merge; Analizar define el alcance del ciclo, Bucle lo ejecuta | un PR por ciclo |
El Bucle elige su modo por sí mismo cuando no se da ninguno: herramienta cuando no existe roadmap.md para el
repositorio, principio cuando existe. El usuario puede forzar cualquiera de los dos.
El manifiesto
Tools/tools.tsv es la única lista de herramientas en esta skill. Separado por tabulaciones, una fila por herramienta
y lenguaje: lenguaje categoría prioridad herramienta instalar ejecutar notas, con lenguaje en
js | python | yaml, categoría en lint | format | types | security | deadcode | duplication |
complexity | deps | coverage, prioridad en P0 | P1 | P2. Ambos scripts lo leen; los flujos de trabajo
nunca enumeran herramientas en línea. Para añadir o eliminar una herramienta, edita una fila.
| Script | Lee del manifiesto | Hace |
|---|---|---|
Tools/install-quality-tools.sh [--dry-run] [lang ...] | celdas instalar de los lenguajes elegidos | detecta lenguajes (package.json → js; pyproject.toml, requirements.txt o *.py → python; *.yaml/*.yml → yaml); instala herramientas js como devDependencies con el gestor de paquetes del repositorio (lockfile → npm/pnpm/bun), herramientas python y yaml con uv pip install o pip; los prefijos npm:/pip: anulan el canal, - no instala nada |
Tools/run-quality-baseline.sh [--dry-run] [lang ...] | celdas ejecutar | ejecuta cada herramienta en reports/codequality/<YYYY-MM-DD>-<HHMMSS>/, sustituyendo $OUT (directorio de informes), $SRC (QUALITY_SRC_DIRS, por defecto src si existe, si no .), $PM y $NPX; una herramienta que no está instalada es MISSING, una que falla es FAILED, ninguna detiene la ejecución; escribe summary.md con el estado por herramienta, recuentos de incidencias analizadas y totales P0/P1/P2; imprime la ruta del informe |
Las filas cuyo ejecutar es - (herramientas de cobertura) se instalan pero no se ejecutan en la línea base: la cobertura se
mide en el Bucle, limitada al objetivo. Cada herramienta es gratuita y se ejecuta localmente; npm audit,
pip-audit y checkov acceden a la red solo para sus bases de datos de vulnerabilidades.
Escalera de apalancamiento (orden por defecto de la lente de principios)
- Nombres — código que no puedes leer, no puedes cambiar de forma segura. Barato, desbloquea todo.
- DRY / duplicación — elimina la mayor cantidad de código con el menor riesgo; expone abstracciones ocultas.
- Funciones pequeñas — Método Largo → Extraer; un nivel de abstracción por función.
- SRP — dividir clases y módulos que cambian por más de una razón.
- OCP / DIP — invertir dependencias, añadir puntos de inflexión; alto impacto, mayor riesgo, red de seguridad primero.
- ISP / LSP — interfaces grasas y sustituibilidad rota; necesitan los puntos de inflexión del paso 5.
El análisis parte C ajusta este orden al inventario real (apalancamiento = impacto ÷ riesgo; ver Principles.md Parte 3).
No negociables
- Un elemento por iteración. Un hallazgo, o un principio en un objetivo acotado. Diffs pequeños y revisables.
- Preservación del comportamiento. La estructura cambia, el comportamiento no. Si el comportamiento debe cambiar, detente y márcalo: eso es una característica, no una corrección.
- De verde a verde. Las pruebas pasan antes y después. Rojo después de un cambio significa revertir, nunca corregir hacia adelante.
- Pruebas de caracterización primero cuando las líneas a tocar no están probadas. Sin red, no refactorices.
- Proponer antes de aplicar cualquier movimiento de diseño (modo principio). El modo herramienta puede corregir directamente, luego muestra el diff.
- P0 → P1 → P2 para hallazgos de herramientas, entre lenguajes, nunca por lenguaje.
- Nunca debilitar una prueba o una regla de lint para obtener verde. Las pruebas obsoletas se mueven al nuevo comportamiento correcto; las reglas se satisfacen en el código.
- Boy Scout, acotado. Deja los archivos tocados más limpios, pero no amplíes el alcance más allá del elemento actual.
- Evidencia, no opinión. Nombra la regla o el principio, y una métrica si existe.
Artefactos de salida
Todos bajo reports/codequality/ (ignorado por git):
| Archivo | Escrito por |
|---|---|
<YYYY-MM-DD>-<HHMMSS>/summary.md + salida bruta de herramientas | run-quality-baseline.sh (Análisis A) |
<YYYY-MM-DD>/smell-inventory.md | Análisis B |
<YYYY-MM-DD>/roadmap.md | Análisis C |
<YYYY-MM-DD>/session-log.md | Bucle, una entrada por iteración |
<YYYY-MM-DD>/quality-report.md | Bucle, al final de la sesión (abajo) |
Informe de Mejora de Calidad (obligatorio)
Toda sesión del Bucle termina con este informe, en cualquier modo. Es el entregable junto con el cambio de código, y el cuerpo del PR o comentario del rastreador cuando el trabajo se envía a través de IssueFlow.
| Sección | Contenido |
|---|---|
| Tabla resumen | líneas añadidas / eliminadas / netas; incidencias antes → después por prioridad; puntos críticos de código muerto eliminados; pruebas antes → después (recuento, todas en verde) |
| Código eliminado | archivo, qué, líneas, riesgo |
| Código añadido o modificado | archivo, qué, líneas, propósito |
| Errores corregidos | gravedad, descripción, causa raíz (solo si alguno surgió) |
| Delta de complejidad | complejidad ciclomática máxima y media antes → después, con una barra ASCII por punto crítico |
| Diferido | elementos vistos pero fuera de alcance, y por qué |