c4-architecture

Visión general de la skill c4-architecture

La skill c4-architecture te ayuda a generar documentación de arquitectura de software como diagramas C4 en Mermaid, no solo a dibujar cajas. Es una opción especialmente útil para ingenieros, technical writers, arquitectos de staff y equipos que necesitan documentación de arquitectura que explique un sistema con el nivel adecuado para cada audiencia: contexto para lectores amplios, contenedores para perfiles técnicos, componentes para desarrolladores y vistas de despliegue para operaciones.

Para qué sirve c4-architecture

Usa c4-architecture cuando el trabajo real consiste en convertir un codebase, un mapa de servicios o una descripción preliminar del sistema en documentación de arquitectura estructurada. Resulta especialmente útil cuando necesitas diagramas que puedan vivir en Markdown y en control de versiones, en lugar de quedar como una exportación puntual de una pizarra.

Casos de uso en los que mejor encaja

Esta c4-architecture skill encaja muy bien para:

• documentar un repo existente para facilitar el onboarding
• crear una vista de contexto del sistema y de contenedores para ADRs o documentación técnica
• explicar microservicios, sistemas orientados a eventos y dependencias externas
• producir diagramas de arquitectura para sitios de documentación, wikis o pull requests
• crear contenido de arquitectura para flujos de trabajo de Technical Writing

Qué la diferencia de un prompt genérico para diagramas

Un prompt normal puede producir una respuesta con forma de diagrama, pero esta skill te da un flujo de trabajo más claro y mejores valores por defecto:

• se apoya en el modelo C4, por lo que los niveles de abstracción se mantienen más limpios
• trata Context y Container como la base, no como extras opcionales
• incluye guía de sintaxis para diagramas Mermaid C4
• te avisa de errores de modelado habituales antes de que publiques documentación engañosa
• incluye patrones avanzados para microservicios y sistemas más complejos

Lo que suele importar primero a quienes la evalúan

Antes de instalar o invocar c4-architecture, la mayoría quiere saber:

• ¿Me ayudará si mi sistema solo se entiende de forma parcial? Sí, siempre que puedas aportar actores, servicios principales, data stores y sistemas externos.
• ¿Funciona bien para documentación centrada en Markdown? Sí, la salida en Mermaid es el valor principal.
• ¿Es útil para technical writers sin experiencia profunda en arquitectura? Sí, porque la skill toma decisiones claras sobre niveles y errores comunes.
• ¿Sustituye una revisión profunda de arquitectura? No. Acelera los primeros borradores y la documentación estructurada, pero la precisión del sistema sigue dependiendo de tus inputs.

Cómo usar la skill c4-architecture

Instala c4-architecture en tu entorno de skills

Si tu agente es compatible con el patrón de CLI de skills que usa este repositorio, instálala con:

npx skills add softaworks/agent-toolkit --skill c4-architecture

Si tu entorno carga skills desde un repositorio clonado, usa la skill desde:

skills/c4-architecture

Lee primero estos archivos antes del primer uso

Si quieres una guía de c4-architecture rápida y con alta densidad de información, léelos en este orden:

1. skills/c4-architecture/SKILL.md
2. skills/c4-architecture/references/common-mistakes.md
3. skills/c4-architecture/references/c4-syntax.md
4. skills/c4-architecture/references/advanced-patterns.md
5. skills/c4-architecture/README.md

Por qué este orden funciona:

• SKILL.md te da el flujo de trabajo previsto
• common-mistakes.md evita los errores de modelado más frecuentes
• c4-syntax.md te ayuda a depurar rápido la salida Mermaid
• advanced-patterns.md importa cuando tu sistema no es un monolito simple

Elige el nivel C4 adecuado antes de escribir el prompt

La palanca que más influye en la calidad del uso de c4-architecture es elegir el nivel correcto para la audiencia:

• C4Context: empieza siempre por aquí; muestra usuarios y sistemas externos
• C4Container: normalmente es imprescindible; muestra apps, bases de datos, colas y servicios
• C4Component: añádelo solo cuando la estructura interna realmente ayude a los lectores
• C4Deployment: úsalo para aspectos de runtime o infraestructura
• C4Dynamic: úsalo para flujos importantes de requests o eventos

Un fallo muy común es saltar directamente a componentes y generar ruido antes de que los lectores entiendan el límite del sistema.

Dale a la skill el mínimo de información que realmente necesita

No necesitas notas de arquitectura perfectas, pero sí la suficiente estructura para evitar una topología inventada. Entre los buenos inputs están:

