tderoussel/fleet-brief

Was macht fleet-brief?

Parallele Agenten scheitern an gemeinsamen Grundlagen — zwei Spuren, die eine Datei bearbeiten. Der Brief existiert, um diese Kollision vor dem Dispatch unmöglich zu machen. Leite die Grenzen aus der tatsächlichen Dateikarte ab; nimm sie niemals an.

Erstelle den Brief in dieser Reihenfolge

1. Ordne zuerst die Dateien

Bevor du Spuren definierst, liste die Dateien auf, die jede vorgeschlagene Änderung berühren würde. Lies sie. Eine Spur, die ohne Lesen ihrer Dateien definiert wird, ist eine Kollision, die nur darauf wartet, zu passieren.

2. Weise exklusive Besitzrechte zu

Jede Datei hat genau eine besitzende Spur. Erstelle diese Tabelle:

Spur	Besitzt (schreibt)	Liest nur
W1 —	path/a.ts, path/b.ts	path/shared.ts

Wenn zwei Spuren eine Datei schreiben müssen, hast du drei Optionen — wähle explizit eine aus, lasse sie nie mehrdeutig:

• Sequenziere sie (W2 wartet auf den Merge von W1)
• Vereine sie zu einer Spur
• Füge eine Naht ein: Eine Spur fügt einen Erweiterungspunkt hinzu, die andere nutzt ihn

3. Benenne die gemeinsamen Grundlagen

Liste jede Datei auf, die mehr als eine Spur liest, und gib an, wer sie schreiben darf.

Leite diese Liste aus der vor dir liegenden Codebasis ab — übernimm nicht die Liste eines anderen Projekts. Die wiederkehrenden Muster, die es wert sind, überprüft zu werden:

• Der Live-Eingangspfad. Was auch immer Webhooks oder Benutzerverkehr empfängt. Gleichzeitige Änderungen hier scheitern in der Produktion, nicht in Tests.
• Engine- und Dispatcher-Module, die von mehreren Funktionen aufgerufen werden.
• Nur-anhängbare Manifeste — Bereitstellungskonfigurationen, Routentabellen, Funktionslisten. Plattformen setzen Grenzen (Funktionsanzahlen, Dateigrößen); zwei Spuren, die unabhängig voneinander anhängen, können eine überschreiten.
• Weit importierte Exporte. Erweitere additiv; eine Umbenennung wirkt sich auf jeden Aufrufer aus.
• Generierte oder eingekaufte Dateien, die keine Spur von Hand bearbeiten sollte.

Eine Datei, die bereits einmal eine Kollision verursacht hat, ist dauerhaft gemeinsamer Grund. Halte sie im Brief fest, damit die nächste Flotte das Wissen erbt.

4. Leite die DO-NOT-Liste ab

Jeder DO-NOT-Eintrag nennt eine Datei oder ein Verhalten sowie den Grund. Bloße Verbote werden ignoriert; begründete Verbote haben Bestand.

Einträge, die für die meisten Codebasen verallgemeinern:

• Führe niemals git add -A während der Konfliktlösung aus — es staged die Konfliktmarkierungen und die Arbeit anderer Spuren.
• Arbeiter committen nicht in verknüpften Worktrees; der Orchestrator committed.
• Wenn die Testsammlung die Datenbank global mockt, beweist ein grüner Unit-Test nichts über die Datenbank. Sage dies explizit.
• Füge keine Abhängigkeiten ohne eine einzeilige Begründung hinzu.
• Wende keine Schema-Migrationen aus einer Spur heraus an. Verschiebe sie auf einen einzigen überprüften Schritt.
• Achte auf CLI-Aufrufe, die stillschweigend fehlschlagen — z. B. benötigt gh pr create ein explizites --base, und verkettete Heredocs können Fehler verschlucken.

Füge dann die projektspezifischen hinzu. Jeder Vorfall, der dich eine Nacht gekostet hat, gehört hierher, mit seinem Grund.

5. Setze die Hürde

Gib explizit pro Spur an: Was „erledigt“ bedeutet, welche Belege es gibt und wer vor dem Merge prüft.

Der Standard, den es wert ist, beibehalten zu werden, ist Prüfung-vor-Live — bauen, dann unabhängige Code-Review, dann Muss-fix-Runden, dann mergen. Führe niemals einen Merge einer Spur allein auf das Wort des Autors hin durch. Der Agent des Autors ist der schlechteste mögliche Prüfer seines eigenen Diffs.

6. Markiere, was zurückgehalten wird

Ein Abschnitt Bewusst NICHT erledigt — benötigt einen Menschen. Elemente, die für eine explizite Freigabe zurückgehalten werden, werden absichtlich zurückgehalten. Erlaube einer Spur nicht, eines auszuführen, nur weil es bereit aussieht.

Isolation

Führe Builds in Git-Worktrees aus, niemals im Haupt-Checkout — eine Flotte, die ein Arbeitsverzeichnis teilt, wird Änderungen vermischen. Wenn Spuren trotz der Karte überlappende Dateien ändern, gib jeder ihren eigenen Worktree.

Größenbestimmung

Spuren sollten unabhängig voneinander mergebar sein. Wenn eine Spur nicht ohne den PR einer anderen Spur gemerged werden kann, ist es keine Spur — es ist eine Phase. Sequenziere Phasen; parallelisiere Spuren.

Ausgabe

Schreibe den Brief dorthin, wo das Projekt seine Pläne aufbewahrt, und öffne ihn mit einer Warnung „überprüfen, niemals annehmen“. Statuszeilen in jedem Quelldokument sind Kontrollpunkte, keine Autorität — überprüfe erneut den aktuellen Commit, den Datenbankzustand, die PR-Prüfungen und die Worktree-Heads, bevor du basierend darauf dispatchst.