Wenn ich zwischen AI-Coding-Werkzeugen wechsle, ist das eigentliche Problem oft nicht die Qualität des generierten Codes. Ich muss dem neuen Tool erst wieder erklären, warum wir eine Architektur gewählt haben, auf welchem Branch gearbeitet wird, welche Tests wirklich bestanden wurden, welcher Pull Request noch offen ist und was der vorherige Agent überhaupt tun durfte.

Deshalb habe ich begonnen, diesen leicht verlorenen Projektkontext in GitHub statt nur im Chat zu hinterlegen. Ob Codex, Claude Code, Cursor oder ChatGPT im Browser: Die nächste Sitzung liest zuerst Issues, Branches und PRs. Ein Tool mit Schreibrechten kann in seinem eigenen Branch committen; eine reine Leseintegration kann zumindest eine Prüfung vornehmen.

Das nenne ich GitHub-first: Werkzeuge sind austauschbar, der technische Projektzustand darf nicht mit einem Chatfenster verschwinden. Für diesen Zweck braucht es keinen ständig laufenden Koordinations-Bot. Selbst mit dem Smartphone kann ich den nächsten Arbeitsschritt übergeben.

Chat-Gedächtnis ist nicht dasselbe wie Projektkontext

An Projekten wird über Tage gearbeitet. Agent B weiß möglicherweise nicht, warum A einen Entwurf verworfen hat. Eine neue Sitzung hält die grünen CI-Ergebnisse eines alten Commits für den Status des aktuellen HEAD. Zwei Entwickler bearbeiten dieselbe Datei und beide glauben, sie seien zuständig. Zehn Seiten aus der bisherigen Unterhaltung in den nächsten Prompt zu kopieren, hilft kurzfristig – verstärkt aber die Abhängigkeit vom Sitzungsverlauf eines bestimmten Anbieters.

Ich unterscheide daher Gesprächsgedächtnis und überprüfbare Engineering-Fakten. GitHub überträgt weder die privaten Dialoge noch die internen Überlegungen eines Modells. Speichern lassen sich aber vier Arten von Zustand:

• Projektregeln: AGENTS.md, README und Architekturhinweise. Nicht jedes Tool liest AGENTS.md automatisch.
• Auftragsidentität: Issue, Task-ID, Plan, Verantwortliche, optionaler Checkpoint, erledigte und noch ungeprüfte Arbeit.
• Codeversion: main, Feature-Branches, Commit- und Git-Blob-SHAs, insbesondere der tatsächlich aktive Branch.
• Review und Freigabe: PR-Diff, Review-Kommentare, ACK, CI-Läufe für den exakten HEAD und Merge- oder Deployment-Belege.

Das muss keine neue riesige JSON-Datenbank werden. Git verwaltet Code, Issues und PRs dokumentieren Entscheidungen, ein Checkpoint hält bei Bedarf die nächste Aktion fest. Geheimnisse, kurzfristige Model-Caches und hochfrequente Locks gehören nicht in das Repository.

Statt den ganzen Chat zu kopieren, gebe ich einer neuen Sitzung zunächst diesen kurzen Arbeitsauftrag. Die Vorlage bleibt bewusst auf Englisch, damit sie in unterschiedlichen Tools wiederverwendbar ist:

You are the developer for this task. Recover project state read-only first.
Repository: OWNER/REPO
Task: Issue #N, linked PR #M, task ID TASK_ID

Read repository rules, the plan, checkpoint, current feature-branch HEAD,
PR diff, the latest applicable review comments, and checks for that HEAD.
Explain the authorized actions, verified work, and remaining gates.
Stop and report if the branch moved, permissions differ, or orders conflict.
Do not merge, deploy, or change production settings without separate approval.

Für Solo-Entwickler reicht anfangs die leichte Variante: README oder AGENTS.md, ein Issue beziehungsweise PR und die letzten Commits. Einen Checkpoint und das strengere Order/ACK-Protokoll braucht man erst bei langen Aufgaben, parallelen Schreibern oder unabhängiger Abnahme.

Ein GitHub als Zustandsbasis für mehrere AI-Einstiege und Branches

Die Architektur lässt sich auf folgenden Ablauf reduzieren. Die animierte SVG-Grafik am Artikelanfang zeigt denselben Zusammenhang:

