Centralizar workspaces de agentes IA: el patrón para escalar en equipo

Hay un momento en la vida de todo equipo que adopta agentes IA en el que la plantilla compartida deja de servir. Lo notás un martes cualquiera: dos personas distintas te muestran versiones diferentes de la misma regla, ambas funcionando, ambas distintas. Nadie se equivocó. La plantilla, simplemente, ya no es la fuente de verdad — es un promedio histórico de lo que algún día fue verdad.

Si tu equipo crea decenas de espacios de trabajo agénticos a la semana sobre múltiples productos, este artículo es para vos. Vamos a recorrer por qué la plantilla duplicada se rompe a escala, qué patrones existentes probamos antes de descartarlos, y el cambio estructural que terminó funcionando: dejar de configurar al agente y empezar a componer al workspace.

La spec técnica completa vive en otro lado, y la enlazamos al final como fuente canónica. Acá contamos la historia.

El día que la plantilla dejó de servir

La plantilla compartida en Drive — o en un repo starter, o en una NAS de la empresa — fue, durante meses, lo más simple que podía funcionar. Y funcionó. Cada nuevo proyecto era una duplicación: copiás la carpeta, le cambiás el nombre, ajustás dos cosas, y ya tenés a tu agente con las convenciones del equipo.

Hasta que el equipo creció. Hasta que los productos se multiplicaron. Hasta que cada nuevo espacio de trabajo fue una copia con derivas pequeñas de una "fuente de verdad" que ya nadie podía señalar con confianza.

A escala, una plantilla duplicada no escala. No es por descuido. Es por geometría. Cada copia recibe ediciones locales que no fluyen de regreso. La consolidación manual compite con shipear features y siempre pierde. Después de seis meses, el "template canónico" está atrás del workspace promedio del equipo, y el equipo lo sabe.

Lo que necesitás no es una mejor plantilla. Es un patrón distinto.

Principio: Una plantilla que se duplica es la fuente de futuras divergencias, no la fuente de verdad.

Las dos grietas que se abren a escala

Cuanto más usa tu equipo agentes IA, más sentís dos dolores que tiran en direcciones opuestas: drift y bloat.

El drift te lo trae el éxito. La gente edita rules, skills y workflows mientras trabaja — porque eso es lo que hace un equipo que aprende. Pero las mejoras se quedan en la copia donde se hicieron. Una semana después, la misma regla existe en cuatro versiones distintas en cuatro workspaces distintos, y ninguna está en la plantilla.

El bloat te lo trae el crecimiento. Para servir a todos los productos, la plantilla acumula reglas, skills y workflows para cada uno. Y cada nuevo workspace inherita todo, aunque solo toque uno. La ventana de contexto del agente se llena de material que no aplica a la tarea de hoy. Sube el costo de tokens, baja la señal-ruido.

Las dos grietas no se resuelven con la misma palanca. "Centralizá todo en la plantilla" empeora el bloat. "Que cada equipo tenga su versión" empeora el drift. Las recetas obvias chocan. Por eso, después de meses de iteración, te das cuenta de que necesitás una solución que ataque ambos al mismo tiempo.

El primer paso es detectar cada dolor explícitamente:

• Drift: ¿hay archivos que aparecen idénticos en varios workspaces pero con ediciones locales que nadie consolidó?
• Bloat: ¿el agente carga capacidades para productos que no toca esta semana?

Si la respuesta es "sí" a uno, el otro va a aparecer pronto. Casi siempre los dos llegan juntos.

Principio: Si optimizás solo por una de las dos grietas, la otra te muerde dos meses después.

Lo que probamos antes (y por qué no encajó)

Antes de llegar al patrón actual, probamos opciones obvias. Ninguna resolvió ambas grietas.

Probamos primero una plantilla compartida más estricta, con review obligatorio antes de duplicar. Eso resolvió el bloat parcialmente — al menos no entraba cualquier cosa — pero el drift creció, porque la fricción de "consolidar luego" se volvió todavía mayor. El review se transformó en un cuello de botella, y los workspaces empezaron a divergir igual.

Después probamos git submodules para los archivos transversales. Cada workspace incluía un submódulo apuntando al repo de "shared agents". Eso resolvió el drift, pero no el bloat — cada workspace seguía cargando todo el shared. Y los submodules, en un equipo con perfiles mixtos de seniority, se volvieron un infierno operativo: actualizar el shared rompía workspaces, los detached HEAD confundían a la gente, y los conflictos al actualizar consumían más tiempo que el que ahorraban.

También buscamos enfoques publicados. El más cercano que encontramos fue una estrategia multi-repo basada en submodules con jerarquía de archivos CLAUDE.md — un repo workspace privado que agrupa varios repos de servicios, con archivos de contexto del agente en jerarquía. Es un patrón sólido cuando tu unidad de trabajo es un solo producto con varios servicios, y un equipo que vive en ese producto. Si esa es tu forma, te recomendamos evaluarlo.

