Schatten-Arbeitsbereich & Git Worktrees

1. Konzeptüberblick und systemisches Problem

Sobald ein autonomer Agent beginnt, die Codebasis im aktiven Entwicklerverzeichnis zu modifizieren, entsteht eine kritische Blockade (Workflow Lockout). Wenn der Agent 25 Dateien bearbeitet, den Code kompiliert, Pakete installiert und Tests ausführt, kann der Mensch nicht parallel Code schreiben, seinen lokalen Dev-Server prüfen oder Branches wechseln: Uncommitted Changes des Entwicklers und des Agents vermischen sich unweigerlich und verursachen Konflikte.

Darüber hinaus: Scheitert der Agent, hängt er fest oder halluziniert, kann das Zurücksetzen des Working Trees (git checkout -f oder git clean) versehentlich die ungesicherte Arbeit des Ingenieurs löschen.

Der Shadow Workspace (Schatten-Arbeitsbereich) auf Basis von Git Worktrees löst dieses Problem endgültig. Der Agent erhält ein vollständig isoliertes Verzeichnis auf der Festplatte, das an einen eigenen Branch gebunden ist. Der Ingenieur schreibt weiterhin in seinem bevorzugten Editor Code, während der Hintergrund-Agent parallel komplexe Refactorings in der Schatten-Umgebung durchführt – ohne jegliche Auswirkung auf die aktive Arbeitsstation.

2. Architektonische Taxonomie und mentales Modell

Die Architektur der Interaktion mit Shadow Workspaces basiert auf der Trennung der Disks und einer gemeinsamen Git-Objektdatenbank:

┌─────────────────────────────────────────────────────────────┐
│                 SHARED REPOSITORY OBJECTS (.git)            │
└──────────────┬───────────────────────────────┬──────────────┘
               │                               │
               ▼                               ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│  PRIMARY WORKSPACE (Human)  │ │ SHADOW WORKSPACE (AI Agent) │
│ • Branch: feature/payments  │ │ • Branch: agent/fix-auth    │
│ • Path: ~/projects/app      │ │ • Path: ~/.worktrees/task-42│
│ • Port: 3000 (Active)       │ │ • Port: 3001 (Isolated)     │
│ • Uncommitted local edits   │ │ • Automated ReAct Loop      │
└─────────────────────────────┘ └─────────────────────────────┘

1. Gemeinsame Objektdatenbank (Single Object Database):
   • Alle Workspaces nutzen dieselbe lokale Git-Objektdatenbank (.git/objects). Es ist nicht nötig, Gigabytes an Historie erneut herunterzuladen oder ein langsames git clone durchzuführen.
2. Dynamischer Agenten-Worktree:
   • Wird in Millisekunden durch den Befehl git worktree add -b <agent-branch> <shadow-path> <base-commit> erstellt.
   • Stellt dem Agenten ein vollständig sauberes Working Tree bereit, frei von Müll und unfertigen Änderungen des Menschen.
3. Umgebungsisolierung (Environment Decoupling):
   • Eigene Konfigurationsdateien für die Umgebung (.env.test), isolierte Netzwerkports und eigene temporäre Build-Verzeichnisse.
4. Merge- und Bereinigungsmechanismus (Reconciliation & Cleanup):
   • Nach Validierung und erfolgreichem Durchlaufen der Tests werden die Änderungen als atomarer Commit formuliert, woraufhin das Schatten-Verzeichnis sicher gelöscht wird (git worktree remove).

3. Technischer Pipeline und interne Mechanik

Der Lebenszyklus einer Aufgabe im Shadow Workspace:

1. Initialisierung und Zuweisung des Shadow Spaces: Der Orchestrator (oder der Entwickler über einen Befehl wie agy-run-in-worktree) generiert eine eindeutige Task-ID und erstellt das Verzeichnis:

   git worktree add -b agent/auth-refactor ../shadow-auth main
   

2. Schnelles Linking der Abhängigkeiten: Um minutenlanges Warten auf npm install zu vermeiden, erstellt der Orchestrator symbolische Links auf gemeinsame node_modules oder nutzt den Content-Cache von pnpm:

   ln -s $(pwd)/node_modules ../shadow-auth/node_modules
   