Phone / browser / local IDE / cloud coding agent
                       |
             Read GitHub task facts
                       |
       AGENTS.md · Issue · plan · checkpoint
                  branch · PR
                       |
              Check permission scope
                       |
         Feature branch A     Fix branch B
                  |                |
                commit           commit
                  |                |
                 PR A             PR B
                     \           /
                   review + CI per HEAD
                           |
                  Human approval to merge
                           |
                          main

Die genannten AI-Einstiege haben keineswegs automatisch dieselben GitHub-Rechte. Manche Integrationen können nur suchen und lesen, andere Coding Agents bearbeiten Dateien in einer eigenen Laufzeit und erstellen Branches oder PRs. Stand der Beschreibung: Oktober 2026. Damit behaupte ich nicht, die aktuellen Fähigkeiten jedes genannten Produkts einzeln getestet zu haben. Prüfe die tatsächliche Konto- und Integrationsfreigabe für read, write, comment, merge und deploy.

Ein Cloud-Agent kann Feature A bearbeiten, eine Browser-Sitzung eine Dokumentationsänderung vorschlagen und lokales Codex einen API-Fix schreiben. Sie teilen Projektregeln, arbeiten aber in feature/A, docs/B und fix/C getrennt und führen ihre Ergebnisse in PRs zusammen.

Getrennte Branches verhindern keine logischen Konflikte. Zwei Änderungen können dieselbe Schnittstelle oder Abhängigkeit betreffen. Deshalb ist ein tatsächlicher Schreiber pro Aufgaben-Branch sinnvoll. Vor einem Merge prüfe ich gemeinsame Basis, betroffene Dateien, neueste CI und gegebenenfalls Integrationstests. GitHub beschreibt die Mechanik in der Pull-Request-Dokumentation; geschützte Branches können Reviews und Checks verpflichtend machen.

Mehrere lokale Arbeitsverzeichnisse sind ein anderes Thema: Dafür nutze ich bei Bedarf Git Worktree, erklärt im Worktree-Beitrag. Hier geht es darum, wie unterschiedliche AI-Tools denselben GitHub-Auftrag übernehmen und ihre Änderungen wieder zusammenführen.

Werkzeugwechsel: zuerst Issue, Branch und PR verifizieren

Ein Prompt liefert nur den Einstiegspunkt. Der neue Agent muss aus der Quelle beantworten können: Welcher HEAD ist aktuell? Was hat die vorige Person geliefert? Wer darf jetzt schreiben?

Für den Einstieg genügt eine kleine AGENTS.md im Projektstamm. Sie sollte zu den tatsächlichen Architektur- und Testanweisungen führen, nicht eine zweite vollständige Projektdokumentation werden:

# AGENTS.md

- Stack and architecture: see README.md and docs/architecture.md
- Install and test: follow the current commands in README.md
- Task entry points: GitHub Issue and linked PR
- Optional state: tasks/<TASK_ID>/checkpoint.json
- Before editing: verify task ID, branch, and live HEAD
- Prefer one writer for each feature branch
- Merges and deployments need separate approval

Bei länger laufenden Aufgaben ergänze ich optional eine checkpoint.json. Die Schlüsselnamen stammen aus einem echten Projekt, während alle IDs und SHAs hier absichtlich Platzhalter sind:

{
  "task_id": "TASK_ID",
  "phase": "P2",
  "status": "IN_PROGRESS",
  "branch": "feat/TASK_ID",
  "commit_sha": "REPLACE_WITH_LAST_VERIFIED_40_HEX_SHA",
  "pr": "https://github.com/OWNER/REPO/pull/N",
  "verification": { "merge": { "status": "NOT_AUTHORIZED" } },
  "next_action": "Read current HEAD and review comments before resuming"
}

Dieses Beispiel ist weder die private Originaldatei noch ein vollständiges universelles Schema. Ein Checkpoint muss nicht nach jedem Commit aktualisiert werden. Für kleine Aufgaben reichen Issue- und PR-Kommentare; ich aktualisiere die Datei an wichtigen Übergaben, Prüfmeilensteinen oder bei Blockaden.

Eine wichtige Falle ist die SHA-Selbstreferenz. checkpoint.commit_sha bezeichnet den zuletzt verifizierten Code-Commit, nicht zwingend den Commit mit der Checkpoint-Datei und auch nicht automatisch den Live-HEAD. Wurde der Code bei Commit A geprüft und der Checkpoint später mit Commit B gespeichert, darf die Datei auf A zeigen. Sie kann aber nicht vor dem Erstellen von B dessen zukünftigen Hash enthalten. Ein fester Versatz von genau einem Commit ist daraus nicht abzuleiten.

