Cień Workspace i Git Worktrees

1. Przegląd koncepcji i problem systemowy

Gdy autonomiczny agent zaczyna modyfikować kod w aktywnym katalogu dewelopera, dochodzi do krytycznego zablokowania przepływu pracy (Workflow Lockout). Jeśli agent edytuje 25 plików, kompiluje kod, instaluje paczki i uruchamia testy, człowiek nie może równolegle pisać kodu, sprawdzać swojego lokalnego serwera dev ani przełączać gałęzi: niezatwierdzone zmiany dewelopera i agenta nieuchronnie się mieszają, powodując konflikty.

Co więcej: jeśli agent poniesie porażkę, zawiesi się lub zacznie halucynować, resetowanie drzewa roboczego (git checkout -f lub git clean) może przypadkowo nadpisać niezatwierdzoną pracę samego inżyniera.

Shadow Workspace (przestrzeń robocza cienia) oparta na Git Worktrees rozwiązuje ten problem raz na zawsze. Agent otrzymuje całkowicie izolowany katalog na dysku, przypisany do własnej gałęzi. Inżynier kontynuuje pisanie kodu w swoim ulubionym edytorze, podczas gdy agent działający w tle wykonuje złożony refactoring w środowisku cieniowym, bez żadnego wpływu na aktywną stację roboczą.

2. Taksonomia architektoniczna i model mentalny

Architektura interakcji z przestrzeniami cieniowymi opiera się na rozdzieleniu dysków oraz współdzielonej bazie obiektów Git:

┌─────────────────────────────────────────────────────────────┐
│                 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. Wspólne repozytorium obiektów (Single Object Database):
   • Wszystkie przestrzenie robocze korzystają z jednej lokalnej bazy obiektów Git (.git/objects). Nie ma potrzeby ponownego pobierania gigabajtów historii ani wykonywania wolnego git clone.
2. Dynamiczny Worktree agenta:
   • Tworzony w milisekundach za pomocą polecenia git worktree add -b <agent-branch> <shadow-path> <base-commit>.
   • Zapewnia agentowi całkowicie czyste drzewo robocze, wolne od śmieci i niedokończonych poprawek człowieka.
3. Izolacja środowiska (Environment Decoupling):
   • Własne pliki konfiguracyjne środowiska (.env.test), izolowane porty sieciowe oraz dedykowane tymczasowe katalogi buildów.
4. Mechanizm scalania i czyszczenia (Reconciliation & Cleanup):
   • Po weryfikacji i pomyślnym przejściu testów zmiany są pakowane jako atomowy commit, po czym katalog cieniowy jest bezpiecznie usuwany (git worktree remove).

3. Pipeline techniczny i mechanika wewnętrzna

Cykl życia zadania w przestrzeni roboczej cienia:

1. Inicjalizacja i alokacja przestrzeni cieniowej: Orkiestrator (lub deweloper poprzez komendę typu agy-run-in-worktree) generuje unikalny ID zadania i tworzy katalog:

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

2. Szybkie linkowanie zależności: Aby nie czekać minutami na wykonanie npm install, orkiestrator tworzy dowiązania symboliczne do wspólnych node_modules lub wykorzystuje cache treściowy pnpm:

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

3. Autonomiczna praca agenta: Agent startuje z katalogiem roboczym Cwd = ../shadow-auth. Samodzielnie:
   • Odczytuje i edytuje pliki.
   • Uruchamia lokalny serwer na izolowanym porcie (PORT=3005 npm run test:e2e).
   • Iteruje w cyklu ReAct aż do pełnego sukcesu.
4. Walidacja wyniku: Wszystkie testy przechodzą w przestrzeni cieniowej. Jeśli agent zepsuł build, inżynier nie odczuwa żadnych problemów w swojej głównej IDE.
5. Utrwalenie i integracja: Agent wykonuje finalny commit na gałęzi agent/auth-refactor. Orkiestrator usuwa katalog cieniowy:

   git worktree remove ../shadow-auth
   

6. Prezentacja wyniku inżynierowi: Inżynier widzi komunikat o gotowości zadania i może wykonać szybki git merge lub otworzyć PR.

4. Praktyczne scenariusze inżynierskie w produkcji

01. Równoległe rozwijanie funkcjonalności bez przerywania pracy dewelopera

Inżynier buduje nowy ekran ustawień na gałęzi main:

• Jednocześnie uruchamia agenta w tle do napisania migracji bazy danych i kontrolerów w przestrzeni cieniowej.
• Agent uruchamia testy, naprawia typy i przygotowuje backendową część w izolacji.
• Inżynier ani przez sekundę nie przerywa pracy nad swoim ekranem.

02. Testowanie turniejowe konkurujących hipotez (Multi-Agent Bake-off)

Szukanie najszybszego algorytmu do przetwarzania dużych zbiorów danych:

• Orkiestrator wdraża trzy równoległe Worktrees: agent-a, agent-b, agent-c.
• Trzem różnym modelom (Claude 3.7 Sonnet, DeepSeek R1, GPT-4o) stawiane jest to samo zadanie optymalizacyjne.
• Uruchamiany jest benchmark; wybierane jest rozwiązanie z najlepszym wskaźnikiem latency, a dwa pozostałe workspace'y są automatycznie usuwane.

03. Bezpieczne uruchamianie nieweryfikowanych skryptów agentowych

Testowanie radykalnej aktualizacji jądra systemu:

• Jeśli agent całkowicie zniszczy strukturę plików lub wygeneruje niedziałający kod, deweloper po prostu usunie katalog workspace'u w ciągu 1 sekundy, bez ryzyka uszkodzenia lokalnego repozytorium Git.

5. Pułapki, typowe błędy i bezpieczeństwo

• Konflikty zajętych portów sieciowych (Port Collisions): Jeśli cieniowy workspace uruchamia testy, które niejawnie próbują postawić serwer webowy na stałym porcie 3000, zakończą się one błędem EADDRINUSE, jeśli port ten jest już zajęty przez dewelopera. Zawsze konfiguruj parametryzację portów.
• Blokady gałęzi (Worktree Branch Locks): Git zabrania montowania tej samej gałęzi w dwóch różnych Worktrees jednocześnie. Cieniowi agenci muszą zawsze pracować na nowych, unikalnych gałęziach.
• Nagromadzenie miejsca na dysku: Jeśli orkiestrator awaryjnie kończy działanie bez kroku czyszczenia (git worktree remove), na dysku mogą pozostawać dziesiątki zapomnianych folderów repozytorium. Okresowo wykonuj git worktree prune.
• Wyciek niekontrolowanych plików (.env.local): Pliki znajdujące się w .gitignore nie są automatycznie kopiowane do nowego worktree'a. Agentowi należy jawnie udostępnić dostęp do zmiennych środowiskowych testów, aby poprawnie przejść walidację.