phmatray/ai-migration-kit

auto-dev — eine kontinuierliche Flotte, die Issues implementiert und zusammenführt

Was es tut

implement-issue macht aus einem geplanten Issue einen bereiten PR; merge-pr führt einen PR zusammen. auto-dev beaufsichtigt sie im großen Maßstab: N Hintergrund-Worker besitzen jeweils ein Issue Ende-zu-Ende (implement-issue <N> → merge-pr <PR>); sobald der PR eines Workers zusammengeführt wird, wird er ausgemustert und ein neuer Worker wird auf das nächste anstehende Issue losgelassen – sodass N Issues ohne Ihre Aufsicht in Bearbeitung bleiben.

Der Wert liegt in der Orchestrierung, die eine naive „Führe sie in einer Schleife aus“-Herangehensweise vermeidet:

• Konfliktvermeidung – jeder gleichzeitige Worker erhält ein Issue in einem anderen Codebereich, sodass Branches selten kollidieren.
• Reihenfolge – zuerst kleine, in sich geschlossene Issues (schnelle Erfolge, weniger Konflikte), dann mittlere. L/XL und manuelle QA sind standardmäßig ausgeschlossen.
• Erzwungener Merge – Worker lieben es, bei „PR bereit“ stehen zu bleiben (halbe Arbeit). auto-dev überprüft den echten Merge-Status von GitHub bei jedem Signal und treibt jeden Worker erneut an, der stockt.
• Erfassung außerhalb des Geltungsbereichs – ein Worker, der über einen nicht verwandten Bug stolpert, behebt ihn nur inline unter dem Freiraum von implement-issue (lokal in einer Datei, die sein PR bereits ändert und klein, in einem eigenen Commit) und erstellt andernfalls einen Issue über create-issue, anstatt ihn fallen zu lassen, gegen die gemeinsame Filing-Bar (../_shared/filing-bar.md), sodass eine Flotte von N Workern nicht mit N verschiedenen Standards erstellt. Das Backlog bleibt wahrheitsgetreu und abbaubar (#410).
• Lifecycle-Hygiene – beendete Agenten werden heruntergefahren; eine Zustandsdatei überlebt Neustarts, sodass die Flotte fortsetzbar ist.

Autonomievertrag

Der Benutzer startet dies und geht weg – er sieht zu, wie ein Backlog abgebaut wird, er genehmigt nicht jeden Schritt. Führen Sie autonom durch: Wählen Sie die vernünftige Standardeinstellung, geben Sie sie an, machen Sie weiter. Stoppen Sie nur bei echten Blockaden:

• gh ist nicht authentifiziert, oder Sie haben keine Push-/Merge-Rechte.
• Keine berechtigten Issues (Warteschlange nach Filterung leer) – melden Sie, dass das Backlog abgebaut wurde.
• Ein echter harter Block eines Workers (Tests, die er nicht grün bekommt, ein Konflikt, bei dem beide Seiten dieselbe Logik umgeschrieben haben, eine erforderliche Genehmigung, die er sich nicht selbst geben kann). Machen Sie ihn sichtbar; erzwingen Sie keinen Merge.

Täuschen Sie niemals Fortschritt vor: Ein Kontrollkästchen, ein „bereit“-Umschalten oder ein Merge behauptet, dass Arbeit erledigt ist – untermauern Sie jeden mit Beweisen, wie es die untergeordneten Skills erfordern. Der Squash-Merge ist die einzige irreversible Aktion – er erfolgt nur über merge-pr bei einem grünen, mergebaren PR, niemals über einen --admin-Override hier.

Eingaben

• Parallelität N – Worker gleichzeitig. Standard 3 (3–4 ist der Sweet Spot; mehr = mehr Konflikte und mehr Bereiche, die disjunkt gehalten werden müssen).
• Reihenfolge – standardmäßig klein→mittel. Halten Sie sich an das, was der Benutzer gesagt hat.
• Berechtigte Menge – standardmäßig offene Issues, die (a) einen Implementierungsplan haben, (b) Code-Aufgaben sind (nicht manuelle „QA“/„von Hand verifizieren“), (c) innerhalb des Aufwandslimits liegen (Standard ≤ mittel). Halten Sie sich an Eingrenzungen („nur studio-Issues“, „mit Label priority: high“).
• Heartbeat – normalerweise über loop im dynamischen Modus gestartet, sodass das selbstgetaktete Aufwachen der Schleife der Heartbeat ist. Wenn direkt aufgerufen, rüsten Sie Ihr eigenes Aufwachen.
• Modellstufe – Standard gestaffelt, nicht nur Opus (siehe Token-Ökonomie): günstigstes fähiges Modell für Mechanisches/Dokumentation, mittleres für typische Bugs, oberstes reserviert für bereichsübergreifende/schwierige Arbeit + Fehler-Eskalation. Der größte einzelne Kostenhebel. Halten Sie sich an einen Override („alles auf Opus“, „Sonnet für alles“).

Token-Ökonomie – die Flotte günstig betreiben

Die Kosten einer langen Ausführung sind ~83% Context-Cache-Read pro Turn, ~16% Output – Sie bezahlen für Context-Volumen × Turns, nicht fürs Denken. Wenden Sie diese Regeln an; vollständige Begründung + Messung in references/token-economics.md.

Gemessen an einem echten 19-Merge-Durchlauf (ein .NET/Blazor-Repo, N=3, 21 Worker-Sessions, 863M Tokens): 224 Turns/Session · Context 30K → 350K · 181K durchschnittlicher Context pro Turn · 0.55 Tool-Aufrufe pro Turn. Cache-Read war 98.3% der Tokens. Kosten = Σ über Turns der Context-Größe, daher kosten späte Turns ~10× frühe und die Turn-Anzahl ist superlinear – sie treibt beide Faktoren gleichzeitig. Rangieren Sie Hebel nach diesem Maßstab, nicht nach Intuition.

Diese Überschrift zählt Worker-Sessions – und der Orchestrator war ein Drittel der Rechnung. Wenn Sie das Transkript des Supervisors in dieselbe Aufstellung einbeziehen: eine Session, 551 Assistant-Nachrichten, ~210K durchschnittlicher Context pro Nachricht, 33% der listenäquivalenten Kosten des Durchlaufs – mehr als jede Top-Tier-Worker-Session zusammen – und es hat nie einmal kompaktiert über alle 19 Merges hinweg. Die Worker-Ausgaben sind ähnlich verzerrt: die Top 3 von 37 Worker-Sessions waren 32% aller Worker-Kosten, und die schlechteste war ein Issue mit effort: medium auf der mittleren Stufe, sodass weder Label noch Stufe es vorhersagten. Beide Messungen und die beiden gezählten Budgets, die sie begrenzen, befinden sich in references/token-economics.md § Sessionlänge.

1. Teilen Sie jeden Worker in zwei Unter-Agenten auf: implementieren, dann zusammenführen – der eine Hebel, der nachweislich funktioniert hat. A/B-verifiziert, ~11% aller Worker-Tokens. Phase 1 (/auto-dev-worker <N>) stoppt bei einem bereiten PR; Phase 2 (/auto-dev-merge <PR>) führt ihn in einem frischen Context zusammen.

Merge-Phase	Turns	Durchschn. Context/Turn	Cache-Read
vorher (18 Worker, innerhalb der Implementierungs-Session)	27 Durchschn.	247K	6.6M pro Worker
nachher (v2 Phase 2, frische Session)	24	71K	1.7M

Fast identische Turn-Anzahlen, daher ist der Context pro Turn der ganze Unterschied: −74% in der Merge-Phase, ≈11% der gesamten Worker-Ausgaben. Übergeben Sie die PR-Nummer zwischen den Phasen über eine Datei, die der Phase-1-Prompt benennt (Fallback: Parsen der Berichtszeile, dann gh pr list --head). Bonus: Beide Post-Vervollständigungs-Probleme, die im Basis-Durchlauf beobachtet wurden, traten in den späten Turns einer langen Session auf – kürzere Sessions verkeilen sich weniger.

2. Tool-Aufruf-Batching – AUSPROBIERT UND HAT NICHT FUNKTIONIERT. Erwarten Sie keinen Gewinn hier. Eine harte Batching-Regel mit Beispielen wurde zum Worker-Prompt hinzugefügt und A/B-gemessen: Dichte ging von 0.556 → 0.537 Aufrufen pro Turn (Phase 1) – d.h. keine Änderung. Behalten Sie die Regel (sie kostet nichts), aber budgetieren Sie keine Einsparungen dafür. Die Diagnose: Eine Dichte unter 1.0 bedeutet nicht, dass Aufrufe, die gebatcht werden könnten, es nicht werden. ~45% der Turns machen keinen Tool-Aufruf – sie sind Argumentations-/Erzählungs-Turns – und der Rest sind echt sequentiell (edit → build → Fehler lesen → beheben). Der wiederherstellbare Abfall sind Turns, die keinen Tool-Aufruf produzieren, was ein Problem der Ausgabe-Ausführlichkeit ist, kein Batching-Problem. Wenn Sie dies angehen, greifen Sie die Ausführlichkeit an (Denklänge, Erzählung zwischen Schritten), und messen Sie Aufrufe/Turn, um zu überprüfen, ob Sie sie bewegt haben.

3. Halten Sie große Befehlsausgaben aus dem Context heraus – gemessen 4.262 Tokens → ~2 pro vollständigem Testlauf. Vollständige dotnet test-Ausgabe ist ~17K Zeichen und wird bei jedem späteren Turn erneut gelesen. Anordnung: Protokollieren Sie in eine Datei, setzen Sie nur EXIT + Zählwerte in den Context, greppen Sie die Datei nur bei Fehlschlag. Verbieten Sie explizit, den Befehl durch tail/head zu leiten – das beschneidet die Beweise, während es trotzdem Turns kostet. Ehrlicher Umfang: Die Reduktion pro Durchlauf ist exakt und verifiziert, aber der aggregierte Gewinn hängt davon ab, wie oft ein Worker die Suite ausführt. Das größte einzelne Bash-Ergebnis fiel im A/B von 25,2K → 10,5K Zeichen, während das gesamte Tool-Ergebnisvolumen pro Turn sich kaum bewegte (722 → 710 Zeichen) – weil das A/B-Issue eine Dokumentationsaufgabe war, die selten Tests ausführt. Erwarten Sie den wahren Ertrag bei testlastigen Issues.

4. Stufen Sie das Modell auf die Aufgabe ab – real, aber stufenabhängig, pro token-economics.md: schwach zwischen mittel und klein ($0,419/Mtok vs $0,168/Mtok ≈ 2,5×); stark zwischen oben und mittel ($2,376/Mtok vs $0,419/Mtok ≈ 5,7×). Lohnt sich für bereichsübergreifende Arbeit; weniger wirkungsvoll für Routine-Bugs. Routen Sie nach Issue-Labels (passen Sie Namen an das kleine/mittlere/obere Trio der Laufzeit an, z.B. Haiku/Sonnet/Opus):

Issue-Form (nach Label)	Stufe
docs/templates/manifest, Format & Snapshot-Regenerierung, priority:low+effort:S Einzeiler-Guards	klein (z.B. Haiku)
die meisten Bugs: Emitter/Validator/Parser-Guards, Studio TS, CLI, LSP – effort:S/M; große Issues standardmäßig	mittel (z.B. Sonnet)
eine niedrigere Stufe konnte dieses Issue nicht grün machen	oben (z.B. Opus), reaktive Eskalation (einmal)
bereichsübergreifend (viele Bereiche/Emitter), mehrdeutig/Design – Arbeit, von der ein Maintainer weiß, dass sie schwierig ist	oben (z.B. Opus), prädiktiv als letztes Mittel

Der Orchestrator (Sie) bleibt auf dem oberen Modell, aber halten Sie seinen Context pro Turn klein (Hebel 2).

5. Verkleinern Sie, was jeden Turn erneut gelesen wird.

• Trimmen Sie die feste Präambel – sie wird auf jedem Turn jedes Workers bezahlt. CLAUDE.md mit 44KB (~11K Tok) kostete 52M Tokens in einem Durchlauf aus einer einzigen Datei; verschieben Sie Referenzmaterial für Deploy/Secrets/kubectl in verlinkte Dokumente und hinterlassen Sie einen Zeiger.
• Keine TaskList pro Issue – sie wächst unbegrenzt und injiziert sich jeden Turn neu. Die Zustandsdatei ist Ihr einziges Arbeitsgedächtnis.
• Komprimieren Sie bewusst, in einem gezählten Rhythmus – nicht nach Gefühl. Der Rhythmus-Ganzzahl hat ein Zuhause, references/token-economics.md § Die zwei Budgets; Schritt 4 feuert sie vom Merge-Zähler der Zustandsdatei ab, demselben gezählten Feld, das der Neuvermessungs-Rhythmus bereits verwendet. Wiederholen Sie die Zahl hier nicht – tests/auto-dev-cost-budgets/test.sh schlägt fehl, wenn Sie es tun. Warum gezählt: Kosten sind Σ(Context × Turns), daher ist der Schwanz eines Durchlaufs superlinear, und die Regel, die dies ersetzt – ein /context-Prozentsatz oder ein Rhythmus, der locker genug war, um innerhalb eines 19-Merge-Durchlaufs nie zu feuern – hat nichts begrenzt und $213 in einer einzigen Session gekostet. Komprimieren Sie immer mit einer Fokus-Anweisung, z.B. /compact behalte den Slot→Issue/PR-Map, Merge-Zähler, Warteschlangen-Reihenfolge, erfasste Folgemaßnahmen. Erste Aktion nach jeder Komprimierung / /clear / loop-Wiederzündung: lesen Sie die Zustandsdatei erneut.
• Halten Sie die ABSCHLUSSBERICHTE der Worker knapp – sie werden bei jedem späteren Abgleich-Turn erneut gelesen.
• Delegieren Sie schwere Lesevorgänge an Einweg-Explore-Unter-Agenten – der Datei-Dump stirbt mit dem Unter-Agenten, anstatt Ihren Context zu belasten.
• Starten Sie die SUPERVISOR-Session schlank – Unter-Agenten erben den MCP-Satz des Supervisors, daher reitet jeder Server, der mit Ihrer Session verbunden ist, auf jedem Turn jedes Workers. Die Entfernung von MCP pro Worker ist nicht mehr verfügbar (das Agent-Tool hat keine MCP-Konfiguration pro Start); trimmen Sie es einmal, wo Sie starten.

6. Machen Sie weniger Turns (jeder Round-Trip liest den gesamten Context erneut).

• Batch unabhängige Tool-Aufrufe in einen Turn (parallele Reads/Greps/gh).
• Lassen Sie Skripte Abfrage+Klassifikation zusammenfassen – scripts/survey.sh, scripts/reconcile.sh.
• Pollen Sie nicht in einem kurzen Rhythmus, es sei denn, ein Merge steht unmittelbar bevor – ein unnötiges Aufwachen liest alles erneut, und nach Ablauf der ~5-minütigen Cache-TTL bezahlt es einen vollständigen Cache Write (1,25×), keinen Read (0,1×).
• Begrenzen Sie die Session, nicht nur den Turn. Batching wurde A/B-getestet und hat sich nicht bewegt (Hebel 2), daher ist die Optimierung pro Turn nahezu erschöpft und die Sessionlänge ist die verbleibende Variable – die Top 3 von 37 Worker-Sessions waren 32% aller Worker-Kosten, und weder das Aufwands-Label noch die Stufe sagten voraus, welche drei. Phase-1-Worker tragen daher ein Turn-Budget (die Ganzzahl lebt in references/token-economics.md § Die zwei Budgets, nicht hier) und übergeben bei Erreichen mit STATUS: PARTIAL; Schritt 4 setzt sie in einem frischen Unter-Agenten fort, was die Ersparnis ausmacht – eine SendMessage-Fortsetzung behält den Context, den das Budget zu verwerfen gedenkt. Dies ist der Mechanismus von Hebel 1, der eine verifizierte Verbesserung in diesem Abschnitt, angewendet an einer Längen-Naht anstelle einer Phasen-Naht.

Messen Sie es – behaupten Sie nie, dass ein Hebel funktioniert, ohne einen A/B. Drei Skripte, alle nehmen ein Verzeichnis von Session-.jsonl-Transkripten:

• scripts/usage_report.py – Tokens + $-Äquivalent nach Modell. Verfolgen Sie Tokens/Merge und $/Merge. ⚠️ Es aggregiert das GESAMTE Projektverzeichnis einschließlich vergangener Durchläufe – symlinken Sie einen Durchlauf zuerst in ein temporäres Verzeichnis, wobei Sie das Layout beibehalten: die Supervisor-Session <sid>.jsonl plus ihr <sid>/subagents/-Verzeichnis (<proj>/<sid>/subagents/agent-*.jsonl ist der Ort, an dem jedes Worker-Transkript lebt, also sitzt die Flotte eines Durchlaufs unter einer ID – wählen Sie die ID aus der Zustandsdatei oder gh-Zeitstempeln; mtime ist unzuverlässig). Ein flacher Haufen von agent-*.jsonl- Symlinks wird als 0 sub-agent gelesen und paart nichts.
• scripts/analyze_cache.py – Turns/Session, Context zu Beginn vs. Spitze, durchschnittlicher Context pro Turn und Tool-Ergebnisvolumen nach Tool. Hier sehen Sie, warum eine Session teuer ist.
• scripts/measure_phase2.py – paart die Phase-1- und Phase-2-Unter-Agenten-Transkripte jedes Issues (anhand des ISSUE: ihrer Berichtszeilen) und teilt die Kosten in Implementierungs-Phase vs. Merge-Phase auf; bei einem Transkript vor Version 2.0 findet es stattdessen den In-Session-Merge-Übergabe-Turn. Dies hat Hebel 1 bewiesen.

Zwei Metriken tragen das meiste Signal: durchschnittlicher Context pro Turn (sind späte Turns aufgebläht?) und Tool-Aufrufe pro Turn (machen Turns überhaupt Arbeit? Baseline ~0,55 – siehe Hebel 2).

Wie es funktioniert

        ┌─────────────────────── auto-dev (Sie, der Supervisor) ───────────────────────┐
        │  Zustandsdatei: Warteschlange (klein→mittel), in Bearbeitung befindliche Slots, erledigt, erfasst          │
        │  bei jedem Signal → Abgleich mit GitHub → Ende-zusammengeführt + nachfüllen → N laufend halten  │
        └───────────────────────────────────────────────────────────────────────────────┘
            │ Dispatch (bereichsisoliert)        ▲ strukturierter Bericht / Leerlauf-Benachrichtigung
            ▼                                 │
   Worker A ─ implement-issue → [bereit] ⇢ FRISCHER Unter-Agent ─ merge-pr ─ Bericht ┐
   Worker B ─ implement-issue → merge-pr ─ Bericht ─┤  N Hintergrund-Agenten, einer pro Issue,
   Worker C ─ implement-issue → merge-pr ─ Bericht ─┘  bei Merge ausgemustert, aus der Warteschlange ersetzt

Worker sind Hintergrund-Unter-Agenten, die mit dem Agent-Tool gestartet werden. Kommunizieren Sie über ihre strukturierten Berichte – die letzte Nachricht eines Unter-Agenten ist sein Bericht, der Ihnen bei der Rückkehr zugestellt wird – über Leerlauf-Benachrichtigungen und durch SendMessage an einen noch laufenden; lesen Sie niemals ihre rohen Transkriptdateien (<proj>/<your-session>/subagents/agent-*.jsonl) – die Ausgabe eines Workers ist ein riesiges Protokoll, das Ihren Context sprengen wird. Verlassen Sie sich auf den Bericht

…

[gekürzt für die Übersetzung]