Der nächste Agent muss den aktuellen Branch-HEAD erneut über GitHub lesen und mit dem dokumentierten Ausgangspunkt abgleichen. Zwei unterschiedliche SHAs bedeuten nicht automatisch einen Fehler. observed_head_sha und new_head_sha im ACK bezeichnen die geprüfte alte und die neu übergebene Version. Ob eine Order wegen eines veralteten HEAD abgewiesen werden muss, ist eine eigene Regel.

AGENTS.md beschreibt Regeln, Issue/PR hält die Diskussion fest und ein Checkpoint ergänzt bei Bedarf den Arbeitsstand. Clients, die AGENTS.md nicht automatisch laden, sollten dazu explizit aufgefordert werden.

Den strengeren Übergabekern aus meinem eigenen Projekt habe ich als Open Source veröffentlicht. Für die leichte Variante ist er nicht nötig; wer Order/ACK-Bindungen, die HEAD-Veraltung und Offline-Validierung genau sehen möchte, kann Quellcode und Tests lesen:

vxime/conversation-memory-hub

Das Repository enthält Protokoll, Validatoren und Beispiele. Es ist kein gehosteter Dienst, der andere AI-Chats automatisch weckt oder deinen Projektzustand spiegelt. Die wirklichen Aufgaben, Branches und PRs bleiben in deinem GitHub-Repository.

Ein echter PR: FIX_REQUIRED, ACK und unabhängige Nachprüfung

Architekturdiagramme können trügerisch beruhigend wirken: Zwei AIs antworten „verstanden“, also halten wir die Übergabe für erfolgreich. Ich habe deshalb einen realen Dokumentations-PR aus einem privaten Projekt nachvollzogen. Reviewer B beanstandete zwei Punkte, Entwickler A korrigierte den Text und meldete einen neuen HEAD zurück. B prüfte diese neue Version, bevor die Arbeit weitergehen durfte. Der spätere Merge war eine separate menschliche Entscheidung.

Die Begriffe FIX_REQUIRED, ACK und ADVANCE sind projektinterne Kommentar-Konventionen, keine nativen GitHub-PR-Status. Sie stehen für Korrekturauftrag, Rückmeldung mit neuem Stand und Freigabe der nächsten bereits autorisierten Schritte nach neuer Prüfung. STALE_ORDER bezeichnet eine Anweisung, die an einen alten HEAD gebunden ist.

Der PR änderte lediglich einen Plan für ein lesendes Runner-Audit. Er installierte keinen Runner. F-001 betraf eine Lücke in der Audit-Anweisung: Sie sollte riskante Kommentar-Trigger wie issue_comment erkennen, listete mit ihrem Befehl aber nur die Dateinamen der GitHub-Actions-Workflows auf.

# Original plan: names only; the YAML triggers remain invisible.
gh api "repos/OWNER/REPO/contents/.github/workflows" --jq '.[].name'

Aus einem Dateinamen lässt sich nicht ablesen, ob die YAML-Datei auf oberster Ebene bei on: ein issue_comment enthält. F-002 korrigierte einen falschen Abschnittsverweis. Die überarbeitete Planung fixierte eine Audit-SHA, las die tatsächlichen Trigger und prüfte zum Schluss, ob HEAD gewandert war. Den Unterschied zwischen beiden Dokumentversionen habe ich angesehen; die Actions-Event-Dokumentation erklärt die zugrunde liegende Gefahr.

A kommentierte anschließend ACK und den neuen HEAD im ursprünglichen PR. B überprüfte beide Korrekturen gegen diesen HEAD und erteilte erst dann ADVANCE. Diese zwei AI-Sitzungen wurden durch einen Menschen weitergeführt. Weder wurde ein Chat automatisch geweckt, noch wurde decideResume() als GitHub-Actions-Gate oder lokaler Git-Hook installiert. Für einfache Übergaben reichen normale PR-Kommentare mit Versionsangabe.

Die wesentlichen Felder des tatsächlichen ACK-Kommentars, ohne private IDs und Hashwerte:

{
  "protocol": "ai-supervisor/ack/v1",
  "task_id": "TASK_ID",
  "order_id": "REPLACE_WITH_ORDER_ID",
  "decision_received": "FIX_REQUIRED",
  "observed_head_sha": "REPLACE_WITH_OLD_HEAD",
  "new_head_sha": "REPLACE_WITH_NEW_HEAD",
  "executed": [
    "F-001: Inspect workflow triggers at a pinned SHA",
    "F-002: Correct the audit plan's section reference"
  ]
}

