nedeadinside/likec4-skill

Diagramas C4 con LikeC4

Produce diagramas C4 válidos en el DSL de LikeC4 a partir de una descripción verbal o de un código base, y valídalos con el CLI antes de la entrega. Las referencias están divididas por tema: lee solo lo que la tarea necesita, antes de escribir esa parte; no adivines la sintaxis.

Todo lo que hay aquí está verificado contra likec4 1.59.2 (consulta references/setup-and-validation.md para el procedimiento de fijación y actualización).

Reglas estrictas (solo dos)

1. Valida antes de entregar. Ejecuta likec4 validate en el proyecto y entrega solo si el código de salida es 0. Si no hay CLI disponible → realiza la autocomprobación documentada e indícalo. Procedimiento: references/setup-and-validation.md.
2. Nunca inventes sintaxis DSL. Si no estás seguro, abre la referencia correspondiente; si aún tienes dudas, consulta https://likec4.dev/dsl/.

Configuración (lo primero, una vez por sesión)

LC4="npx -y [email protected]"
v="$(likec4 --version 2>/dev/null | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+' | tail -1)"
[ -n "$v" ] && [ "$(printf '%s\n1.53.0\n' "$v" | sort -V | head -1)" = "1.53.0" ] && LC4=likec4

Un CLI instalado se usa solo si es >= 1.53.0 — las versiones anteriores no tienen el comando format y la 1.52.0 sale con código 0 en modelos inválidos, por lo que ambos controles siguientes pasarían silenciosamente. No se requiere instalación global — npx -y [email protected] funciona en cualquier entorno con Node 22+ y conexión de red (la primera ejecución descarga, luego queda en caché). Para proyectos que el usuario conserve, recomienda npm install --save-dev [email protected]. Detalles, versión mínima, alternativa sin conexión y catálogo de errores: references/setup-and-validation.md.

Tarea → qué leer

Tarea que tienes	Leer
Contexto del Sistema / Paisaje ("quién lo usa, con qué se comunica")	references/levels/l1-context.md
Contenedores ("qué se ejecuta dentro", elecciones tecnológicas)	references/levels/l2-container.md
Componentes (dentro de un contenedor)	references/levels/l3-component.md
Nivel de código — clases/interfaces de un componente	references/levels/l4-code.md
Flujo de datos / escenario / secuencia (inicio de sesión, compra, pipeline)	references/levels/flows-dynamic.md
Infraestructura / "dónde se ejecuta"	references/levels/deployment.md
Cualquier pregunta transversal del DSL (especificación, modelo, FQN, extend, predicados)	references/syntax-core.md
Colores, formas, iconos, leyenda, diseño	references/styling.md
Dado un repositorio / código fuente	references/code-to-diagram.md
Instalar, validar, formatear, errores, vista previa/exportación/CI	references/setup-and-validation.md

Escalar la estructura según la tarea

• Petición pequeña (un sistema, imagen rápida de contexto/contenedor): empezar desde templates/minimal/ — 3 archivos (spec.c4, model.c4, views.c4). No construyas un proyecto con varias carpetas para esto.
• Sistema real (2+ niveles, varios sistemas, despliegue, flujos): usa la estructura templates/full/ — copia los archivos y renombra el contenido:

architecture/
├── spec.c4                 # el ÚNICO bloque de especificación: todos los tipos
├── model/
│   ├── landscape.c4        # sistemas de nivel superior + actores
│   ├── <system>.c4         # un archivo por sistema, mediante extend <system> { … }
│   └── externals.c4        # elementos externalSystem
├── deployment/prod.c4      # nodos + instanceOf (los tipos permanecen en spec.c4)
└── views/
    ├── context.c4          # Nivel 1 (índice de vistas)
    ├── <system>-views.c4   # Vistas de Nivel 2/3 con profundización
    └── dynamic-flows.c4    # vistas dinámicas + de despliegue

Crece añadiendo archivos (nuevo sistema → nuevo model/<s>.c4), mantén el modelo separado de las vistas, y mantén la especificación en un solo archivo. Todos los archivos .c4 dentro de la carpeta se fusionan automáticamente en un solo modelo.

Las plantillas usan solo los colores de tema integrados (en alcance = primary, externo = gray mediante el tipo externalSystem, persona = indigo) — sin colores personalizados, sin etiquetas. Esto mantiene la convención C4 y se adapta a temas claros/oscuros.

Flujo de trabajo

1. Alcance — identifica el sistema, actores, externos; elige los niveles. Por defecto: Contexto + Contenedor; Componente solo para un contenedor no trivial; una vista dinámica para cada escenario clave (recomendado); despliegue cuando la infraestructura importe; Nivel 4 solo por solicitud explícita o justificación clara (references/levels/l4-code.md — el sustituto por defecto es un enlace a la fuente). Si la entrada es un repositorio → references/code-to-diagram.md. Si el alcance es realmente ambiguo → haz una pregunta; en caso contrario, continúa y declara los supuestos.
2. Configura — copia la plantilla correspondiente, ejecuta la línea LC4 anterior.
3. Modelo, luego vistas — escribe los archivos del modelo, luego las vistas con profundización (view of, navigateTo), leyendo el archivo de nivel para cada diagrama que produzcas.
4. Valida, luego formatea — $LC4 validate <dir>; corrige los errores Línea N: (catálogo en setup-and-validation.md) hasta que el código de salida sea 0. Luego `$LC4 format
5. Entrega — muestra el árbol de archivos, el resultado de la validación y cómo ver los diagramas ($LC4 start <dir>; opciones de exportación/CI en setup-and-validation.md).

Barra de calidad (verificar antes de entregar)

• likec4 validate código de salida 0 (o autocomprobación indicada), stderr limpio.
• likec4 format <dir> --check código de salida 0 — los archivos están en forma canónica.
• Cada elemento tiene una descripción; cada contenedor/componente un technology; cada relación una etiqueta direccional (qué + cómo).
• Cada vista tiene un title; ≤ ~20 elementos por vista — divide vistas abarrotadas.
• Los niveles se conectan: Contexto → Contenedor → Componente mediante view of / navigateTo.