Arquitecto de Clases de Proyecto

¿Qué hace Arquitecto de Clases de Proyecto?

Convierte un repositorio en un diagrama de clases UML interactivo que un desarrollador puede explorar en lugar de leer cientos de archivos. El análisis se basa en evidencia: cada clase, atributo, método y relación en el diagrama apunta al archivo y línea de origen. Nada se inventa; los hallazgos heurísticos se etiquetan como inferido.

Todas las rutas en este archivo son relativas al directorio de la habilidad (la carpeta que contiene este SKILL.md).

Requisitos

• Node.js 18+ (node --version). Los scripts no tienen dependencias: nunca ejecutes npm install para esta habilidad.
• Acceso de lectura al repositorio. El análisis nunca modifica los archivos fuente; solo escribe su carpeta de salida.
• Si Node.js no está disponible, usa el método alternativo descrito al final.

Flujo de trabajo

1. Identificar el repositorio

Usa la ruta absoluta del proyecto del que el usuario está hablando (normalmente el espacio de trabajo actual). Los comandos a continuación se ejecutan desde el directorio de la habilidad, por lo que una ruta relativa como . apuntaría a la propia habilidad.

2. Generar el diagrama

node scripts/class-architect.js generate "/ruta/absoluta/al/repo"

Opciones útiles (consulta la referencia de CLI para todas ellas):

Necesidad	Opción
Autor en el pie de página	--author "Nombre" --author-role "Ingeniero de Software"
Título del diagrama	--title "Servicio de Facturación"
Solo parte de un repositorio grande	--include "src/main/java/com/acme/billing/**" (repetible)
Omitir carpetas	--exclude "legacy/**" (repetible)
Restringir idiomas	--languages java,sql
Analizar también pruebas	--include-tests
Vista / diseño inicial	--view classes|er|overview|packages --layout grouped|layered|hierarchical|grid
Carpeta de salida personalizada	--out "/ruta/a/salida" (por defecto <repo>/.class-architect)
Ocultar rutas locales del HTML	--hide-root (deshabilita los enlaces "abrir en editor")

El comando imprime un resumen JSON en stdout (el progreso va a stderr). Códigos de salida: 0 éxito, 1 error de uso, 2 sin archivos fuente analizables, 3 fallo de validación del modelo (no se escribe nada), 4 error interno.

3. Verificar el resultado

Lee el resumen JSON (status, outputs, summary.counts, summary.insights, summary.edits, validation). Salidas escritas en la carpeta de salida:

• diagram.html - el diagrama interactivo (ábrelo en un navegador; funciona sin conexión).
• report.md / report.json - archivos escaneados, clases, interfaces, enumeraciones, relaciones, relaciones inferidas, referencias no resueltas, archivos excluidos con razones, advertencias, información.
• model.json - el modelo UML (fuente única de verdad); overlay.json - ediciones del usuario, cuando las hay.

Si el código de salida es 2, ajusta --include / --languages y menciona qué carpetas fueron excluidas y por qué (desde el JSON details). Si el código de salida es 3, informa los errores de validación; no edites manualmente el modelo para ocultarlos.

Para repositorios con cientos de clases, el diagrama se abre en la Vista general (módulos) y permite al usuario profundizar en módulos y paquetes; también puedes generar diagramas enfocados con --include para un contexto acotado.

4. Presentar el diagrama al usuario