No era nuestra forma. Nosotros tenemos múltiples productos en organizaciones de GitHub distintas, decenas de workspaces efímeros que se crean y se borran en días, y un equipo que rota entre productos según la semana. Una estructura optimizada para "un producto, varios servicios" no resuelve "muchos productos, muchas tareas, muchos workspaces".

Resumen rápido del fit:

• Si tu equipo trabaja sobre un solo producto, varios servicios, con workspaces estables → la estrategia de submodules con jerarquía de CLAUDE.md probablemente te encaja.
• Si tu equipo trabaja sobre múltiples productos, decenas de workspaces a la semana, múltiples GitHub orgs, equipos que rotan → te hace falta otra cosa.

Principio: Adoptar el patrón equivocado para tu shape de equipo cuesta más que no adoptar nada.

El cambio de unidad: el workspace, no el agente

El "ajá" llegó cuando dejamos de pensar en "configurar al agente" y empezamos a pensar en "configurar al workspace".

Es un cambio sutil, pero estructural. Casi todos los frameworks de configuración de agentes IA disponibles hoy tienen la misma forma: un manifiesto define un agente — sus tools, sus skills, su prompt — y ese manifiesto es la fuente de verdad. Funciona si el agente cambia mucho y el contexto cambia poco. Si es al revés — el mismo agente trabajando en muchos contextos distintos — el manifiesto del agente está optimizado para la dimensión equivocada.

En un equipo multi-producto, lo que varía no es el agente. El agente es el mismo. Lo que varía es el slice de contexto organizacional que necesita para esta tarea concreta. Cuando alguien abre un workspace para "fix bug en el módulo de integración del producto A", el contexto relevante es: rules del producto A + convenciones del ecosistema integrado + código del módulo + reglas universales del equipo. Una hora después, esa misma persona abre otro workspace para "borrador de docs del producto B": el contexto relevante es completamente otro. Mismo agente. Mismo modelo. Lo que cambia es el envelope de contexto.

Hacé del workspace la unidad de composición, no del agente. El manifiesto describe el envelope de contexto de la tarea, no la identidad del agente. Esa decisión estructural es la que destraba todo lo demás. Le pusimos nombre al patrón: Agent Workspace as Code (AWaC).

Principio: El agente es constante; el contexto es lo que varía. Componé al nivel de lo que varía.

Cómo se ve un workspace declarativo

Hablar de "componer al nivel del workspace" es abstracto hasta que ves el manifiesto. La parte que sorprende: es un solo archivo. Sin scripts. Sin submodules. Sin setup.sh.

Un workspace se describe con un manifiesto YAML que lista qué stacks de capacidades incluir y qué repos de código clonar. Cada stack vive en su propio repositorio: una fuente de verdad por stack. La carpeta del workspace empieza vacía y una operación de bootstrap la materializa.

Ejemplo generalizado:

name: producto-a-feature-billing
schema: awac/1

stacks:
  - core
  - cloud-platform
  - producto-a
  - ecosistema-integrado

repos:
  - org: producto-a-org
    repo: backend
    path: backend/
  - org: ecosistema-modulos
    repo: producto-a-billing-connector
    path: modules/billing-connector/

Un workspace para investigación o documentación puede ser tan minimalista como esto:

name: spike-investigacion
schema: awac/1
stacks: [core, research]

Cada workspace recibe solo los stacks que declaró. El equipo de Producto B nunca carga rules de Producto A. Bloat resuelto.

Las primeras decisiones a tomar al adoptar este patrón:

• Identificá tu core stack: lo que aplica a todos los workspaces (convenciones de commit, branch policy, reglas de seguridad universales, anti-prompt-injection).
• Identificá tus product stacks: uno por cada producto SaaS que mantenés. Vive en la org de GitHub que es dueña de ese producto.
• Identificá tus technology stacks: ecosistemas con los que integrás frecuentemente (un ERP, un CMS, un cloud provider).

El primer manifiesto de un proyecto nuevo se escribe en menos de un minuto. Si toma más, los stacks están mal segmentados.

Principio: Un workspace es una composición declarada, no un cocktail de duplicados.

El loop que cierra el drift

La composición declarativa resuelve el bloat. ¿Pero el drift?

Acá es donde la mayoría de los enfoques que probamos se rompen. Centralizar las capacidades en repos compartidos es relativamente fácil; lo difícil es que las mejoras locales — esas pequeñas ediciones que la gente hace mientras trabaja, que justifican existir — fluyan de regreso al stack correcto sin fricción y sin gobernanza ad-hoc.

La pieza es una operación llamada promote. Cuando alguien edita una rule en su workspace y quiere compartir la mejora, una sola línea de comando detecta de qué stack viene el archivo, abre un PR contra el repo de ese stack, y queda la mejora en gobernanza humana — review del equipo. Una vez merged, cualquier workspace que use ese stack la recibe en su próximo sync.

