~/studies/work 2026-11-20 · published 2026-11-21
Un centro, tres satélites
Por qué la forma de trabajar del equipo vive en un repositorio y cada otro harness tiene el suyo, incorporado como submódulo en lugar de contenido copiado.
- harness
- architecture
- git
- submodules
- ~/project/versatile-sh
El problema de una carpeta grande
Nuestra configuración para trabajar con agentes de IA empezó como un montón de instrucciones. Reglas, patrones, registros de proyectos, notas de infraestructura e investigación estaban todos juntos, y cada sesión cargaba lo que tuviera más cerca. Creció hasta que nadie podía decir qué archivo era dueño de qué dato.
El harness del equipo (`versatile-sh/.claude`) mergeó los pull requests #166 a #178 el 2026-11-20, entre ellos el que restringió los repositorios del equipo a conocimiento de Versatile únicamente (#169). Es el día por el que fecho este post. Describe la forma que salió de ahí, no un resultado medido: no tengo números de antes y después, y no voy a inventarlos.
La forma
El centro es `.claude`. Contiene solo cómo trabajamos: el archivo router, las guías de `docs/work/`, skills, agentes, comandos, las herramientas de `bin/` y los hooks. Nunca contiene una regla de ingeniería, un dato de proyecto, un handoff ni un log personal.
Cada otro harness es un satélite con su propio repositorio:
| Repositorio | Contiene |
|---|---|
| versatile-harness | La base de conocimiento de ingeniería (premises, rules, patterns, standards, lints, design) y el hogar de registros de cada proyecto |
| hosting-harness | Infraestructura y la configuración de deploy de cada app |
| research-harness | El engine de investigación: método, estudios, estado |
| <domain>-media | La copia canónica de cada imagen, video y fuente de diseño |
El centro lleva los tres primeros como submódulos git bajo `harness/`. No se copia nada. Una sesión lee `harness/versatile-harness/` igual que cualquier otro archivo, y el contenido es lo que diga el `main` de ese satélite.
Por qué repositorios separados
La premisa está escrita en la base de conocimiento como un archivo corto, y su núcleo es una sola frase: un harness puede reducirse, reemplazarse e iterarse por sí solo, así que nunca se mete inline en el centro ni en otro harness.
- Distintos ritmos de cambio. La base de conocimiento recibe muchos pull requests pequeños al día. La forma de trabajar cambia pocas veces y afecta a todos. Mezclarlos hace que cada revisión trate de dos cosas.
- Distintas audiencias. La configuración de deploy nunca debe viajar con el repositorio de un producto. Tenerla en su propio repositorio convierte esa frontera en una frontera de repositorio en lugar de una convención.
- Reemplazabilidad. Si el engine de investigación resulta equivocado, puede reescribirse sin tocar el resto.
- Una regla para cosas nuevas. Algo parecido a un harness sin repositorio todavía se propone como un nuevo `<name>-harness`. No se pliega en uno existente.
Las reglas que lo mantienen honesto
- La verdad de un satélite es su `main` en GitHub. La carpeta bajo `harness/` es una copia de lectura.
- Nunca se edita bajo `harness/`. Se cambia la copia de trabajo hermana, en una rama, mediante un pull request.
- Lo que una sesión aprende sobre Versatile va a un hogar compartido mediante un pull request, nunca solo a la memoria. Lo que aprende sobre cualquier otro proyecto se queda local, en una carpeta `local/` ignorada.
La segunda y la tercera regla son la razón por la que la separación rinde. Un dato tiene exactamente un hogar, y una búsqueda que cae en el repositorio equivocado no encuentra nada en lugar de una copia obsoleta.
Lo que cuesta
Tres cosas se vuelven más difíciles. Un cambio que abarca el centro y un satélite necesita dos pull requests. Los punteros que registran qué commit de cada satélite lee el centro pueden quedar atrasados. Y una persona tiene que saber qué repositorio es dueño de un tema. La tabla de routing en el archivo router del centro existe para lo último. El siguiente post cubre la herramienta que maneja lo segundo.
Creo que el intercambio es correcto, pero es un juicio tras días de uso por un equipo pequeño, no una medición. Si los pull requests de punteros empiezan a ser ruido, la respuesta será automatizarlos más, no volver a unir los repositorios.