DEV Community

Andrea Schiona
Andrea Schiona

Posted on

Agenti di coding in parallelo senza conflitti: Git Worktrees

#ai #agents #git #programmazione

TL;DR: se usi Claude Code, Codex o agenti di coding simili, un singolo checkout condiviso è un disastro quando lanci più agenti in parallelo. git worktree crea cartelle di lavoro separate, ognuna sul proprio branch, condividendo lo stesso repository: zero conflitti, zero push/pull inutili, merge diretto in integrazione.

Il problema: agenti che si pestano i piedi

Due agenti sullo stesso repo, stessa cartella, stesso branch:

  • scrivono gli stessi file
  • sovrascrivono modifiche
  • nessun isolamento di contesto

Risultato: caos, anche se ogni agente “funziona” bene da solo.

La soluzione: una worktree per agente 

git worktree add ../feature-login -b feature/login main
git worktree add ../feature-payments -b feature/payments main
git worktree add ../integration -b integration main
Enter fullscreen mode Exit fullscreen mode

Struttura risultante:

project/
├── main/               → branch main
├── integration/        → branch integration
├── feature-login/      → branch feature/login
└── feature-payments/   → branch feature/payments
Enter fullscreen mode Exit fullscreen mode

Ogni agente ha:

  • la propria cartella
  • il proprio branch
  • lo stesso repository condiviso

Nessun conflitto di file, nessun conflitto di working directory.

Il dettaglio che sorprende: niente push, niente pull

Le worktree sono sullo stesso repo locale. Quindi l’integrazione può fare direttamente:

cd ../integration
git merge feature/login
git merge feature/payments
npm test
Enter fullscreen mode Exit fullscreen mode

Git conosce già tutti i branch locali. Push e pull servono solo quando entra l’uomo:

  • PR, review, CI, audit trail
  • Piano locale agenti → piano remoto esseri umani

Cleanup corretto 

git worktree remove ../feature-login
git branch -d feature/login
Enter fullscreen mode Exit fullscreen mode

git worktree remove pulisce anche il registro interno. Se hai già cancellato la cartella a mano: git worktree prune.

Ciclo completo per un task:

git worktree add ../feature-login -b feature/login main
cd ../feature-login && git add . && git commit -m "feat: login"
cd ../integration && git merge feature/login && npm test
git worktree remove ../feature-login
git branch -d feature/login
Enter fullscreen mode Exit fullscreen mode

Runtime condiviso: il problema dei port

Le worktree isolano file e branch, non i processi. Due agenti che fanno npm run dev o eseguono test si contendono :3000, database di test locali e RAM per i browser headless.

Workaround semplice: ogni worktree ha il suo .env.local con porta dedicata:

echo "PORT=3101" > ../feature-login/.env.local
echo "PORT=3102" > ../feature-payments/.env.local
Enter fullscreen mode Exit fullscreen mode

Per database di test condivisi, suite E2E concorrenti e isolamento reale serve un passo ulteriore — forse contenitori o worktree su macchine separate.

Nota critica: lo stash è condiviso

⚠️ refs/stash è unico nel repo condiviso. Se un agente fa stash in una worktree, l’altra worktree lo vede e può applicarlo nel posto sbagliato.

Regola: mai usare stash con agenti paralleli. Usare solo commit sul proprio branch.

Cosa dice l'ecosistema nel 2026

Questo pattern non è più un trucco per power-user. Team e strumenti di produzione lo hanno adottato come default.

Worktree-per-task vs worktree-per-agent
La scelta consigliata è worktree-per-task: ogni task ha il proprio branch e la propria worktree, e gli agenti vengono assegnati alle worktree invece di possederle permanentemente. Così si evita stato stale e si mantiene la riutilizzabilità.

Supporto nativo

  • Claude Code supporta --worktree / -w per avviare una sessione isolata, oltre all’isolamento dei subagent in worktree separate.
  • Codex CLI non ha una flag nativa --worktree; il pattern comune è git worktree add manuale seguito da codex --cd ../path.
  • Cursor ha aggiunto supporto first-class alle worktree nella release 2026.1.

Strumenti di orchestrazione
Tool come Intent, AQ, Atlas, Nimbalyst e l’orchestrazione cloud di Warp automatizzano creazione, assegnazione, review e cleanup delle worktree. Trattano la worktree come unità di isolamento e costruiscono sopra scheduling, review dei diff e gate di merge.

Previsione di conflitti
Tool come Clash prevedono merge conflict prima che avvengano, monitorando quali file vengono toccati da worktree parallele.

Cinque failure mode da progettare

  1. Port e servizi in conflitto — gli agenti competono per lo stesso dev server, database o cache. Fix: .env.local esplicita per worktree.
  2. Stato esterno condiviso — database, Docker volumes e code sono ancora condivisi. Fix: database o container separati per worktree.
  3. Confini di task laschi — due agenti toccano lo stesso modulo e generano un conflitto imprevisto. Fix: ownership esplicita dei file prima di avviare.
  4. Stato non committato invisibile — le modifiche in corso di un agente non sono visibili all’altro finché non vengono committate. Fix: WIP commit per handoff.
  5. La review diventa il collo di bottiglia — creare molti agenti è economico, leggere molte diff no. Fix: task scope stretto, merge sequenziale e un combined test pass finale.

Workflow pratico

  1. Mappa i confini. Decidi quali file può toccare ogni agente.
  2. Crea una worktree per task. Branch da base pulita; evita di forzare lo stesso branch due volte.
  3. Bootstrap. Installa dipendenze, copia env, assegna port.
  4. Esegui con prompt scoping. Indica ownership boundary e criteri di successo.
  5. Merge sequenziale. Un branch alla volta, con test tra i merge.
  6. Cleanup. git worktree remove e cancella il branch dopo il merge.

Dove si inserisce in contesto enterprise

Non è solo un trucco per sviluppatori singoli. In ambito enterprise, l’isolamento per worktree mappa direttamente su:

  • Value stream Requirement-to-Deploy: ogni worktree è un cambiamento controllato in corso, pronto per approval workflow.
  • Change control: i commit sono tracciabili, reversibili e legati a task branch specifici.
  • Integration gating: la worktree di integrazione è il singolo punto di merge con testing obbligatorio.
  • Governance dei costi: l’esecuzione parallela riduce il wall-clock time, ma solo se i confini di task sono abbastanza stretti da evitare rework.

Il pattern è diventato talmente standard che nel 2026 guide di Augment Code, MindStudio, Warp e numerosi practitioner indipendenti lo descrivono come baseline per il multi-agent coding, non come tecnica avanzata.

Link

📄 Articolo originale: https://dev.to/servatj/running-coding-agents-in-parallel-with-git-worktrees-507i

Top comments (0)