Agent fan-out e git worktree: modifiche in parallelo senza collisioni

Il pattern: un parent, tanti figli con permesso di scrittura

Muse Code si regge su una regola semplice: quando un lavoro si scompone in più task distinti, quei task vengono distribuiti automaticamente a più agent. L’agent parent lancia un figlio con permesso di scrittura per ogni task. Non c’è niente da configurare, nessuna “modalità parallela” da attivare: scomposizione e smistamento sono il comportamento di default ogni volta che il lavoro è abbastanza grande da giustificarlo.

La domanda sorge spontanea: se più agent possono scrivere codice contemporaneamente, nello stesso repository, perché non finisce tutto in un disastro di conflitti di merge e file sovrascritti?

Una sessione di fan-out reale: sei task su un unico gioco, quattro già in merge, due ancora in corso — ognuno nel proprio worktree sotto .muse/worktrees/, con il checkout principale intatto.

Worktree: l’isolamento alla maniera di git

Ogni agent figlio riceve il proprio git worktree: un checkout separato del repository che condivide la cronologia con la tua copia principale, ma ha una working directory e un branch tutti suoi. Due figli possono modificare lo stesso file nei rispettivi worktree senza mai vedere le modifiche dell’altro a metà lavoro. Strutturalmente, la collisione non può proprio avvenire.

Altrettanto importante: la tua copia di lavoro resta pulita. La directory che hai aperta nell’editor non è mai quella su cui un agent sta lavorando. Niente si muove sotto il tuo cursore, nessuna modifica a metà di un agent compare nel tuo diff, e abbandonare il lavoro di un agent costa quanto buttare via il suo worktree. Le modifiche arrivano sul tuo branch solo quando il lavoro è finito e revisionato.

Perché non semplici branch? O container?

I branch normali condividono un’unica working directory: cambiare branch a metà task strapperebbe il tappeto da sotto i piedi a un agent in esecuzione. Container completi o cloni del repo funzionerebbero, ma sono pesanti: object store duplicati, setup lento, merge macchinosi. I worktree centrano il punto di equilibrio: si creano quasi istantaneamente, condividono il database degli oggetti git sottostante, e riportare indietro il branch finito di un figlio è git ordinario — nessun layer di sincronizzazione custom di cui fidarsi, nessuno stato proprietario da debuggare.

Sei feature in contemporanea, coi fatti

Le demo di lancio hanno spremuto a fondo questo meccanismo: nell’esempio di sviluppo di un videogioco, Muse Code ha costruito sei feature del gioco in parallelo, ogni agent nel proprio worktree, e ogni branch è andato in merge pulito. Il vantaggio pratico è tutto qui: il tempo reale di uno sprint multi-feature crolla verso la durata del singolo task più lungo, invece che verso la somma di tutti.

Prova la ricetta

L’agent fan-out è uno dei tre pattern per cui Meta pubblica ricette nel cookbook: spezzare un lavoro grande tra più subagent in modo che niente collida a metà strada. Nel cookbook trovi la versione eseguibile. E dato che il lavoro distribuito in fan-out è esattamente il tipo di cosa che vorrai controllare a posteriori, ogni spawn, ogni chiamata a tool e ogni merge dei figli finisce nell’event log: niente succede fuori registro solo perché è successo in parallelo.