es-kimo/claude-skills

Revisión de Mantenibilidad

El criterio es uno solo: ¿Cuántos lugares debe abrir la siguiente persona (humana o agente) para modificar este código? No se tratan errores de corrección. Eso es tarea de code-review o pr-review.

0. Modo

Modo	Objetivo	Base de comparación	Objetivo de bloqueo
Autoverificación	Mi diff antes del commit	Todo el repositorio	Se corrige (no se reporta, se arregla directamente)
Revisión de cambios	Diff de un PR	Todo el repositorio	Solo problemas introducidos por este cambio
Inspección	Módulo o directorio completo	Todo el repositorio	Todos, ordenados por impacto

En la revisión de cambios, los problemas preexistentes no se marcan como bloqueantes. Se registran por separado como "deuda existente".

1. Leer las bases del proyecto

1. Buscar docs/review/architecture.md. Si no existe, usar el documento de estructura indicado por CLAUDE.md o AGENTS.md.
2. Los criterios del proyecto tienen prioridad sobre los criterios generales de esta skill. Especialmente, obtener del documento base:
   • Mapa de módulos y dirección de dependencias.
   • Lista de abstracciones que deben reutilizarse (cliente HTTP, tipos de resultado, ayudantes de prueba, etc.).
   • Lista de deuda conocida. Los patrones en esta lista no son precedentes que el nuevo código deba seguir.
3. Si no hay documento base, se dibuja el mapa de módulos directamente a partir de la estructura de directorios y los exports de index de cada módulo, y se anota "sin documento base" en la primera línea.

2. Qué revisar

Se revisa de arriba abajo. Cuanto más arriba, mayor es el costo futuro y más frecuentemente lo pasan por alto los agentes.

2-1. ¿Se evitó una abstracción existente?

Los agentes trabajan viendo un solo issue, y sin conocer los módulos creados en issues anteriores, pueden crear lo mismo de nuevo. Es el fallo más común y más costoso.

Por cada función, tipo, clase de error, constante o llamada externa nueva, buscar en el repositorio código que haga lo mismo.

git grep -nE "class \w+Error extends"            # Clases de error
git grep -nE "https?://[a-z.]+\.(com|io|dev)"    # Direcciones y cabeceras de API externas
git grep -nE "^(export )?type \w+ = \{"          # Tipos con nombres similares (ej. XxxEntry)
git grep -nF "<cadena o expresión regular característica del código nuevo>"

• Si hay más de un envoltorio para el mismo sistema externo, los llamadores deberán comprobar el error dividido en varias clases. También buscar su rastro (a instanceof X || b instanceof Y).
• Si la misma constante de lista (extensiones, valores de estado) está en dos sitios, solo una se actualizará.

2-2. Dirección de dependencias

• ¿Se violaron las reglas de capas del documento base? (Ej.: un módulo de dominio importa UI o APIs externas).
• ¿Un submódulo importa un módulo superior, o dos módulos se importan mutuamente?

2-3. Unidades

Dividir no por tamaño, sino por razón de cambio.

• Si un archivo contiene dos o más grupos de funciones que no se llaman entre sí, es señal de que tiene más de una razón de cambio (ej.: mapeo de formularios + acceso a claves anidadas + formato de fechas).
• Si varios archivos de pantalla repiten el mismo proceso preparatorio (autenticación → carga de configuración → rama de error), ese proceso debería ser una función con nombre.

2-4. Calidad de la abstracción

• API faltante: Si dos o más llamadores repiten el mismo preprocesamiento o posprocesamiento, entonces falta una función en el módulo que encapsule ese procesamiento. Ej.: si todos los llamadores hacen doc.items.find((s) => s.kind === "x") y luego parseX(...), falta readX(doc).
• Abstracción excesiva: Interfaces, factorías, opciones o genéricos que solo se usan en un lugar. Son puntos de extensión que no se necesitan ahora.
• Tipos en el límite: Si el llamador debe manejar el fallo, ¿se revela mediante un tipo resultado (unión discriminada)? ¿El llamador no bifurca comparando cadenas de mensaje?

2-5. Patrones

• ¿Se siguen los patrones que el repositorio ya usa (tipo resultado, inyección de dependencias, manejo de errores, forma de exportar módulos)?
• Un patrón nuevo solo se acepta si hay una razón por la que el patrón existente no sirve. Si esa razón no está en el PR o en un comentario, se señala.

2-6. Comentarios y nombres

• ¿El comentario está pegado al objetivo equivocado? Es frecuente que commits de modificación inserten una nueva función entre funciones, dejando el JSDoc sobre otra función.
• ¿El nombre se corresponde con lo que hace? Si el nombre sugiere un comportamiento diferente, se señala.

3. Clasificación

Bloqueante (no fusionar)

• Ya existe código con la misma responsabilidad y se ha creado uno nuevo. Se excluye si en el PR o en un comentario se indica por qué no se puede usar el existente.
• Se ha violado una regla de capas del documento base.
• La nueva API obliga a que dos o más llamadores repitan el mismo procesamiento.
• Un comentario está pegado a un objetivo diferente, induciendo a error al lector.

Sugerencia (no impide la fusión, se deja como trabajo posterior)

• Separación de archivos, mejora de nombres, duplicado preexistente.

Lo que no se menciona: gustos (funcional/imperativo, longitud de línea), lo que detectan linters y formateadores, introducción de nuevas bibliotecas fuera del alcance del issue.

4. Verificación

Cada señalamiento se comprueba con código. Un señalamiento incorrecto hace perder tiempo al agente implementador.

• Si es "duplicado", abrir ambos lugares y verificar que realmente hacen lo mismo. Si tienen apariencia similar pero cumplen especificaciones diferentes, se descarta.
• Si es "en N lugares", contarlos con grep.
• Si es "creado por este cambio", verificar que la línea esté en git diff <base>...HEAD.

5. Informe

Primera línea: alcance revisado (modo, ruta objetivo, existencia de documento base) y recuento (N bloqueantes, N sugerencias, N deuda existente).

Para cada ítem:

• Título: Resultado que indica cuál es el costo. ("Los llamadores de GitHub 401 comprueban el error con 3 clases de error" ✓ / "Mejorar manejo de errores" ✗)
• Ubicación: todas las ubicaciones relevantes en formato archivo:línea. Si es duplicado, ambas.
• Costo: cuántos lugares habrá que modificar la próxima vez que se cambie algo. ("Para cambiar la cabecera de versión de la API, habrá que modificar 3 archivos")
• Dirección: una o dos frases sobre hacia dónde unificar.
• Clasificación: bloqueante / sugerencia / deuda existente.

Si no hay nada que señalar, se escribe "ninguno". No señalar por rellenar.

Lo que no se debe hacer

• Pedir dividir solo por número de líneas o tamaño de archivo.
• Señalamientos sin dirección ("sería mejor abstraer más").
• Considerar duplicado código que solo se parece en apariencia.
• Marcar problemas preexistentes como bloqueantes de este PR.