Las operaciones del patrón son cinco, definidas conductualmente para que cualquier equipo pueda implementarlas en el lenguaje que prefiera:

• bootstrap: desde un manifiesto vacío, produce el workspace completo. Idempotente.
• sync: re-aplica el manifiesto. Trae lo que avanzó upstream sin sobreescribir cambios locales.
• promote: empuja una mejora local al stack que la origina, vía PR.
• status: reporta drift, divergencias, lo que falta promover.
• worktree: aísla trabajo paralelo de múltiples agentes en el mismo workspace.

El loop completo: edits locales → promote → PR → review → merge → todos los workspaces lo reciben. La gobernanza es humana (el PR es la oportunidad de revisar). El movimiento de información es automático. Drift resuelto.

Principio: Una mejora vale lo que cuesta compartirla. Si cuesta diez minutos, no se comparte. Si cuesta un comando, sí.

Lo que aprendimos en piloto

La especificación describe el estado final. El piloto enseña otra cosa: cómo es la transición.

Si estás pensando adoptar este patrón en tu equipo, las siguientes lecciones te pueden ahorrar varias semanas. Vienen de un piloto activo con múltiples productos en simultáneo y un equipo que rota tareas frecuentemente.

1. Empezá por el core stack, no por los stacks de producto. El core es lo que todos comparten. Migrar primero las rules verdaderamente universales destraba todo lo demás. Migrar primero un stack específico te lleva a discutir bordes y nadie está de acuerdo en qué es "específico".

2. No adelantes stacks que no estás usando esta semana. Crear agent-stack-foo "por si acaso" es deuda. Crealo cuando un proyecto real lo necesita. Los stacks vacíos se vuelven cementerios donde la gente espera que alguien les ponga contenido.

3. Las rules más controvertidas son las que más rápido convergen. Cuando un PR de promote toca una rule que la mitad del equipo escribiría distinto, la conversación técnica se da en el PR — y el equipo gana clarity. Las controversias en Slack se resuelven en el repo. La gobernanza por PR es más fría y más productiva que la gobernanza por meeting.

4. El workspace efímero baja la barrera para experimentos. Cuando crear un workspace nuevo cuesta un minuto y dos comandos, la gente prueba más cosas. Más experimentos = más mejoras detectadas = más PRs de promote. La primera adopción que vimos fue alguien creando un workspace solo para probar una variante de una rule, sin compromiso. Esa cultura aparece sola si el patrón la habilita.

5. El "private overlay" es la válvula de escape correcta para preferencias personales. Cosas que no deben vivir en stacks públicos del equipo — preferencias de modelo, refs a secretos personales, atajos individuales — viven en un overlay privado que cada quien controla. Sin esto, la presión por meter "mi configuración" en stacks compartidos rompe la gobernanza. Con esto, los stacks compartidos se mantienen limpios y cada quien afina su experiencia.

Una secuencia de adopción que vimos funcionar:

• Semana 1: crear el repo core con lo verdaderamente universal. Migrar piloto con un proyecto.
• Semana 2: iterar con feedback real. No agregar stacks aún.
• Semana 3: agregar promote. No antes — necesitás 1-2 semanas de uso para que el equipo entienda qué quiere promover.
• Semana 4 en adelante: migrar stacks de producto a demanda. Cuando arranca un proyecto de Producto X y no existe el stack, se crea ahí.

Principio: El patrón es lo que se publica. La adopción es lo que se aprende.

Checklist para evaluar si te encaja

• ¿Tu equipo crea más de cinco workspaces nuevos por semana para distintos productos?
• ¿Notás versiones derivadas del mismo archivo de rule en distintos workspaces?
• ¿La plantilla acumula capacidades para productos que la mayoría de workspaces no toca?
• ¿Los nuevos integrantes del equipo abren la plantilla y no entienden qué aplica a qué?
• ¿La consolidación de mejoras al "template canónico" la viene postergando alguien hace meses?

Si dijiste sí a más de uno, este patrón te puede servir.

Lo importante es la idea, no la implementación. Cualquier equipo puede adoptar AWaC en el lenguaje y con el tooling que prefiera — bash, Python, Go, Rust. La especificación es lo que se comparte; el código es de cada uno.

Si tu equipo lo prueba, escribí qué funcionó y qué no. La spec deja preguntas abiertas a propósito — sobre granularidad de stacks, sobre conflictos entre capas, sobre versionado — para que la comunidad las cierre con experiencia real.

La especificación canónica completa, con el schema del manifiesto, el orden exacto de composición, todas las operaciones definidas conductualmente y las preguntas abiertas, está publicada acá:

The full canonical specification is published here: Agent Workspace as Code (AWaC) — canonical specification