Lo scenario è noto a chiunque usi coding agent: un agent lavora da venti minuti su un branch, ha letto il codebase e costruito contesto, poi arriva la richiesta di hotfix su main. Si fa stash, si cambia branch, si perde tutto il contesto accumulato. Se invece due agent girano nella stessa directory, il problema è peggiore: entrambi toccano gli stessi file, il secondo scrive sopra il primo in silenzio, senza warning e senza errore. Il danno si scopre un’ora dopo, con test che falliscono in modo incomprensibile.
Un articolo di KDnuggets propone come soluzione una funzionalità che sta nel core di Git dalla versione 2.5, rilasciata nel 2015: i worktree.
Come funzionano
Un worktree è una directory separata, checkout dello stesso repository. Se ne possono avere quante servono, ognuna sul proprio branch, tutte coesistenti sul filesystem. Condividono la stessa cartella .git, quindi history, oggetti e commit, ma ognuna ha i propri file in checkout, il proprio index e il proprio stato di lavoro. Un agent che modifica file in una non vede e non tocca le altre.
Rispetto a clonare il repo più volte il vantaggio è concreto: si clona una volta sola, e ogni worktree aggiuntivo costa solo i file in checkout, non un’altra copia della history. La superficie da imparare sono sette comandi: add, list, lock, unlock, remove, prune e la variante di add su branch esistente.
Il passo che quasi tutti saltano
Un worktree nuovo è una directory nuova. Non eredita il file .env, non eredita node_modules, non eredita il virtualenv Python. I file gitignorati non compaiono: vanno copiati esplicitamente e le dipendenze vanno installate. È il punto in cui il setup fallisce più spesso, ed è il motivo per cui l’articolo suggerisce di scriptare la creazione invece di farla a mano.
Il secondo pezzo di infrastruttura è un file AGENTS.md committato nel repo, con overview del progetto, comandi di build e test, architettura, convenzioni, zone proibite e — sezione da compilare per ogni worktree — task, branch e criteri di accettazione. L’articolo cita ricerca peer-reviewed presentata a ICSE 2026 secondo cui includere documentazione architetturale nel contesto dell’agent produce guadagni misurabili su correttezza funzionale, conformità architetturale e modularità del codice.
Il caso reale e il rischio a lungo termine
Il caso documentato è quello di Tamir Dresher al Microsoft Global Hackathon 2025: un worktree per feature, una finestra VS Code per worktree, un agent per finestra, e il suo ruolo spostato da sviluppatore a tech lead che assegna, rivede e fa merge.
Il vero rischio non sono i conflitti alla creazione ma il drift: un worktree che gira per giorni senza sincronizzarsi accumula divergenza. La raccomandazione è fare rebase su main alla fine di ogni sessione significativa, non solo prima della PR, e usare --force-with-lease al posto di --force in push.
In sintesi
- Un worktree per task isola ogni agent: stessa
.git, directory e branch separati, nessuna sovrascrittura silenziosa. - File gitignorati e dipendenze non si copiano da soli: va scriptato, altrimenti il setup fallisce lì.
- Il nemico è il drift: rebase su main a ogni checkpoint, push con
--force-with-lease.
Fonte: Git Worktrees for AI Development — https://www.kdnuggets.com/git-worktrees-for-ai-development
Hai qualcosa da aggiungere? Unisciti alla discussione.