# Uruchamiaj równoległe agenty w izolowanych worktree

URL: https://developertoolkit.ai/pl/workflows/harness/git-worktrees/
Description: Uruchamiaj 2–4 równoległych agentów w worktree Gita dla Claude Code, Codexa i Cursora z blokami portów, kontrolą kolizji i bezpiecznym sprzątaniem.

Worktree Gita daje każdemu równoległemu zadaniu agenta kodującego własny katalog roboczy i gałąź przy jednym wspólnym magazynie obiektów Gita. Programiści oraz tech leadzi łączą worktree z blokami portów, allowlistą konfiguracji deweloperskiej, kontrolą nakładających się plików i bezpiecznym sprzątaniem, aby prowadzić dwa do czterech równoległych strumieni w Claude Code, Codexie lub Cursorze bez kolizji.

Otwierasz trzy terminale w tym samym checkoucie. Formatter pierwszego agenta przepisuje plik edytowany przez drugiego, serwer deweloperski drugiego po cichu zajmuje kolejny wolny port, a testy end-to-end trzeciego przechodzą na serwerze drugiego. Wszystkie trzy meldują „gotowe”, mimo że żaden nie udowodnił, który kod przeszedł testy.

## Kiedy równoległe worktree się opłacają, a kiedy lepiej iść szeregowo

Równoległe strumienie zwiększają przepustowość tylko wtedy, gdy zadania dotyczą rozłącznych plików i każde ma maszynową bramkę. Wąskim gardłem jest niemal zawsze pojemność code review, a nie liczba uruchomionych modeli; dwa do czterech aktywnych strumieni utrzymują nadzór i integrację w ryzach dla jednego programisty.

| Sytuacja | Wzorzec wykonania | Uzasadnienie |
| --- | --- | --- |
| 2–4 poprawki lub funkcje w rozłącznych modułach, każda z testami | Równoległe worktree, jeden strumień na zadanie | Niezależne diffy i niezależne bramki |
| Jedno trudne zadanie z dwiema konkurencyjnymi architekturami | Ta sama specyfikacja w dwóch worktree; zostaje czystszy zielony diff | Obiektywne porównanie na identycznych testach |
| Dwa zgłoszenia dotykające tego samego API, schematu lub konfiguracji | Jeden strumień, kolejno | Praca równoległa gwarantuje konflikty semantyczne i przeróbki |
| Rozpoznanie kodu tylko do odczytu albo audyt PR | [Subagent zakresowy](/pl/claude-code/automate/custom-subagents/) w jednej sesji | Bez narzutu osobnego checkoutu i gałęzi |

Szerszy wybór między worktree, subagentami i kolejkami w tle opisują [wzorce orkiestracji](/pl/workflows/automate/orchestration-patterns/).

## Co worktree izoluje, a co pozostaje wspólne

Każdy worktree ma własne pliki robocze, indeks stagingu i wybraną gałąź, współdzieląc historię `.git`, refy i `git config`. Wszystko poza Gitem pozostaje wspólne, dopóki konfiguracja tego nie rozdzieli:

| Zasób | Izolowany przez worktree Gita? | Awaria przy braku izolacji |
| --- | --- | --- |
| Śledzone pliki i gałąź | Tak | Rozwiązane natywnie przez worktree |
| Pliki ignorowane przez Git (`.env`, zależności) | Brak w świeżym worktree | Build pada albo agent zmyśla konfigurację |
| Porty serwera deweloperskiego i testów | Nie | Cichy przeskok portu kieruje testy na serwer innego strumienia |
| Lokalna baza, cache, kolejki | Nie | Równoległe migracje lub seedy psują wspólny stan |
| `git config` | Nie | Zapis konfiguracji w jednym worktree zmienia wszystkie pozostałe |
| Poświadczenia chmurowe, sekrety, wdrożenia | Nie | Każdy strumień wciąż sięga do tych samych zdalnych zasobów |

**Worktree nigdy nie jest sandboksem bezpieczeństwa**

Każdy lokalny worktree dziedziczy sieć, sesje chmurowe i poświadczenia twojej stacji roboczej. Twardą izolację wymuszaj przez [uprawnienia i sandboksy](/pl/workflows/harness/permissions-and-sandboxing/), a zadania wymagające osobnych baz lub zaślepek przenoś do [środowisk efemerycznych](/pl/workflows/harness/ephemeral-environments/).

## Natywne worktree w Claude Code, Codexie i Cursorze

Wszystkie trzy narzędzia obsługują izolowane worktree natywnie, różniąc się lokalizacją katalogu oraz kopiowaniem plików ignorowanych. Aktualne flagi i kroki UI sprawdzaj w oficjalnej dokumentacji:

