Shadow Git Worktrees & Branching

1. Konzeptüberblick und systemisches Problem

Wenn ein Entwickler einen schweren Agenten im aktuellen Projektverzeichnis startet, wird die Arbeit blockiert:

• Dateien in VS Code oder Cursor flackern, der Bildschirm springt, der lokale Next.js-Server lädt sich 20 Mal pro Minute neu.
• Wenn der Agent die TypeScript-Konfiguration bricht, verliert der Entwickler die Autovervollständigung in seinen offenen Tabs.
• Es ist unmöglich, parallel an einer anderen Aufgabe zu arbeiten, solange der Agent seine Sitzung nicht abgeschlossen hat.

Shadow Git Worktrees lösen dieses Problem. Anstatt in Ihrem aktuellen Arbeitsbereich zu arbeiten, erhält der Agent sein eigenes „Schatten-Verzeichnis“ (Worktree) in einem benachbarten Ordner.

2. Architektonische Taxonomie und mentales Modell

┌─────────────────────────────────────────────────────────────┐
│                 SHARED .GIT REPOSITORY CORE                 │
└──────────────┬───────────────────────────────┬──────────────┘
               │                               │
               ▼                               ▼
┌──────────────────────────────┐┌──────────────────────────────┐
│ HUMAN WORKSPACE (main)       ││ AGENT WORKTREE (task/ai-fix) │
│ Path: ~/projects/app         ││ Path: ~/projects/app-agent-1 │
│ • Active Cursor IDE Session  ││ • Headless Agent Execution   │
│ • Local Dev Server on :3000  ││ • Test Runner on :3001       │
│ • Zero Flickering / Chaos    ││ • Builds, lints & verifies   │
└──────────────────────────────┘└──────────────┬───────────────┘
                                               │
                                               ▼ Verified Diff
                                ┌──────────────────────────────┐
                                │ MERGE VIA CLEAN PULL REQUEST │
                                └──────────────────────────────┘

3. Praktische Engineering-Szenarien im Produktionsumfeld

01. Parallele Ausführung langer Migrationen

Ein Ingenieur arbeitet am UI einer neuen Seite im Branch feat/checkout, während ein Hintergrund-Agent im Shadow-Worktree alte Backend-Endpunkte von Express auf Fastify im Branch refactor/api umschreibt. Nach dem Bestehen der Tests führt der Ingenieur einfach einen schnellen git merge durch.

02. Spekulative Bug-Fixes (A/B-Testung von Ansätzen)

Ein Entwickler startet zwei Agenten in zwei verschiedenen Worktrees: Einer löst das Problem durch ein Update der Bibliothek, der andere durch das Schreiben eines eigenen Polyfills. Der Ingenieur vergleicht die Bundle-Größe beider Branches und wählt den besten Ansatz.

4. Fallstricke, typische Fehler und Sicherheit

• Vergessene Worktrees (Disk Clutter): Wenn die Löschung der Arbeitsverzeichnisse nach Abschluss der Task nicht automatisiert wird, können die node_modules-Ordner in Dutzenden von Worktrees schnell den gesamten Festplattenspeicher des Laptops füllen. Verwenden Sie automatische Bereinigungsskripte (git worktree prune).
• Portkonflikte des lokalen Servers: Wenn ein Shadow-Worktree seinen eigenen Testserver startet, könnte er versuchen, denselben Port zu belegen (z. B. :3000). Dem Agenten muss über Umgebungsvariablen der Flag PORT=3001 übergeben werden.

5. Strategisches Fazit für Ingenieure im Jahr 2026

Shadow Worktrees machen die Zusammenarbeit mit KI wirklich asynchron. Der Entwickler ist nicht länger Geisel eines Terminals, der auf die Fertigstellung der Generierung wartet: Der Agent wird zum unsichtbaren Kollegen, der im Nebenraum arbeitet und nur dann an die Tür klopft, wenn ein fertiges, getestetes Ergebnis vorliegt.