Das Originalprotokoll enthält weitere Pflichtfelder und Integritätsprüfungen. Entscheidend ist, dass A den alten geprüften HEAD und den neuen gelieferten HEAD festhält. B muss nicht blind einer Nachricht „erledigt“ vertrauen, sondern kann die tatsächliche Änderung nachprüfen.

Der PR änderte nur Dokumentation, hatte keinen erfolgreichen CI-Nachweis für den betreffenden HEAD und führte kein Produktions-VPS-Audit aus. Nachgewiesen ist eine überprüfbare Review-Übergabe, kein autonomes Gesamtsystem.

STALE_ORDER: Anweisungen für einen alten HEAD müssen stoppen

Eine Order ist ein strukturierter Auftrag, den B in einen Issue-/PR-Kommentar schreibt. Er bindet Task-ID, Ziel-Branch, observed_head_sha, Befunde und erlaubte beziehungsweise verbotene Operationen. Das order_id im ACK verweist auf diesen Auftrag.

In einem separaten Negativtest war die Order an einen alten main-HEAD gebunden. Danach änderte sich das Repository. Beim erneuten Lesen sollte A mit STALE_ORDER stoppen, statt die frühere Anweisung auf neueren Code anzuwenden.

Ich habe die archivierte Order, den späteren HEAD und die Staleness-Prüfung in decideResume() direkt kontrolliert. Damals meldete A, dass es angehalten hatte. Dieses Ergebnis wurde allerdings von einem Menschen übertragen und nicht von A selbst als unabhängiges GitHub-ACK geschrieben. Es ist ein nützlicher Negativversuch, aber kein End-to-End-Test über sämtliche Clients hinweg.

Die Regel ist klar: B bindet Task, Branch, HEAD und Berechtigungen; A liest vor der Ausführung den aktuellen HEAD. Hat er sich geändert, wird gestoppt und B muss die neue Version beurteilen. Eine früher korrekte Anweisung kann für eine andere Codeversion falsch sein.

Das erklärt auch meinen Wunsch nach unabhängigem Review. Ein plausibler Diff aus einem Agenten und eine Prüfung des echten neuen HEAD durch eine andere Sitzung sind zwei unterschiedliche Fakten. Zum allgemeinen Agent-Owner- und Zustandsdesign gibt es meinen AI-Agent-Orchestration-Beitrag.

Zusammenarbeit vom Smartphone ersetzt keine Rechenumgebung

Praktisch finde ich, dass ich nicht nur zum Verfolgen eines Vorgangs einen Mac dauerhaft laufen lassen oder einen ständigen Koordinations-Bot betreiben muss. Mit einem berechtigten Client kann ich unterwegs PRs lesen, Review-Kommentare prüfen und den nächsten Schritt übergeben. Wirkliche Codeänderungen, Builds und Tests benötigen weiterhin eine autorisierte Laufzeit: Cloud-Agent, Runner oder lokales System.

Bei den Kosten trenne ich zwei Rechnungen: Wiederholte Kontexterklärungen und Bot-Wartung kosten potenziell Zeit und Betrieb, während Modellinferenz, Chat-/Codex-/API-Kontingente und CI eigenständige Kosten verursachen. Einen vergleichbaren Token-Kostentest habe ich nicht durchgeführt und behaupte daher keine ausgedachte prozentuale Einsparung.

Mein Blog hat außerdem eine GitHub-Actions-zu-Self-hosted-Runner-Pipeline. Im Beitrag über geräteübergreifende Entwicklung und Deployment geht es um die spätere Veröffentlichung. Diese Seite behandelt den Schritt davor: Wie erkennen wir bei einem Tool-, Geräte- oder Personenwechsel, dass tatsächlich derselbe Auftrag fortgesetzt wird?

Für eine risikoarme Ein-Datei-Änderung reicht oft ein Agent mit einem Branch. Über mehrere Tage, Tools und Personen werden Checkpoints, Branch-Zuständigkeiten, unabhängige Reviews und klare Berechtigungen wertvoller. GitHub-first bedeutet für mich nicht, dass AI-Tools plötzlich ein gemeinsames Gedächtnis besitzen, sondern dass die technischen Fakten an einem Ort bleiben, an dem der nächste Beteiligte sie wiederfinden kann.