• nombre y propósito del sistema
• usuarios principales o actores externos
• servicios/apps/data stores principales
• sistemas externos o vendors
• relaciones y protocolos clave
• audiencia objetivo
• niveles de diagrama deseados
• archivo de salida o ubicación en la documentación

Si solo dices “make a C4 diagram for my app”, espera una salida genérica.

Convierte una petición vaga en un buen prompt para c4-architecture

Prompt débil:

Create a C4 diagram for our platform.

Prompt más sólido:

Use the c4-architecture skill to document our B2B analytics platform. Audience: engineering and product. Create C4Context and C4Container diagrams in Mermaid plus brief Markdown explanations. System boundary: Analytics Platform. Actors: Customer Admin, Analyst. External systems: Okta, Stripe, Snowflake, SendGrid. Internal containers: React web app, API gateway, Python ingestion service, dbt transform jobs, PostgreSQL app DB, Redis cache. Show key relationships and protocols. Avoid component-level detail unless necessary.

La versión más sólida mejora la salida porque especifica audiencia, alcance, límites, actores, contenedores internos y dependencias externas.

Usa un flujo de trabajo práctico, no una petición de una sola vez

A la hora de decidir si instalar c4-architecture, lo que suele pesar es si su flujo encaja con el trabajo real de documentación. En la práctica:

1. pide primero un diagrama de contexto
2. revisa qué actores y sistemas externos faltan
3. genera el diagrama de contenedores
4. añade vistas de componentes o despliegue solo donde los lectores las necesiten
5. guarda los diagramas en Markdown con un texto breve de explicación

Este enfoque por etapas funciona mejor que pedir cinco tipos de diagramas a la vez, porque los errores en los niveles 1 y 2 se arrastran a todos los diagramas de niveles inferiores.

Cómo aprovecharla bien para Technical Writing

c4-architecture for Technical Writing encaja bien cuando los writers necesitan documentación de arquitectura legible, mantenible y versionada junto al código. La skill ayuda porque produce diagramas que se pueden incrustar en Markdown y acompañar con texto breve.

Para tareas de technical writing, incluye:

• nivel del lector objetivo: ejecutivo, técnico mixto, developer, ops
• términos de glosario o nombres de producto aprobados
• terminología preferida para servicios y equipos
• ubicación de la documentación, como /docs/architecture/
• si la salida debe explicar por qué existe cada diagrama

Así evitas un problema muy común: diagramas técnicamente plausibles, pero desalineados con la voz de la documentación o con su arquitectura de la información.

Ten claras las reglas de modelado que más afectan a la calidad

La guía de errores del repositorio destaca algunas reglas especialmente importantes:

• los contenedores son unidades desplegables/de runtime, no clases
• los componentes son partes internas dentro de un contenedor
• no inventes niveles C4 no oficiales
• mantén niveles de abstracción consistentes dentro de un diagrama
• añade solo el detalle que ayude a la toma de decisiones de la audiencia

Si solo recuerdas una cosa, que sea esta: la mayoría de los malos diagramas C4 fallan por mezclar niveles, no por una sintaxis incorrecta.

Recurre a la documentación de referencia cuando falle la salida Mermaid

Cuando el diagrama generado no renderiza o su estructura se ve mal, revisa:

• references/c4-syntax.md para ver declaraciones y elementos válidos de Mermaid C4
• primero la sintaxis de relaciones y de boundaries
• si has usado el tipo de diagrama correcto, por ejemplo C4Container frente a C4Component

Esta skill resulta más usable que un prompt genérico, en parte porque la referencia de sintaxis te da una ruta clara para corregir errores.

Cuándo importan los patrones avanzados

Abre references/advanced-patterns.md cuando tu arquitectura incluya:

• microservicios con varios límites de servicio
• API gateways
• flujos orientados a eventos o basados en colas
• más de un límite de ownership
• vistas de infraestructura o despliegue que necesiten nodos y entornos reales

Ese archivo es especialmente útil cuando un modelo mental simple de “un sistema, una app, una base de datos” produciría documentación engañosa.

FAQ de la skill c4-architecture

¿c4-architecture es buena para principiantes?

Sí, especialmente si puedes describir el sistema en lenguaje claro. El flujo de trabajo de la skill y su guía de errores reducen los fallos habituales en C4. Quienes empiezan deberían limitarse a Context y Container y evitar diagramas Component hasta que el límite del sistema esté claro.

¿Cuándo no debería usar c4-architecture?

Evita c4-architecture si solo necesitas un boceto informal rápido, un artefacto de diseño pixel-perfect o un modelo interno de diseño muy centrado en UML. Donde mejor rinde es cuando buscas documentación de arquitectura mantenible en Mermaid, no un diseño de implementación exhaustivo.