• Proporciona la ruta de diagram.html (y su URL file:// desde outputs.diagramUrl). No intentes lanzar un navegador a menos que el usuario lo pida y tu entorno lo permita.
• Resume solo lo que dice el informe: números de clases / interfaces / enumeraciones / relaciones, frameworks detectados, ciclos de dependencia, hallazgos de arquitectura, referencias no resueltas y advertencias. Cita los nombres de las clases exactamente.
• Menciona que las relaciones marcadas como inferidas (convenciones de nomenclatura, tipificación estructural de Go) deben verificarse, y que los nombres de tablas/columnas derivados están marcados como derivados.
• Señala las principales interacciones: haz clic en una clase o línea para inspeccionarla (con archivo y línea de origen), búsqueda (/), filtros, vistas (Vista general, Paquetes, Clases, ER de base de datos), la lupa (L), modo de edición (E), Información, Exportar. Detalles: la guía del diagrama interactivo.

5. Actualizar después de cambios en el código

Ejecuta el mismo comando de nuevo. Este:

• reanaliza solo los archivos cambiados (caché incremental),
• conserva todas las ediciones del usuario (de overlay.json y de las ediciones que el usuario guardó en diagram.html con el botón Guardar),
• reporta las ediciones cuyo destino desapareció del código como huérfanas (conservadas, nunca eliminadas en silencio) y las ediciones que entran en conflicto con un cambio en el código fuente,
• resalta las clases añadidas / eliminadas / modificadas en comparación con la ejecución anterior,
• mantiene una copia de seguridad del diagrama anterior (diagram.prev.html).

Si el usuario ha descargado una copia del diagrama en otro lugar, pásala con --edits "/ruta/al/diagrama-guardado.html".

6. Opcional: secciones de documentación

El diagrama puede mostrar documentación adicional debajo de él (tablas, flujos, pasos, cuadrículas de enumeraciones, notas de banner) usando los componentes de la plantilla original. Solo añade hechos que hayas verificado en el código y cita el archivo fuente. Escribe un archivo JSON siguiendo la guía de configuración y pásalo con --notes notes.json.

Reglas

• Nunca modifiques, formatees o "arregles" el código fuente analizado como parte de esta habilidad.
• Nunca inventes clases, miembros o relaciones, y nunca presentes una relación inferida como cierta.
• Nunca elimines o sobrescribas overlay.json o un diagram.html guardado por el usuario: el CLI los fusiona por ti.
• La carpeta de salida .class-architect/ se genera; sugiere añadirla a .gitignore a menos que el usuario quiera confirmar el diagrama.
• No subas el diagrama ni el modelo a ningún lugar: pueden contener estructura de código propietaria.

Método alternativo cuando los scripts no pueden ejecutarse

Si Node.js 18+ no está disponible o no se permite la ejecución de comandos:

1. Lee los archivos fuente relevantes y escribe un modelo JSON a mano siguiendo la referencia del modelo UML. Incluye solo elementos que viste en el código, con source.file y source.line; establece confidence: "inferred" para cualquier cosa no explícita.
2. Copia templates/viewer.html a la ubicación donde el usuario quiere el diagrama (por ejemplo class-diagram.html).
3. En la copia, reemplaza el texto null dentro de <script type="application/json" id="pca-data">null</script> con {"model": <tu modelo>, "overlay": null, "meta": {"title": "<nombre del proyecto>"}}, escribiendo < como < dentro del JSON.
4. Alternativamente, dile al usuario que abra templates/viewer.html y arrastre el archivo model.json a la página.

El diseño, las interacciones y las exportaciones funcionan entonces en el navegador exactamente igual que en un diagrama generado; solo faltan la extracción automática, la detección de cambios y el informe de validación. Di claramente que el modelo fue escrito a mano.

Otros comandos

node scripts/class-architect.js analyze "/abs/repo"                       # modelo + informe, sin HTML
node scripts/class-architect.js render --model model.json --out diagram.html
node scripts/class-architect.js validate --model model.json --html diagram.html
node scripts/class-architect.js diff --base old-model.json --head model.json
node scripts/class-architect.js edits --from saved-diagram.html --out overlay.json
node scripts/class-architect.js viewer --out viewer.html
node scripts/class-architect.js doctor

Archivos de referencia (léelos solo cuando sea necesario)

• references/CLI.md - todos los comandos, opciones, salidas y códigos de salida.
• references/INTERACTIVE-DIAGRAM.md - qué puede hacer el usuario en el diagrama, atajos de teclado.
• references/RELATIONSHIPS.md - cómo se decide cada tipo de relación y multiplicidad, evidencia y confianza.
• references/LANGUAGES.md - idiomas, frameworks y ORMs compatibles, y qué se extrae.
• references/CONFIGURATION.md - class-architect.config.json, entidades externas, umbrales, notas de documentación.
• references/UML-MODEL.md - el formato del modelo (para el método alternativo o para otras herramientas).
• references/LIMITATIONS.md - limitaciones conocidas para mencionar cuando sea relevante.