**Claude Code**

Claude Code oferuje wbudowane sesje worktree oraz izolację worktree dla subagentów, kopiując deweloperskie pliki ignorowane z głównej allowlisty `.worktreeinclude`. Dodaj katalog worktree do `.gitignore`, ogranicz `.worktreeinclude` wyłącznie do lokalnych plików deweloperskich (nigdy sekretów produkcyjnych) i pamiętaj, że przebiegi nieinteraktywne zostawiają worktree do jawnego sprzątania. Zobacz [dokumentację Claude Code](https://code.claude.com/docs).

**Codex**

Codex tworzy zarządzane worktree z poziomu CLI lub w trakcie sesji ([izolowane worktree Codexa](/pl/codex/automate/worktrees/)). Zarządzane worktree często startują na odłączonym `HEAD` bez plików ignorowanych, więc przed pierwszym commitem utwórz nazwaną gałąź i dostarcz konfigurację lokalną — albo uruchamiaj Codexa wewnątrz worktree utworzonego skryptem repozytorium. Zobacz [dokumentację OpenAI Codex](https://developers.openai.com/codex).

**Cursor**

Cursor obsługuje Worktrees obok okna Agents Window do pracy równoległej ([okno Agents w Cursorze](/pl/cursor-ide/build/agents-window/) · [dokumentacja Cursora](https://cursor.com/docs)). Gdy stos wymaga deterministycznych bloków portów i konfiguracji środowiska, utwórz checkout skryptem repozytorium i otwórz ten katalog w osobnym oknie Cursora.

## Zapisz kontrakt izolacji w skryptach repozytorium

Natywne polecenia narzędzi rozdzielają wyłącznie pliki, nie przydzielając bloków portów ani bezpiecznego sprzątania. Zacommituj cienki wrapper repozytorium (`bin/wt new <slug>` i `bin/wt cleanup <slug>`), aby każdy programista i agent stosował identyczny kontrakt:

1. **Tworzenie z jawną bazą i blokiem portów (`wt new`):** pobierz `origin`, utwórz gałąź `agent/<slug>` od gałęzi domyślnej, przydziel najniższy wolny indeks portów (krok 10, żeby przypadkowy przeskok został w bloku strumienia), zapisz `WT_INDEX`, `WT_BASE`, `APP_PORT` i `DB_PORT` do ignorowanego `.wt-env`, skopiuj wyłącznie jawną allowlistę plików deweloperskich i zainstaluj zależności.
2. **Ścisłe powiązanie serwerów i testów z `.wt-env`:** odczytuj `APP_PORT` z `.wt-env` w konfiguracji serwera i testów E2E z włączonym ścisłym trybem portu, aby serwer zakończył się błędem zamiast cicho przechodzić na kolejny port:

```ts title="playwright.config.ts"
import { readFileSync } from 'node:fs';
import { defineConfig } from '@playwright/test';

const wtEnv = (() => {
  try { return readFileSync('.wt-env', 'utf8'); } catch { return ''; }
})();
const port = /^APP_PORT=(\d+)$/m.exec(wtEnv)?.[1] ?? '4321';
const baseURL = `http://localhost:${port}`;

export default defineConfig({
  use: { baseURL },
  webServer: {
    command: `pnpm dev --port ${port} --strictPort`,
    url: baseURL,
    reuseExistingServer: !process.env.CI,
  },
});
```

3. **Bezpieczne usuwanie (`wt cleanup`):** odmawiaj usunięcia, gdy `git status --porcelain` nie jest pusty, gdy na porcie z `.wt-env` wciąż nasłuchuje proces albo gdy gałąź zawiera commity niewypchnięte na `origin`.

## Prowadź równoległe strumienie od podziału do scalenia

1. **Najpierw podziel niezależne zadania.** Przed utworzeniem checkoutów sprawdź, czy wybrane tickety modyfikują rozłączne pliki i kontrakty publiczne; prace nakładające się ustaw szeregowo.
2. **Uruchom 2–4 strumienie skryptem wrappera.** Wystartuj po jednej sesji agenta w każdym worktree z jawnymi granicami ścieżek i kontraktem portów z `.wt-env`.
3. **Wymagaj lokalnych bramek w każdym worktree.** Agent kończy zadanie dopiero wtedy, gdy typy, lint i testy zwracają kod 0 wewnątrz jego checkoutu — najlepiej z egzekwowaniem przez [hook `Stop`](/pl/workflows/harness/agent-hooks/).
4. **Integruj kolejno i rób rebase.** Scalaj PR-y po jednym, rebasuj pozostałe aktywne gałęzie na zaktualizowany `main`, ponawiaj bramki i sprzątaj scalone worktree bezpiecznym skryptem ([kolejka review](/pl/teams/review-queue/)).

**Prompt do skopiowania: sprawdź niezależność strumieni przed rozgałęzieniem**

```text
Read issues #412, #415, and #418 without editing code. For each issue list:
- Expected files and modules modified
- Shared contracts touched (API routes, DB schema, exported types, configs)
- Executable test or acceptance check proving completion
Output a table marking each issue "parallel" or "after #<id>" so no two parallel
worktrees edit the same file or shared contract.
```

## Zweryfikuj równoległe strumienie bez czytania każdego diffu

Przed otwarciem lub recenzją PR-ów wykonaj cztery mechaniczne sprawdzenia:

- **Kontrola nakładania się plików między gałęziami:** uruchom w głównym checkoucie; każda wypisana ścieżka oznacza kolizję dwóch strumieni — zatrzymaj jeden do czasu scalenia i rebasu drugiego:

```bash
for b in $(git for-each-ref --format='%(refname:short)' refs/heads/agent/ 'refs/heads/worktree-*'); do
  git diff --name-only "origin/main...$b"
done | sort | uniq -d
```

- **Weryfikacja bazy i portu:** potwierdź, że `git merge-base HEAD origin/main` zgadza się z planowaną rewizją bazową, a proces nasłuchujący na `APP_PORT` działa z katalogu tego właśnie worktree.
- **Automatyczny audyt Stanowiska 4:** uruchom `npx @wondelai/harness-audit --lang pl`, aby zweryfikować w Stanowisku 4 (Graf) skrypty worktree, higienę `.worktreeinclude` i izolację portów ([przewodnik po harness-audit](/pl/workflows/harness/harness-audit-guide/)).
- **Pakiet dowodów:** dołączaj dokładne komendy, kody wyjścia i listy zmienionych plików do każdego PR-a ([pakiet dowodów](/pl/workflows/ship/evidence-bundle/)).

## Kiedy równoległe worktree sprawiają problemy

- **Testy przechodzą na serwerze sąsiedniego strumienia.** Brak `strictPort` albo stałe URL-e w testach E2E maskują zepsuty kod. Zatrzymaj wszystkie serwery, powiąż serwery i URL-e testów ściśle z `.wt-env` i unieważnij wcześniejsze niezweryfikowane przebiegi.
- **Świeże worktree nie potrafi się zbudować.** Brak konfiguracji deweloperskiej lub zależności zatrzymuje agenta. Dodaj pliki deweloperskie do allowlisty wrappera albo `.worktreeinclude` i zautomatyzuj instalację zależności przy tworzeniu worktree.
- **Commity znikają po usunięciu odłączonego `HEAD`.** Odzyskaj je przez `git reflog` przed czyszczeniem i wymagaj w prompcie startowym sprawdzenia `git branch --show-current` oraz utworzenia nazwanej gałęzi przed pierwszą edycją.
- **Dwa strumienie przechodzą osobno, ale psują się po scaleniu.** Zmieniły niejawny wspólny kontrakt. Zrób rebase drugiego strumienia na zaktualizowany `main`, ponów pełną bramkę i wpisz ten kontrakt na listę zadań szeregowych.
- **Przebiegi headless zostawiają zablokowane worktree.** Sprawdź `git status`, zachowaj potrzebne commity, odblokuj i usuń stare worktree oraz okresowo wykonuj `git worktree prune`.

## Oficjalna dokumentacja i kolejne kroki

Aktualne komendy worktree, zasady `.worktreeinclude` i obsługę wielu agentów sprawdzaj w oficjalnej dokumentacji: [Claude Code](https://code.claude.com/docs), [OpenAI Codex](https://developers.openai.com/codex) i [Cursor](https://cursor.com/docs).

- [Środowiska efemeryczne](/pl/workflows/harness/ephemeral-environments/) — Dodaj osobne bazy, zaślepki usług i sprzątanie, gdy sama izolacja plików nie wystarcza.
- [Wzorce orkiestracji](/pl/workflows/automate/orchestration-patterns/) — Dobieraj worktree, subagentów i kolejki w tle do kształtu zadania.
- [Izolowane worktree w Codexie](/pl/codex/automate/worktrees/) — Obsługuj zarządzane worktree Codexa, gałęzie i czyszczenie bez utraty zmian.
- [Kolejka code review](/pl/teams/review-queue/) — Nie dopuść, by równoległe strumienie agentów zatkały przegląd PR-ów.
