vibbs/agent-skills

Architecture Explainer (Explicador de Arquitectura)

Produce un único archivo HTML autónomo por explicador: tiempo de ejecución, topología, prosa, tipografía y estilos incrustados, sin llamadas de red en tiempo de ejecución. Alójalo en cualquier lugar, ábrelo sin conexión, incrústalo en una página con <iframe> o adjúntalo a un correo electrónico.

El modelo

Una topología, muchas proyecciones. El sistema se crea una vez, con toda su profundidad. Todo lo demás es un selector sobre ese único grafo — nunca un segundo diagrama.

TOPOLOGÍA  nodos + aristas + metadatos           ← lo único que creas
──────────────────────────────────────────────────────
PERSONA    política de resolución — vocabulario, profundidad de colapso, qué hechos se muestran
LENTE      superposición de interés — qué aristas existen, qué hecho anuncia cada nodo
ERA        pasado / presente / planeado — presencia y estilo de estado
RITMOS     narrativa — cámara, enfoque, prosa, en secuencia

Dos reglas que impone el tiempo de ejecución y que no debes ignorar:

1. El color pertenece a la lente. El tipo de nodo se indica con la forma — esquina doblada para una fuente, lomo para un almacén, figura para un paso humano, achaflanado para una puerta. Nunca reintroduzcas un esquema de color por tipo; convierte el diagrama en un arcoíris y hace que el cambio de lente pierda sentido.
2. Un diagrama sin recorrido guiado no está terminado. El linter falla la compilación si hay cero ritmos. Esta es la regla que mantiene estos diagramas autoexplicativos en lugar de solo bonitos.

Flujo de trabajo — sigue en orden

1. Entrevista. No inventes el sistema.

El mayor modo de fallo es generar una arquitectura que parezca plausible pero que el usuario nunca describió. Pregunta antes de escribir nada. Usa la herramienta de preguntas estructuradas de tu agente si la tiene.

Cubre:

• Las capas. ¿Cuáles son las 5–8 etapas o grupos de nivel superior? Se convierten en las cajas de nivel 1.
• Componentes por capa. Solo lo que vale la pena mostrar. "Postgres" es una caja; sus tablas no.
• El ciclo de vida. Recorre una solicitud o trabajo representativo de principio a fin. Esto produce las aristas.
• Quién lo lee. Ejecutivo / arquitecto / ingeniero es el conjunto habitual, pero pregunta — podría ser "cliente / nuestro equipo", o "estudiante / profesional".
• Qué intereses importan. Flujo de datos más 2–4 de: costo, latencia, confianza y gobernanza, modos de fallo, propiedad, seguridad. Cada lente necesita sus propias aristas o hechos.
• Si hay historia. v0 → hoy → planeado es el eje de mayor valor para trabajos con clientes y hojas de ruta. Omítelo si el sistema no tiene un pasado significativo.
• El argumento. ¿Qué debería creer un lector después de leerlo? Esto se convierte en los ritmos. Si el usuario no tiene un argumento, el explicador no tiene columna vertebral — insiste en uno.

2. Elige el eje principal

La profundidad rara vez es el interesante. Pregunta para qué sirve el diagrama:

Propósito	Eje principal
Enseñar cómo funciona	Tiempo — ritmos que recorren una solicitud
Presentación al cliente / partes interesadas	Era — lo que existe, lo que se propone
Revisión de diseño, riesgo	Lente — modos de fallo, límites de confianza
Incorporación, referencia	Profundidad — capas luego componentes

3. Escribe la especificación

Lee references/spec-format.md completamente antes de escribir una. Es la referencia completa de nodo / arista / ritmo con todos los campos opcionales.

Copia assets/runtime/specs/llm-eval.js como ejemplo trabajado — ejercita todas las funciones y tiene una buena forma de imitar. Escribe la nueva especificación en specs/<nombre>.js, luego apunta src/spec.js a ella (una línea — el punto de entrada y el linter la leen a través de ahí).

4. Compila

Copia primero assets/runtime a un directorio de trabajo y compila allí. No ejecutes npm install dentro de la carpeta del skill instalado — a menudo es una ubicación de instalación compartida o con enlaces simbólicos.

cp -R <directorio-del-skill>/assets/runtime ./explicador
cd explicador
npm install            # necesita red; ~20s
npm run build          # primero lint de la especificación, luego emite dist/index.html

La salida del linter te indica el recuento de proyecciones. Si falla, arregla la especificación — nunca debilites el linter. Cada regla que impone existe porque un diagrama real se envió sin ella y fue peor. Consulta references/spec-format.md para saber qué significa cada regla.

5. Verifica visualmente — obligatorio, ambos formatos

Este es el paso que más se omite y el más importante. Las matemáticas de diseño no son triviales y los fallos son silenciosos: una etiqueta recortada, una arista que pasa por cinco cajas, una cámara que encuadra espacio vacío. No declares terminado sin mirar.

node scripts/shots.mjs        # matriz de escritorio → shots/

Luego haz una captura de pantalla en tamaño de teléfono tú mismo (390×844) y abre e inspecciona las imágenes. Comprueba:

• Cada combinación de persona × era se renderiza sin superposición ni recorte.
• Cada lente cambia realmente la imagen — si dos lentes se ven idénticas, sus conjuntos de aristas son incorrectos.
• Encuadre de ritmos. Recorre los ritmos; cada uno debe encuadrar su enfoque con contexto visible, no espacio vacío ni todo el sistema.
• Etiquetas. Nada recortado, nada superpuesto a una caja.
• Teléfono. Reflujo a una columna, legible al 100%, controles que no se desbordan.
• Consola. Cero errores, incluso dentro de un iframe en sandbox.

Si algo se ve mal, lee references/troubleshooting.md antes de cambiar el código de diseño.

6. Entrega

Dale al usuario el archivo dist/index.html compilado. Dile que el archivo es autónomo y puede alojarse, incrustarse o abrirse sin conexión.

Solo para Claude Code / aplicaciones Claude. Envía el archivo con SendUserFile. Si es algo que el usuario volverá a visitar — la mayoría de los explicadores lo son — también persístelo con create_artifact.

No negociables

• Cada nodo tiene un por qué — una frase sobre por qué existe la caja, no qué es.
• Todo lo que un ejecutivo pueda ver tiene detalle a nivel ejecutivo en vocabulario ejecutivo.
• Al menos 6 ritmos, cada uno con prosa real. Ritmos pobres producen una presentación de diapositivas, no un argumento.
• ≤34 nodos hoja. Más allá de eso, divide en varios explicadores en lugar de abarrotar.
• Un tema por compilación. Los lectores tienen un conmutador claro/oscuro, nada más.

Adaptación

• Dirección visual diferente — src/themes.js contiene cinco (house, swiss, editorial, draft, shadcn). Cambia THEME_ID en src/App.jsx. Si agregas una tipografía debes configurar metrics.charFactor correctamente o cada etiqueta se recorta; consulta references/troubleshooting.md.
• Más personas / lentes / épocas — solo datos de especificación, sin cambios de código.
• Generación a partir del código fuente — un script que recorre un repositorio y emite el árbol DIAGRAM es una extensión razonable, pero el por qué, el detalle y los ritmos aún deben provenir de un humano.

Alcance

Esto construye figuras explicativas, no paneles en vivo, no herramientas de dibujo libre, y no inventarios de infraestructura. Si el usuario quiere un diagrama editable que seguirá arrastrando, quiere drawio. Si quiere un número en una página, quiere un gráfico.