3. Autonome Arbeit des Agenten: Der Agent startet mit dem Arbeitsverzeichnis Cwd = ../shadow-auth. Er führt selbstständig folgende Aktionen aus:
   • Lesen und Bearbeiten von Dateien.
   • Starten eines lokalen Servers auf einem isolierten Port (PORT=3005 npm run test:e2e).
   • Iteration im ReAct-Zyklus bis zum vollständigen Erfolg.
4. Validierung des Ergebnisses: Alle Tests laufen im Shadow Space. Wenn der Agent den Build bricht, spürt der Ingenieur keinerlei Probleme in seiner primären IDE.
5. Fixierung und Integration: Der Agent erstellt einen finalen Commit im Branch agent/auth-refactor. Der Orchestrator entfernt das Shadow-Verzeichnis:

   git worktree remove ../shadow-auth
   

6. Präsentation des Ergebnisses an den Ingenieur: Der Ingenieur sieht die Meldung zur Fertigstellung der Aufgabe und kann schnell einen git merge durchführen oder einen PR öffnen.

4. Praktische Engineering-Szenarien im Production-Betrieb

01. Parallele Feature-Entwicklung ohne Unterbrechung der Entwicklerarbeit

Der Ingenieur entwickelt einen neuen Einstellungs-Screen im Branch main:

• Gleichzeitig startet er einen Background-Agenten zur Erstellung von Datenbank-Migrationen und Controllern im Shadow Workspace.
• Der Agent führt Tests aus, korrigiert Typen und bereitet den Backend-Teil isoliert vor.
• Der Ingenieur unterbricht seine Screen-Entwicklung keine einzige Sekunde.

02. Turnierartiges Testen konkurrierender Hypothesen (Multi-Agent Bake-off)

Suche nach dem schnellsten Algorithmus zur Verarbeitung großer Datenmengen:

• Der Orchestrator deployt drei parallele Worktrees: agent-a, agent-b, agent-c.
• Drei verschiedenen Modellen (Claude 3.7 Sonnet, DeepSeek R1, GPT-4o) wird dieselbe Optimierungsaufgabe gestellt.
• Ein Benchmark wird ausgeführt; die Lösung mit der besten Latency wird ausgewählt, während die beiden anderen Workspaces automatisch gelöscht werden.

03. Sichere Ausführung ungeprüfter Agent-Skripte

Testen einer radikalen Aktualisierung des System-Kernels:

• Falls der Agent die Dateistruktur komplett zerstört oder nicht-lauffähigen Code generiert, löscht der Entwickler einfach das Workspace-Verzeichnis in 1 Sekunde, ohne Angst, das lokale Git-Repository zu beschädigen.

5. Fallstricke, typische Fehler und Sicherheit

• Konflikte bei belegten Netzwerk-Ports (Port Collisions): Wenn ein Shadow Workspace Tests ausführt, die implizit versuchen, einen Webserver auf dem festen Port 3000 zu starten, schlagen diese mit dem Fehler EADDRINUSE fehl, falls dieser Port vom Entwickler belegt ist. Konfigurieren Sie stets parametrisierbare Ports.
• Branch-Locks (Worktree Branch Locks): Git verbietet das Mounten desselben Branches in zwei verschiedenen Worktrees gleichzeitig. Shadow-Agenten müssen immer in neuen, eindeutigen Branches arbeiten.
• Ansammlung von Speicherplatz: Beendet der Orchestrator abrupt ohne den Bereinigungsschritt (git worktree remove), können Dutzende vergessene Repository-Ordner auf der Festplatte verbleiben. Führen Sie regelmäßig git worktree prune aus.
• Leckage unkontrollierter Dateien (.env.local): Dateien, die in .gitignore stehen, werden nicht automatisch in den neuen Worktree kopiert. Dem Agenten muss explizit Zugriff auf Test-Umgebungsvariablen gewährt werden, damit Tests korrekt durchlaufen.