ki-grok/06-worktrees-und-isolierte-arbeit.md

Kapitel 6

Worktrees und isolierte Arbeit

Kern in einem Satz: Ein Git-Worktree ist eine zweite Arbeitskopie desselben Repos: Agenten (oder du) editieren isoliert – Merge/Apply erst, wenn der Diff reviewbar und grün ist.

---

6.1 Warum Isolation, wenn Subagents schon „eigenen Kontext“ haben?

Kapitel 5 trennt Kontextfenster. Worktrees trennen Dateien auf Disk.

Ohne Worktree (isolation: none)	Mit Worktree (isolation: worktree)
Alle schreiben in denselben Working Tree	Kind schreibt in eigene Worktree-Kopie
Parallel-Fixes reiben sich an denselben Dateien	Konflikte entstehen beim Merge, nicht mittendrin
git status mischt alle Experimente	Pro Experiment eigener Status

Alltagsschmerz: Session A refactort Auth, Session B fixt CI – beide rühren package.json an. Am Abend: weder Feature noch CI, dafür ein Diff, den niemand mergen will.

Philosophie: Isolation ist billiger als Heldentum. Lieber zwei saubere Worktrees und ein bewusstes Apply als einen gemeinsamen Working Tree als Chaos-Zone.

{width=90%}

---

6.2 Drei Einstiege in Worktrees bei Grok Build

A) Neue interaktive Session im Worktree

# Wichtig: --worktree=name mit Gleichheitszeichen,
# sonst frisst -w den Prompt als Worktree-Label.
grok --worktree=feat "refactor module X"

# Kurzform -w, Basis-Ref setzen (z. B. main statt aktuellem HEAD):
grok -w --ref main "implement feature from main"
# bzw. --worktree-ref

Warum = bei --worktree=feat?
grok -w "refactor module X" interpretiert den String leicht als Worktree-Name, nicht als Prompt. Mit --worktree=feat und Prompt danach (oder expliziter Trennung) bleibt die Absicht klar.

B) Subagent mit isolation: worktree