¿Es mejor que pedirle directamente a una IA un diagrama en Mermaid?

En general, sí, para documentación de arquitectura. Un prompt genérico puede generar Mermaid, pero c4-architecture te da una estructura más sólida: selección de nivel, disciplina de modelado, referencia de sintaxis y anti-patrones conocidos. Eso la hace más fiable para documentación que otras personas van a leer y mantener.

¿c4-architecture sirve tanto para monolitos como para microservicios?

Sí. En monolitos, ayuda a separar contexto, contenedores y vistas de componentes seleccionadas. En microservicios, la referencia de patrones avanzados resulta útil para decidir cuándo mostrar servicios como contenedores y cuándo conviene tratarlos como límites de sistema más amplios.

¿Necesito acceso al codebase completo?

No, pero cuanto mejor sea el material de partida, mejores serán los resultados. La skill puede trabajar a partir de notas de arquitectura, estructura del repo, listados de servicios, documentación de APIs, deployment manifests o descripciones de stakeholders. Si tus inputs son parciales, pídele que marque explícitamente las suposiciones.

¿Puedo usar c4-architecture para vistas de despliegue y runtime?

Sí. La skill admite C4Deployment y también diagramas de flujo dinámico. Úsalos solo cuando la topología en runtime o el flujo de requests sea relevante para el lector; de lo contrario, pueden añadir ruido.

Cómo mejorar la skill c4-architecture

Empieza por hechos, no por estructura inferida

La forma más rápida de mejorar la salida de c4-architecture es proporcionar una lista de hechos antes de pedir diagramas:

• usuarios
• límite del sistema
• unidades desplegables
• data stores
• dependencias externas
• protocolos
• entornos o modelo de hosting

Esto reduce relaciones erróneas expresadas con demasiada seguridad.

Pide que las suposiciones se enumeren de forma explícita

Una mejora de mucho valor en el prompt es:

If any element is uncertain, list assumptions before generating the final Mermaid.

Esto ayuda especialmente al documentar un sistema heredado o al usar la skill a partir de notas parciales.

Revisa la salida de contexto y contenedores antes de profundizar

No aceptes un diagrama de componentes hasta que las capas de contexto y contenedores estén bien. Si el modelo de contenedores es incorrecto, el detalle de componentes solo hará que el documento parezca pulido sin dejar de ser inexacto.

Corrige sin concesiones los errores de abstracción

Si la salida muestra clases, packages o endpoints como contenedores, detente y corrige eso primero. La guía de common-mistakes.md importa porque unos niveles de abstracción incorrectos hacen que todo el documento inspire menos confianza.

Un prompt de corrección útil es:

Revise this as a true C4Container diagram. Only include deployable applications, services, data stores, and external systems. Move internal modules to a later component view.

Especifica la audiencia en cada petición importante

La audiencia cambia por completo qué significa “bueno”:

• los ejecutivos necesitan contexto, resultados y dependencias externas
• los ingenieros necesitan contenedores, protocolos y límites de responsabilidad
• los developers pueden necesitar detalle de componentes dentro de un contenedor
• los equipos de ops necesitan nodos de despliegue y entornos

Sin audiencia, la skill puede generar un nivel de detalle incorrecto incluso si la sintaxis es válida.

Acompaña los diagramas con texto breve de apoyo

La skill resulta más útil cuando pides entre 2 y 5 bullets bajo cada diagrama que cubran:

• qué muestra el diagrama
• por qué se eligió ese nivel
• interacciones clave
• qué queda excluido de forma intencional

Ese pequeño añadido hace que la salida sea mucho más útil en documentación y en hilos de revisión.

Itera con cambios dirigidos, no con reescrituras completas

Tras la primera pasada, mejora la calidad con correcciones concretas como:

• añadir sistemas externos que faltan
• renombrar contenedores para que coincidan con la terminología del producto
• dividir un servicio sobrecargado en dos contenedores
• añadir protocolos a las relaciones
• eliminar detalle de componentes de la vista de contenedores
• generar una vista de despliegue solo para producción

Una iteración dirigida conserva la buena estructura y converge más rápido que un simple “try again”.

Usa c4-architecture como sistema de documentación, no solo como generador

El mejor uso a largo plazo de la c4-architecture skill es estandarizar la documentación de arquitectura dentro de tu repo. Mantén los diagramas Mermaid cerca del código o de la documentación, revísalos en pull requests y actualízalos cuando cambien los servicios o los límites. Ahí es donde esta skill supera al prompting ad hoc: hace posible una documentación de arquitectura repetible y nativa de Markdown.