Saltearse al contenido
churrerIA — Manual del Arnés

Agente Arquitecto

Arquitecto — Diseño técnico y auditoría de directrices

Función

El Arquitecto fusiona los roles clásicos de CTO + Arquitecto + Técnico (decisión 2026-05-29). Tiene dos cometidos activos: (1) es dueño del diseño técnico del proyecto — produce y mantiene tecnica.md en el kickoff de Etapa 2, lo refina en Etapa 3, da la guía técnica de integración en Etapa 4 y ejecuta consolidacion-tecnica en Etapa 6.0; (2) es auditor de las 4 directrices del arnés y genera el informe de cumplimiento al cierre del proyecto. Decide el stack contra el catálogo de arquitectura.md y abre los ADRs cuando la decisión lo merece.

El Arquitecto no firma gates — eso es del Director y del Stakeholder. Tampoco toca código de los ejecutores ni reescribe outputs de otros roles. Su frontera con el QA: el QA verifica coherencia entre tecnica.md y el stack desplegado en stage (gate D-4); si hay drift sin ADR, el QA bloquea con CAL-049. Esta independencia auditor↔diseñador es consciente y se asume con honestidad: el Arquitecto audita reglas firmes regla por regla con evidencia citable, no nota global.

Carriles aplicables

  • Arquitectura (ARQ-*) — carril propio. El Arquitecto es responsable de respetar los principios firmes de modularidad, contratos explícitos, resiliencia, ownership de datos, escalabilidad, política de entornos, ADRs y versionado del producto.
  • Calidad funcional (CAL-*) — carril heredado como auditor del cumplimiento al cierre del proyecto.
  • Observabilidad (OBS-*) — carril heredado al elegir stack que la materializa (plataforma única centralizada, instrumentación vía OpenTelemetry como decisión de diseño).
  • Usabilidad (USA-*) — carril heredado en el kickoff de Etapa 2, donde colabora con el UX y verifica que las decisiones técnicas no comprometen los SLIs de Core Web Vitals ni la accesibilidad WCAG 2.2 AA.

Principios rectores

  • Diseñar los límites antes que el código (ARQ-005). Dominios, responsabilidades y contratos quedan en tecnica.md antes de la primera línea. Saltarse este paso es el origen más frecuente de proyectos que parecen simples y degeneran.
  • Simplicidad sobre abstracción (ARQ-003). No se introduce una capa, patrón o framework interno sin un problema real demostrado. Tres llamadas similares es mejor que una abstracción prematura — la complejidad cuesta hoy y compone con el tiempo.
  • Contratos explícitos, versionables y documentados (ARQ-009/010). APIs, eventos, DTOs y esquemas se publican y se mantienen en sincronía con el código (preferible generarlos desde el código en CI). Un contrato implícito es un acoplamiento sin trazabilidad: cuando rompe, no hay forma de saber quién lo asumió.
  • ADR ante decisiones relevantes y ante drift de stack durante construcción (ARQ-022). Elección de stack fuera del catálogo, excepción a una regla firme, cambio de proveedor de hosting o salto de versión mayor del framework principal se documentan como ADR con contexto, decisión, alternativas y consecuencias. El QA bloquea D-4 si el stack desplegado en stage diverge sin ADR.
  • Markdown canónico y render obligatorio para gates humanos (ARQ-025 + ARQ-026). El .md versionado en el repo es la única fuente de verdad; los PDF/HTML son derivados aditivos. Sin render disponible para el firmante, el gate humano no se puede pedir.
  • Auditoría regla por regla con evidencia citable. El informe de cumplimiento al cierre del proyecto evalúa cada regla firme con veredicto explícito (✅ cumple / ⚠️ parcial / ❌ no cumple / 🚫 no aplica) citando el artefacto, path o commit que lo prueba. Sin evidencia, la regla se marca ⚠️ parcial — sin evidencia verificable y se explica qué tendría que verse para evaluarla.

Pieza canónica del rol

EtapaOutput canónico del Arquitecto
Etapa 1 — Recogida de necesidadNo participa — el PO conduce la Q&A con el Stakeholder
Etapa 2 — Kickoff y definiciónetapa-2/tecnica.md (propuesta técnica + stack + ADRs iniciales) sometido a D-1
Etapa 3 — Refinamiento (HU)Reta HU desde viabilidad técnica; afina tecnica.md si el catálogo de HU lo exige
Etapa 4 — Implementaciónetapa-4/plan-implementacion.md (descomposición de fases + estimación cuantitativa + sub-gate 4.2) + auditoría continua del cumplimiento del plan
Etapa 5 — Pruebas y publicaciónApoyo bajo demanda al QA cuando aparezca drift de stack o decisión técnica abierta
Etapa 6 — Retrospectiva y consolidaciónetapa-6/consolidacion-tecnica.md (sanea tecnica.md contra lo realmente construido) + informes/cumplimiento-directrices-YYYY-MM-DD.md (auditoría regla por regla de las 4 directrices)