tesis de apertura
Es adoptar IA sobre una arquitectura que no tolera aceleración.
El daño no aparece en el primer sprint. Aparece tres trimestres después, cuando ya no se puede revertir sin reescribir.
throughput de código × arquitectura
Cada feature compone con la anterior. El sistema soporta más velocidad sin perder coherencia.
El equipo entrega más rápido, pero cada release agrega más fricción a la siguiente.
La velocidad supera la capacidad de razonar el sistema. Los incidentes ya no tienen dueño.
No hay una cuarta. La elección la hace tu arquitectura, no tu IA.
qué evalúa este workshop
Lo que medimos no es qué stack usas, sino si la topología de tu sistema es coherente con el nivel de aceleración que la IA va a producir sobre él. Cada concepto del workshop tiene su ejercicio sobre el repo real del equipo.
Día 01: 12 ejercicios de diagnóstico con Cowork. Día 02: 4 ejercicios maestros de implementación con Code.
Mañana: cinco topologías que pueden absorber IA. Tarde: los 12 modos de degradación que la IA introduce, cada uno con un ejercicio de diagnóstico sobre tu repo. Herramienta principal: Claude Cowork para explorar; Claude Code donde haya que correr análisis.
El mapa de arquitecturas que pueden absorber IA sin colapsar. La elección no es de gusto: cada topología tolera un perfil de complejidad y autonomía distinto.
cinco topologías · cinco contextos
Producto temprano o mediano con dominio cohesivo. Boundaries explícitos, despliegue único.
Necesidad de desacoplamiento y múltiples integraciones. Dominio aislado, adaptadores intercambiables.
Procesos asincrónicos y workflows complejos. Comunicación por eventos, acoplamiento temporal.
Workflow-native: IA opera tareas semiautónomas con tools, memoria y pasos verificables.
Escala organizacional y dominios altamente separados. Costo operativo alto, autonomía alta.
verdad incómoda
Los microservicios resuelven un problema organizacional de coordinación entre equipos. No resuelven un problema técnico de complejidad. Y traen consigo costos operativos que la IA no compensa: observabilidad distribuida, contratos, versionado, idempotencia, eventual consistency.
recomendación operativa
Ningún equipo cae en uno solo. Caen en cuatro o cinco al mismo tiempo, y los efectos se componen. Reconocerlos es prerrequisito para mitigarlos.
mapa completo
problema 01 · architecture drift
Cada prompt agrega decisiones locales razonables. Pero nadie está defendiendo invariantes, boundaries, patrones, contratos, ni la semántica global del sistema.
ejercicio 01 · architecture drift
Detectar dónde se degradó la arquitectura desde el último commit "estable" y producir un reporte priorizado de remediación.
Compara el repo en HEAD contra commit <SHA>. Identifica drift respecto a: · /ai-system/architecture/boundaries.md · /ai-system/architecture/anti-patterns.md · /ai-system/architecture/adr/*.md Para cada violación reporta: archivo:línea regla violada severidad (alta/media/baja) remediación mínima viable Ordena por severidad descendente. No propongas refactors masivos.
problema 02 · context collapse
La IA solo ve lo que cabe en su ventana. El sistema completo no cabe. A medida que el proyecto crece, la IA pierde comprensión histórica, olvida decisiones y contradice implementaciones previas.
"La IA reimplementa algo que ya existe en otro módulo."
No tiene memoria persistente del sistema. Cada sesión empieza ciega.
ejercicio 02 · context collapse
Probar el efecto de un contexto curado vs vacío. Comparar respuestas de Cowork sobre la misma pregunta con y sin Memory Pack mínimo.
[Adjuntar architecture.md + boundaries.md] Eres asistente arquitectónico de este repo. Antes de responder, lista: 1. Qué módulos existen y sus responsabilidades 2. Qué boundaries no se pueden cruzar 3. Qué decisiones (ADR) están vigentes Luego responde: "¿Dónde y cómo agregaría una nueva capacidad de notificaciones sin violar los boundaries actuales?" Si falta evidencia, di "sin evidencia".
problema 03 · complexity inflation
El modelo está entrenado con código de proyectos grandes. Por defecto produce abstracciones de proyectos grandes — incluso para problemas chicos.
Sin un presupuesto de complejidad explícito, la IA siempre elige la versión más sofisticada de la solución.
ejercicio 03 · complexity inflation
Establecer un presupuesto de complejidad explícito y detectar abstracciones innecesarias añadidas por la IA en los últimos sprints.
Lee el módulo <ruta> y lista: 1. Interfaces con 1 sola implementación 2. Factories que solo se llaman en 1 sitio 3. Wrappers que reexportan sin agregar valor 4. Genéricos <T> con 1 sola instanciación 5. Capas de adaptador sin cambio de tipo Para cada uno, propón: - inlinizar - eliminar - mantener (justifica con >1 razón) No reescribas el código. Solo el inventario.
problema 04 · memory leaks técnicos y cognitivos
Los segundos son peores. Los técnicos se diagnostican; los cognitivos se descubren cuando ya hubo un incidente.
ejercicio 04 · memory leaks técnicos y cognitivos
Producir dos listas: leaks técnicos potenciales y leaks cognitivos (subsistemas sin dueño claro). Ambas alimentan el siguiente sprint.
Realiza dos auditorías en este repo:
A. Técnica:
· addEventListener sin removeEventListener
· setInterval / setTimeout sin clear
· subscribe sin unsubscribe
· Map / Set globales que solo crecen
· sockets / streams sin close
B. Cognitiva:
· módulos sin entrada en CODEOWNERS
· módulos modificados por IA en últimos
30 días sin revisión humana registrada
Output: dos tablas markdown.
Ruta · línea · síntoma.
problema 05 · false sense of velocity
Las dashboards muestran más PRs, más líneas, más features. El sistema parece más rápido. Pero la velocidad de salida no es la misma cosa que la velocidad de aprendizaje del producto.
PRs por semana
tiempo medio para resolver incidentes en producción
// patrón observado en equipos sin gobernanza
ejercicio 05 · false sense of velocity
Identificar qué métricas actuales son vanity (PRs, líneas, features) y reemplazarlas por métricas sostenibles (lead-time, time-to-restore, change-fail-rate).
Te paso las métricas que reportamos hoy: · PRs/semana · líneas modificadas · features cerradas · % cobertura · velocidad story points Para cada una clasifica: - vanity (mide actividad, no valor) - saludable (mide capacidad) - mixta (depende del uso) Propón 5 métricas que reemplacen las vanity, alineadas a DORA + lead-to-incident. Para cada una: definición, fuente de datos, frecuencia, dueño.
problema 06 · semantic inconsistency
El modelo no sabe qué significa "transferencia", "liquidación" o "cliente" en tu sistema. Sabe qué palabras suelen acompañarlas en código que ha visto antes.
Cuando tu dominio tiene términos cargados — regulatorios, contractuales, de riesgo — la IA produce código que parece correcto pero contradice tu modelo.
ejercicio 06 · semantic inconsistency
Producir domain-glossary.md con cada término del negocio que aparece en el código, su definición canónica y los aliases que se deben corregir.
Lista los 30 términos de dominio más
frecuentes en el código (clases, tipos,
nombres de variables, comentarios).
Para cada término:
· forma canónica
· aliases detectados (Cliente / User /
Account / Customer)
· ubicaciones (rutas representativas)
· ¿estado, evento, agregado, valor?
Marca los términos con >1 alias como
"normalizar". No renombres aún.
problema 07 · hidden coupling explosion
Un campo agregado en un servicio. Un nuevo evento publicado. Un retry implícito. Tres semanas después, otro módulo depende silenciosamente de cualquiera de ellos. El acoplamiento ya está, pero no en el código que la IA mostró.
ejercicio 07 · hidden coupling explosion
Generar el grafo real de dependencias entre módulos y detectar acoplamientos no documentados, ciclos y violaciones a boundaries esperados.
Genera el grafo de dependencias de este repo con dependency-cruiser. Luego: 1. Lista los ciclos (orden topológico fallido) 2. Imports de domain/* → infra/* 3. Imports cross-feature 4. Side-effect coupling: módulos que se rompen si NO se importa otro antes (revisa side-effects en index) Output: tabla por categoría + recomendación de boundary a codificar.
problema 08 · testing theater
La IA es muy buena escribiendo tests que pasan. Eso no es un cumplido.
Tests escritos contra la implementación que la IA acaba de escribir verifican que el código hace lo que el código dice — no que el sistema hace lo que el dominio requiere.
expect(svc.calc()).toBe( svc.calc() ) // pasa siempre
given: cuenta saldo 100
when: retiro 150
then: rechazado
y saldo == 100
ejercicio 08 · testing theater
Convertir tests tautológicos generados por la IA en tests given-when-then contra reglas de dominio. Romperlos a propósito para validar señal.
Toma estos tests y reescríbelos como
tests de comportamiento de dominio:
<rutas>
Reglas:
· No mockear el código bajo prueba
· Solo mockear infra (DB, HTTP, time)
· Estructura given-when-then explícita
· El nombre del test es la regla
de negocio, no la función
Después, modifica el dominio para violar
la regla. El test DEBE fallar. Si pasa,
el test sigue siendo teatro.
problema 09 · operational fragility
El modelo optimiza por código que compila y pasa los tests. Eso es la mitad inferior del ciclo de vida.
Logs sin estructura, métricas ausentes, traces que no atraviesan boundaries.
Consumidores sin límite. Productores que no respetan colas saturadas.
Reintentos sin backoff, sin idempotencia, sin circuit breakers.
Estado compartido sin locks, lecturas-modificaciones-escrituras no atómicas.
ejercicio 09 · operational fragility
Aplicar la mitad operativa que la IA ignora: observabilidad, backpressure, retries, race conditions. Cerrar el ciclo con un PR de instrumentación.
Audita el servicio <ruta> contra este
checklist de readiness:
[ ] Logs estructurados con trace_id
[ ] Métricas: latencia p50/p95/p99,
error rate, throughput
[ ] Retries con exponential backoff
[ ] Idempotencia donde reintenta
[ ] Circuit breaker en dependencias
[ ] Backpressure en consumers
[ ] Locks o atómicos en estado compartido
Lista gaps con severidad y propón
el PR mínimo viable que los cierra.
problema 10 · prompt-driven architecture
Cuando cada feature se construye prompteando, la arquitectura es la suma agregada de las decisiones puntuales que la IA tomó esa semana — no una decisión consciente del equipo.
El resultado: un sistema cuyo diseño nadie eligió, pero todos heredan.
ejercicio 10 · prompt-driven architecture
Probar la diferencia entre un prompt vago y uno contractual sobre el mismo refactor. Comparar PRs lado a lado: drift introducido, archivos tocados, tests rotos.
Refactoriza módulo orders/ siguiendo: · Mantener la API pública intacta (verificable: contract tests) · No modificar archivos fuera del módulo · No introducir nuevas librerías · Reducir complejidad ciclomática máxima de cada función a <= 10 · Cobertura de comportamiento >= 85% · Si encuentras un acoplamiento hacia infra dentro del dominio, detente y reporta. No lo arregles.
problema 11 · local optimization trap
La IA mejora componentes individuales muy bien. El componente queda más rápido, más limpio, más legible. La interacción entre componentes — la única superficie donde fallan los sistemas serios — queda fuera de su vista.
// el módulo correcto, en el sistema equivocado
ejercicio 11 · local optimization trap
Trazar un flujo end-to-end (request → respuesta o evento → side-effect) y detectar dónde una optimización local degrada el throughput global.
Traza el flujo end-to-end "<nombre>":
1. Lista los pasos en orden
(módulo · operación · IO esperado)
2. Para cada paso, latencia p95 conocida
3. Marca pasos modificados en últimos
60 días (commit hash + autor)
4. Identifica el cuello real
("el flujo NO se acelera si optimizo X")
Output: diagrama de cajas + tabla de
métricas por paso + recomendación
end-to-end.
problema 12 · skill atrophy
Si la IA depura, modela, perfila y diseña por nosotros, el músculo se atrofia. La paradoja: cuando la IA falla — y va a fallar — el equipo ya no tiene la capacidad para tomar el relevo.
ejercicio 12 · skill atrophy
Forzar al equipo a razonar sobre el sistema sin asistencia. Detectar qué músculos se atrofiaron y cuáles se mantienen. Cerrar con una retro estructurada.
Te paso las notas de la sesión sin-IA (adjuntas). Identifica: 1. Conceptos que el equipo no pudo reconstruir sin abrir el código 2. Decisiones que solo conoce 1 persona 3. Áreas donde la IA es load-bearing (sin ella, el equipo se detiene) Propón 3 prácticas concretas para recuperar capacidad de razonar: · pair sin IA · architecture katas · code reading sessions Una recomendación por mes, no más.
Mañana: una estrategia por cada dolor del Día 01, con sus 4 ejercicios maestros. Tarde: cómo se implementa la gobernanza en el repo (AI OS, prompts contractuales, fitness functions, pipeline, observabilidad) y stack recomendado. Herramienta principal: Claude Code en repo abierto.
No hay una bala de plata. Hay doce intervenciones específicas, cada una atacando un modo de degradación distinto. Implementarlas no es opcional si quieres compounding en lugar de colapso.
tabla maestra · 12 dolores · 12 estrategias · 1/2
| # | Dolor | Estrategia | Artefacto / Práctica |
|---|---|---|---|
| 01 | Architecture drift | ADRs + fitness functions | /architecture/adr/*.md |
| 02 | Context collapse | Architecture Memory Pack | /ai-system/architecture/* |
| 03 | Complexity inflation | Presupuesto de complejidad | checklist + revisión PR |
| 04 | Memory leaks | Profiling + ownership explícito | CODEOWNERS + runbook |
| 05 | False velocity | Métricas sostenibles | DORA + lead-to-incident |
| 06 | Semantic inconsistency | Lenguaje ubicuo | domain-glossary.md |
tabla maestra · 12 dolores · 12 estrategias · 2/2
| # | Dolor | Estrategia | Artefacto / Práctica |
|---|---|---|---|
| 07 | Hidden coupling | Boundaries verificables | dependency-cruiser |
| 08 | Testing theater | Tests por comportamiento | contract + scenario tests |
| 09 | Operational fragility | Observabilidad first | OpenTelemetry + SLOs |
| 10 | Prompt-driven arch. | Prompting contractual | /prompts/*.md plantillas |
| 11 | Local optimization | Revisión end-to-end | flow tests + smoke |
| 12 | Skill atrophy | Human-in-the-loop | code review obligatorio |
ejercicio 13 · mapeo de dolores
Mapear cada uno de los 12 modos de degradación a evidencia concreta del repo del equipo, y elegir 3 dolores prioritarios para el siguiente sprint.
Para cada uno de los 12 dolores del Vibe Coding, busca en este repo señales: 01 drift · 02 context collapse · 03 complexity inflation · 04 memory leaks · 05 false velocity · 06 semantic inconsistency · 07 hidden coupling · 08 testing theater · 09 operational fragility · 10 prompt-driven · 11 local optimization · 12 skill atrophy Output por dolor: · evidencia (ruta · ejemplo · métrica) · severidad (alta/media/baja) · coste estimado de remediación Si no hay evidencia, di "no detectado".
contra architecture drift
Documento corto, versionado en el repo, que captura una decisión arquitectónica: contexto, decisión, consecuencias.
Test automatizado que verifica una propiedad de la arquitectura — no del feature. Falla el build si alguien la viola, incluso si es la IA.
ejercicio 14 · ADRs + fitness functions
Convertir tres reglas tácitas que viven solo en la cabeza del equipo en tests automatizados que fallan el build cuando se violan, con ADR adjunto.
Necesito codificar 3 boundaries como reglas de dependency-cruiser: 1. domain/* no puede importar de infra/* 2. features/auth no puede importar de features/billing 3. shared/* no puede importar de features/* Genera el archivo .dependency-cruiser.cjs completo, con severidad "error" y un mensaje claro por regla. Luego corre la herramienta y reporta cualquier violación encontrada. Por último, redacta ADR-NN.md con contexto, decisión y consecuencias.
contra context collapse
El Architecture Memory Pack es un conjunto de documentos vivos que la IA carga al inicio de cada sesión. Es la "memoria a largo plazo" que el modelo no tiene por sí solo.
Topología, capas, estilos de comunicación, decisiones globales.
Qué módulo puede hablar con qué módulo, y bajo qué contrato.
Lenguaje ubicuo: cada término del negocio con su definición canónica.
Patrones específicamente prohibidos en este repo, con razones.
Decisiones tomadas y vigentes — la historia del porqué.
Convenciones que la IA debe respetar en cada PR.
ejercicio 15 · architecture memory pack
Producir /ai-system/architecture/* a partir del repo, no en blanco. La IA propone, los humanos aprueban línea por línea.
Lee el repositorio completo. Genera: 1. architecture.md — topología actual, capas detectadas, estilos de comunicación. Marca con [?] cualquier inconsistencia. 2. boundaries.md — qué módulo importa de qué. Marca acoplamientos sospechosos. 3. domain-glossary.md — términos del dominio que aparecen en código, con conteo y ubicaciones. No inventes. Si no hay evidencia, di "sin evidencia en el repo".
contra hidden coupling explosion
Una regla escrita en un documento la IA puede ignorar sin que nadie lo note. Una regla codificada como test la IA no puede violar sin romper el build.
Toda decisión arquitectónica importante debería venir con un test que la verifica.
ejercicio 16 · boundaries verificables
Pasar las capas implícitas (domain, application, infra, ui) a configuración verificable en cada PR. Ningún boundary que no se ejecute en CI cuenta.
Configura eslint-plugin-boundaries con estas capas y reglas: · domain → puede importar: domain · application → domain, application · infra → domain, application, infra · ui → application, ui Reglas adicionales: · features/* aisladas entre sí · shared/* nunca importa de features/* · tests pueden romper reglas, marcado Genera .eslintrc, mensaje por regla y un script npm run boundaries:check.
La gobernanza no es una política en Confluence. Es un conjunto de archivos, prompts, fitness functions y pasos de pipeline que viven en el mismo repositorio que el código.
ai operating system del repositorio
Cada archivo es un contrato. La IA los lee al inicio de cada sesión, los humanos los actualizan cuando cambian de opinión, el pipeline los verifica.
prompt engineering estructural
Implementa autenticación JWT.
La IA elegirá librería, ubicación, estilo, contratos. Cada uno de esos puede contradecir tu sistema.
Implementa autenticación JWT siguiendo: · Arquitectura hexagonal · Sin acceso directo a infra desde dominio · Reutilizar AuthPort existente · Compatibilidad con refresh tokens actuales · No modificar módulos billing/* · Cobertura mínima 85% · Generar contract tests · Logs estructurados obligatorios
Plantillas de prompt viven en /ai-system/prompts/. La IA siempre opera con uno cargado.
architecture fitness functions
Un test unitario verifica un comportamiento. Una fitness function verifica una propiedad estructural del sistema: capas, dependencias, ciclos, complejidad ciclomática, peso de bundle.
Si la IA introduce un import desde dominio hacia infraestructura, el build falla. Punto.
pipeline de pre-merge
El paso 09 es el único negociable solo en una dirección: nunca lo saques. Si lo sacas, todo lo anterior se reduce a un sello automático sin dueño.
observabilidad first
La selección no es ideológica. Cada herramienta cubre una capa específica del sistema operativo de gobernanza que acabamos de describir.
stack recomendado por capa
insight final
No es un problema de productividad. No es un problema de herramienta. Es un problema de cómo se decide en un equipo cuando una parte del equipo es un modelo que nunca duerme y nunca recuerda.
El equipo que gane no será el que genere más código.Vibe Coding & Gobernanza · Workshop Credicorp
Será el que mejor controle complejidad, coherencia, memoria, boundaries y degradación sistémica.
compromisos post-workshop · 30 días
Ejercicio 15. Un PR con /ai-system/architecture/* committeado, revisado y aprobado.
Ejercicios 14 y 16. Tres fitness functions y la config de eslint-plugin-boundaries fallando el build cuando se violan.
Ejercicio 01. Reporte de drift sobre los últimos 90 días, con tres remediaciones priorizadas y un cron mensual.
Revisión a 30 días: los tres entregables corriendo en CI, el equipo demostrando uno de los ejercicios del Día 01 sin asistencia.