Fan-out de agentes y git worktrees: ediciones en paralelo sin pisarse

El patrón: un padre, muchos hijos con permiso de escritura

Muse Code se apoya en una regla muy simple: cuando un trabajo se puede dividir en varias tareas diferenciadas, esas tareas se reparten automáticamente entre agentes separados. El agente padre lanza un hijo con capacidad de escritura por cada tarea. No hay nada que configurar ni ningún “modo paralelo” que activar: descomponer y repartir es el comportamiento por defecto siempre que el trabajo sea lo bastante grande como para merecerlo.

La pregunta obvia llega enseguida: si varios agentes pueden escribir código a la vez, en el mismo repositorio, ¿por qué no acaba todo en conflictos de merge y archivos machacados?

Una sesión de fan-out real: seis tareas sobre un mismo juego, cuatro ya con merge, dos aún en marcha — cada una en su propio worktree bajo .muse/worktrees/, con el checkout principal intacto.

Worktrees: aislamiento a la manera nativa de git

Cada agente hijo recibe su propio git worktree: un checkout independiente del repositorio que comparte historial con tu copia principal, pero con su propio directorio de trabajo y su propia rama. Dos hijos pueden editar el mismo archivo en sus respectivos worktrees sin ver jamás los cambios a medio hacer del otro. Estructuralmente, la colisión es imposible.

Igual de importante: tu copia de trabajo se mantiene limpia. El directorio que tienes abierto en el editor nunca es el que está mutando un agente. Nada se mueve bajo tu cursor, ningún cambio a medias de un agente aparece en tu diff, y descartar el trabajo de un agente es tan barato como tirar su worktree. Los cambios solo llegan a tu rama cuando el trabajo está terminado y revisado.

¿Por qué no simples ramas? ¿O contenedores?

Las ramas a secas comparten un único directorio de trabajo: cambiar de rama a mitad de tarea le arrancaría la alfombra a un agente en plena ejecución. Contenedores completos o clones del repo funcionarían, pero son pesados: object stores duplicados, arranque lento, merges incómodos. Los worktrees dan en el punto justo. Se crean casi al instante, comparten la base de datos de objetos de git subyacente, y hacer merge de la rama terminada de un hijo es git normal y corriente: sin capa de sincronización propia en la que confiar, sin estado propietario que depurar.

Seis features a la vez, con pruebas

Las demos de lanzamiento exprimieron este mecanismo a fondo: en el ejemplo de desarrollo de juegos, Muse Code construyó seis features del juego simultáneamente, cada agente en su propio worktree, y todas las ramas hicieron merge limpio. Ese es el beneficio práctico: el tiempo de reloj de un sprint multi-feature se comprime hacia la duración de su tarea individual más larga, en vez de ser la suma de todas.

Prueba la receta

El fan-out de agentes es uno de los tres patrones para los que Meta publica recetas en su cookbook: dividir un trabajo grande entre subagentes de forma que nada colisione por el camino. En el cookbook tienes la versión ejecutable. Y como el trabajo repartido en paralelo es justo el tipo de cosa que querrás auditar después, cada spawn, cada llamada a herramienta y cada merge de los hijos queda capturado en el event log: nada ocurre fuera de registro por el hecho de haber ocurrido en paralelo.