La documentación de arquitectura que reside en una wiki muere en una wiki. La documentación que se lee es la que está en el repositorio — y la documentación que se escribe es la que el *scaffold* ya incluía.
La mayoría de la documentación de arquitectura se escribe a posteriori, en una herramienta separada, por alguien que no estuvo presente. Se deteriora. C4 — Contexto, Contenedor, Componente, Código — funciona porque está estructurado, y funciona en un repositorio porque reside junto al código que describe.
Lo Primero: Documentación Antes del Código
Comience con el fin en mente: ¿qué debería entender un nuevo desarrollador en diez minutos? El modelo C4 responde a eso — el contexto en el que opera el sistema, los contenedores de los que está compuesto, los componentes dentro de ellos y las invariantes a nivel de código. Si estos están en el repositorio, la incorporación está a un README de distancia.
- Contexto: con qué se comunica el sistema y por qué.
- Contenedor: las unidades desplegables y sus límites.
- Componente: las piezas dentro de cada contenedor.
- Código: las invariantes — las decisiones que no cambian.
Desglosar el Deterioro
¿Por qué se deteriora la documentación de arquitectura? Reside separada del código, se escribe una vez y nadie la actualiza. C4 en el repositorio soluciona los tres problemas: está junto al código, está estructurada y la sección de invariantes es la parte que menos debería cambiar.
Lo que Incluyen las Plantillas
Cada Plantilla de FACTA incluye su propio README, documentación de arquitectura (C4 + invariantes) y esqueleto. La documentación no es una fase dos — está integrada, para que tanto el agente como el humano hereden la arquitectura en lugar de adivinarla.
Para Quién Es
Esto es para el equipo pequeño que no puede permitirse un arquitecto dedicado, pero tampoco puede permitirse la deriva arquitectónica. C4 en el repositorio es la disciplina arquitectónica más económica que realmente sobrevive — porque reside donde reside el código.
Conclusión
La documentación de arquitectura funciona cuando está estructurada, en el repositorio y se hereda del *scaffold*. C4 + invariantes integradas en cada plantilla es la forma más económica de dar a un equipo pequeño la disciplina de uno mucho más grande.
Acerca de FACTA
FACTA ayuda a startups y equipos en fase de crecimiento a convertir la IA en sistemas de producción que sigan funcionando — no en demostraciones que impresionan una sola vez.
Diseñamos la arquitectura en torno a las partes que realmente fallan bajo uso real: herramientas propias, credenciales que usted controla, conmutación por error (*failover*), controles de costos, observabilidad. La infraestructura esencial que mantiene un sistema vivo después del lanzamiento.
Dirigido por Matías Baglieri y Carolina Fogliato, nos enfocamos en una cosa:
Liderazgo en IA que construye. No solo asesora.
Copie una plantilla y obtenga la documentación C4 con ella.
Consulte la publicación sobre invariantes para entender por qué la sección de invariantes es la más importante.
Explore la Automatización de IA