Der Parent spawnt ein Kind; Grok legt einen isolierten Worktree an. Das Kind arbeitet dort; das Result enthält typischerweise den Worktree-Pfad. Änderungen bleiben isoliert, bis du sie zurückführst (Apply/Merge – intern u. a. über x.ai/git/worktree/*, inkl. Apply in den Haupt-Working-Tree).

# Prompt-Steuerung (sinngemäß – der Agent setzt isolation)
Implementiere Feature Flag "export_csv" in einem worktree-isolierten
general-purpose-Subagenten. Parent-Tree nicht anfassen.
Am Ende: Summary, Worktree-Pfad, Testbefehl, Diff-Statistik.

C) Session forken mit Worktree

/fork --worktree untersuche parallel den CI-Fix auf main-Stand
/fork --no-worktree bleib im selben Tree, nur Gespräch verzweigen
/fork   # ohne Flag: Grok fragt nach

Resume in frischem Worktree:

grok -w -r <session-id>

Neue Session-Taste: Ctrl+N (ggf. Doppel-Geste) kann optional einen Worktree anbieten – UI-abhängig; CLI-Flags sind die reproduzierbare Variante.

---

6.3 Was Grok intern orchestriert

Worktree-Sessions nutzt Extension-Methoden unter x.ai/git/worktree/*, sinngemäß:

Operation	Bedeutung
Create	Neuer Worktree für isolierte Session/Kind
Apply	Änderungen zurück in den Haupt-Working-Tree mergen/anwenden
Remove / gc	Aufräumen, wenn fertig
list / status	Übersicht und Fortschritt

Du musst die JSON-RPC-Namen nicht auswendig können – aber du musst Apply bewusst behandeln: Isolation ohne Merge-Plan ist nur aufgeschobenes Chaos.

grok sessions list gruppiert Sessions oft nach Worktree-Label – hilfreich, wenn du den Überblick verlierst.

---

6.4 Git-Grundlagen, die du brauchst (90 Sekunden)

# klassisches manuelles Worktree (ohne Grok) – Konzept
git worktree list
git worktree add ../your-project-feat-x -b feat/x main
cd ../your-project-feat-x
# … arbeiten …
cd ../your-project
git worktree remove ../your-project-feat-x

Grok automatisiert Create/Apply/Remove in seinem Workflow. Dein Job:

1. Wissen, in welchem Tree du gerade bist (pwd, git rev-parse --show-toplevel).
2. Diffs pro Tree reviewen.
3. Apply/Merge nur mit grünen Checks.
4. Keine Secrets und keine .env mit echten Keys in Worktrees committen.

Achtung: Untracked Secrets in einem Tree sind nicht „sicherer“, nur weil ein zweiter Tree existiert. Worktrees teilen oft das Objekt-Repo; Credentials gehören in Env/Vault, nicht in Dateien.

---

6.5 Wann Worktree – wann nicht?

Situation	Worktree?
Zwei Features parallel mit Datei-Overlap-Risiko	ja
Riskanter Refactor, Baseline soll clean bleiben	ja
Agent-Experiment „was-if“, das du verwerfen willst	ja
Einzeiler-Bugfix, eine Datei	nein – Overhead
Reines Lesen / Explore	nein – explore reicht
Schon schmutziger Working Tree voller WIP	ja (oder erst stash/commit)

Persona-Default: default_isolation = "worktree" an Personas/Roles, die immer schreiben – dann startet Resolution eher isoliert (Kapitel 5). Default ohne Override bleibt meist none.

{width=90%}

---

6.6 Der Apply-/Merge-Vertrag

Nach isolierter Arbeit:

1. Summary lesen – was wurde geändert, welche Tests?
2. Worktree-Pfad öffnen – git status, git diff, kritische Files.
3. Verify im Worktree – dieselben Commands wie im Plan.
4. Apply/Merge in den Haupt-Tree (Agent-Tooling oder manuell per Branch/PR).
5. Integrationstest im Haupt-Tree – „im Worktree grün“ ≠ „mit deinem WIP grün“.
6. Worktree entfernen, wenn der Branch im Remote/PR lebt.

PR-first Variante (oft teamtauglicher): Worktree pusht Branch → normaler PR → kein Apply in den schmutzigen lokalen main. Isolation bleibt; Review läuft über GitHub/GitLab.

Arbeite im Worktree-Branch feat/export-csv.
Am Ende: Branch pushen, PR-Body skizzieren, Haupt-Working-Tree unangetastet.

---

6.7 Zusammenspiel mit Plan Mode und Subagents

Parent: Plan Mode (Kapitel 4) → Ansatz freigeben
   └─ general-purpose Subagent, isolation=worktree → implementieren
Parent: Summary + Verify-Plan prüfen → Apply oder PR

Fallen:

• Parent in Plan Mode, Kind general-purpose ohne Worktree im shared Tree → Kind kann trotz Parent-Plan schreiben (Parent-Plan ≠ Kind-Gate, Kapitel 4).
• Zwei Worktree-Kinder am selben logischen Feature ohne Absprachen → doppelte Branches, doppelte Wahrheit.
• Apply während Parent selbst dirty ist → Konflikte; vorher Parent clean oder PR-only.

---

6.8 Praxis-Sessions

Session A – Feature im Launch-Worktree

cd ~/projects/your-app
git status   # ideal: clean oder bewusstes WIP
grok --worktree=export-csv "Add CSV export for invoices using existing streaming helpers. Tests required. Do not touch auth."

Trainingsziel: pwd / Worktree-Label in Session-Info; Diff nur in diesem Tree; Haupt-Tree unverändert (git status im Original-Pfad).

Session B – Parent orchestriert isoliertes Kind

grok

Bleib im aktuellen Tree und ändere nichts selbst.
Spawne einen general-purpose-Subagenten mit isolation=worktree:
Fix flaky test_retry_timeout, minimale Änderung, pytest tests/payments -q.
Report: Worktree-Pfad, Diff-Stat, Testergebnis.
Apply noch nicht – ich review zuerst.

Trainingsziel: Review vor Apply; du entscheidest Merge.

Session C – Zwei parallele Tracks

Track 1 (worktree): Feature-Flag docs-only in README + config sample.
Track 2 (worktree): Unit-Test für formatDate Timezone-Bug.
Kein gemeinsamer Dateipfad. Am Ende zwei Summaries, kein Auto-Apply.

Trainingsziel: Parallelität mit disjunkten Scopes.

Session D – Fork mit Worktree

/fork --worktree alternative: implement caching with in-memory map only

Original-Session bleibt auf dem anderen Ansatz. Später einen Weg verwerfen.

Session E – Resume isoliert

grok -w -r <session-id>

Trainingsziel: Alte Session, frische Disk-Isolation – nützlich nach Laptop-Wechsel oder wenn der alte Worktree weg ist.

---

6.9 Manuelles Sicherheitsnetz

Wenn Grok-Worktrees und dein Git durcheinanderwirken:

git worktree list
git status
git branch -vv
# vorsichtig aufräumen – nur Worktrees, die du verstehst:
# git worktree remove <path>

Nicht blind rm -rf auf Worktree-Pfade mit uncommitteter Arbeit. Nicht force-pushen, „um den Tree sauber zu machen“.

---

6.10 Jetzt selbst machen: Isolation-Parcours (30 Minuten)

Jetzt selbst machen

1. Repo mit sauberem git status wählen (oder WIP committen/stashen).
2. Session A: grok --worktree=… mit engem Feature-Prompt.
3. Im Original-Pfad git status – sollte das Experiment nicht zeigen.
4. Im Worktree Diff + Test laufen lassen.
5. Session B: Parent spawnt worktree-Subagent, kein sofortiges Apply.
6. Bewusst entscheiden: PR-Branch oder Apply – und den anderen Weg einmal notieren.
7. git worktree list / grok sessions list ansehen.
8. Aufräumen: Worktree remove oder Branch behalten, aber dokumentieren.

---

6.11 Häufige Fehler

Symptom	Ursache	Fix
Prompt wurde Worktree-Name	-w "langer prompt"	--worktree=label + Prompt getrennt
„Isolation“, aber Dateien im Haupt-Tree	isolation: none / Agent ignoriert	Prompt erzwingen; Diff-Pfade prüfen
Apply-Konflikt-Hölle	Dirty Parent + überlappende Edits	Clean Parent oder PR-only
Verwaiste Worktrees	Session tot, Tree bleibt	git worktree list + remove
Doppelte Features	Zwei Isolationen ohne Owner	Ein Track pro Feature-Owner
Falscher Ref	Worktree von dirty HEAD	--ref main / stabile Basis

---

6.12 Checkliste Worktrees

• Parent-Tree clean oder bewusst PR-only (kein Apply in dirty Parent)
• Basis-Ref bewusst (main vs. feature HEAD)
• Label/Name verständlich (feat-…, nicht tmp1)
• Scope disjunkt bei Parallel-Tracks
• Verify im Worktree vor Apply/PR
• Integration nochmal im Ziel-Tree
• Aufräumen terminiert (remove oder Branch-Lifecycle)
• Keine Secrets in Trees

---

Was du jetzt kannst

• Worktrees als Disk-Isolation von Kontext-Isolation (Subagents) unterscheiden
• Sessions und Subagents isoliert starten (--worktree=, isolation, /fork)
• Einen Apply/PR-Vertrag fahren und parallele Tracks ohne Tree-Kollision orchestrieren
• Häufige CLI- und Git-Fallen vermeiden

Nächste Schritte

→ Kapitel 07 – AGENTS.md und Projektregeln: was in jeder Session (und jedem Worktree) stabil gelten soll – ohne es in jeden Prompt zu kopieren.