CLAUDE.md: Worktrees von frisch geholtem origin/main abzweigen, Wiki-Zweigname nennen #57

New Issue

2026-09-28T00:54:31+02:00

jlab-bot commented

2026-09-28 00:54:31 +02:00

Zwei Ergänzungen in CLAUDE.md, beide aus konkreten Vorfällen dieser Woche.

1. Worktrees immer von einem frisch geholten `origin/main`

Ein Worktree, der vom lokalen main abzweigt, kann beliebig alt sein — und die Veralterung ist unsichtbar. Der Grund ist eine Eigenheit der Arbeitsweise mit Agenten: Der Projektanweisungs-Block, den ein Agent am Kontextanfang als bindend erhält, wird aus dem Arbeitsverzeichnis der startenden Sitzung gelesen, nicht aus origin/main. Ein veralteter Worktree legt damit jedem Agenten Regeln vor, die längst korrigiert sind.

Belegt am 2026-09-27: Das Arbeitsverzeichnis der Manager-Sitzung hing mehrere Merges zurück. Ein Umsetzungs-Agent meldete daraufhin einen „Widerspruch" in CLAUDE.md — die Remote-Angabe —, der zwei PRs vorher behoben worden war, und zitierte den alten Text als geltend. Nichts ging kaputt, weil derselbe Agent seinen Diff gegen origin/main geprüft hatte und nicht gegen den lokalen Zeiger. Genau diese Prüfung ist die einzige, die etwas beweist.

Dazu passt ein zweiter Befund aus demselben Tag: Die Arbeitskopie im geteilten Checkout war ebenfalls viele Commits hinter main, sodass ein Vergleich main..HEAD dort 105 abweichende Dateien zeigte, während der Unterschied zu origin/main eine einzige Zeile war.

Vorgeschlagener Text

In CLAUDE.md, Abschnitt „Which forge, and with which tool", als Bullet direkt nach dem Remote-Bullet:

Cut every worktree from a freshly fetched origin/main. git fetch origin main first, then branch from origin/main — never from the local main ref, and never assume the shared checkout is current: both can be many merges behind. The staleness is invisible where it matters most, because the project-instructions block a subagent receives is read from the spawning session's working directory, so an outdated worktree hands every agent rules that were corrected two PRs ago. Measured on 2026-09-27: an agent reported a contradiction in this file that had been fixed two PRs earlier, quoting the stale copy as binding. For the same reason, check a diff against origin/main, never against main.

2. Der Standardzweig des Wikis heißt `main`

Das Wiki ist ein eigenes Repository, und CLAUDE.md nennt seinen Zweignamen nicht. Seit der Regel „vor jedem Push fetchen und rebasen" ist er erforderlich: Ein Agent hat am 2026-09-27 gegen origin/master rebasen wollen, was fehlschlug. Harmlos, weil der Push danach eine saubere Fast-Forward-Änderung war und kein Force im Spiel war — aber vermeidbar.

Vorgeschlagener Text

Im Abschnitt „The wiki", unmittelbar nach dem clone-Block:

Its default branch is main, not master.

Umfang

CLAUDE.md, dazu die entsprechenden Stellen im Wiki (Forge-and-Tooling trägt dieselben Angaben zu Remote, Signatur und Wiki-Klon). Kein Chart: kein Versionsschritt, kein Install-Test, keine Veröffentlichung.

Zwei Ergänzungen in `CLAUDE.md`, beide aus konkreten Vorfällen dieser Woche. ## 1. Worktrees immer von einem frisch geholten `origin/main` Ein Worktree, der vom **lokalen** `main` abzweigt, kann beliebig alt sein — und die Veralterung ist unsichtbar. Der Grund ist eine Eigenheit der Arbeitsweise mit Agenten: Der **Projektanweisungs-Block**, den ein Agent am Kontextanfang als bindend erhält, wird aus dem Arbeitsverzeichnis der **startenden** Sitzung gelesen, nicht aus `origin/main`. Ein veralteter Worktree legt damit jedem Agenten Regeln vor, die längst korrigiert sind. **Belegt am 2026-09-27:** Das Arbeitsverzeichnis der Manager-Sitzung hing mehrere Merges zurück. Ein Umsetzungs-Agent meldete daraufhin einen „Widerspruch" in `CLAUDE.md` — die Remote-Angabe —, der zwei PRs vorher behoben worden war, und zitierte den alten Text als geltend. Nichts ging kaputt, weil derselbe Agent seinen Diff gegen `origin/main` geprüft hatte und nicht gegen den lokalen Zeiger. Genau diese Prüfung ist die einzige, die etwas beweist. Dazu passt ein zweiter Befund aus demselben Tag: Die Arbeitskopie im geteilten Checkout war ebenfalls viele Commits hinter `main`, sodass ein Vergleich `main..HEAD` dort 105 abweichende Dateien zeigte, während der Unterschied zu `origin/main` eine einzige Zeile war. ### Vorgeschlagener Text In `CLAUDE.md`, Abschnitt „Which forge, and with which tool", als Bullet direkt nach dem Remote-Bullet: > - **Cut every worktree from a freshly fetched `origin/main`.** `git fetch origin main` first, then branch from `origin/main` — never from the local `main` ref, and never assume the shared checkout is current: both can be many merges behind. The staleness is invisible where it matters most, because the project-instructions block a subagent receives is read from the **spawning** session's working directory, so an outdated worktree hands every agent rules that were corrected two PRs ago. Measured on 2026-09-27: an agent reported a contradiction in this file that had been fixed two PRs earlier, quoting the stale copy as binding. For the same reason, check a diff against `origin/main`, never against `main`. ## 2. Der Standardzweig des Wikis heißt `main` Das Wiki ist ein eigenes Repository, und `CLAUDE.md` nennt seinen Zweignamen nicht. Seit der Regel „vor jedem Push fetchen und rebasen" ist er erforderlich: Ein Agent hat am 2026-09-27 gegen `origin/master` rebasen wollen, was fehlschlug. Harmlos, weil der Push danach eine saubere Fast-Forward-Änderung war und kein Force im Spiel war — aber vermeidbar. ### Vorgeschlagener Text Im Abschnitt „The wiki", unmittelbar nach dem `clone`-Block: > Its default branch is `main`, not `master`. ## Umfang `CLAUDE.md`, dazu die entsprechenden Stellen im Wiki (`Forge-and-Tooling` trägt dieselben Angaben zu Remote, Signatur und Wiki-Klon). Kein Chart: kein Versionsschritt, kein Install-Test, keine Veröffentlichung.

jklein referenced this issue from a commit

2026-09-28 00:58:51 +02:00

docs: cut every worktree from a freshly fetched origin/main

jlab-bot referenced a pull request that will close this issue

2026-09-28 00:59:21 +02:00

docs: cut every worktree from a freshly fetched origin/main #58

jklein closed this issue

2026-09-28 15:22:57 +02:00

Sign in to join this conversation.