ChatGPT · End to end: vom Issue zum gemergten Pull Request

In Ihrem GitHub-Repo liegt ein Issue, und am Ende dieses Loops wollen Sie einen gemergten Pull Request, der es schließt, wobei ein Mensch den Diff als letzte Instanz prüft. Das ist der ganze Job. Codex ist dafür gebaut, den Großteil davon zu erledigen, während Sie die Kontrolle behalten.

Diese Lektion geht den Loop konkret durch: das Issue aufgreifen, Codex einen Branch anlegen und implementieren lassen, die Tests ausführen, den PR öffnen, reviewen und mergen. Die Disziplin dahinter ist schlicht: saubere Branches, kleine Diffs und ein Review, das ein echter Checkpoint ist und kein bloßes Durchwinken.

Wo Codex in diesem Workflow sitzt

Codex ist der Software-Engineering-Agent von OpenAI. ErErDas Verhältnis von Interaktionen (Likes, Kommentare, Shares) zur Reichweite eines Inhalts. Zeigt, wie stark die Zielgruppe reagiert, gemessen an der Zahl der Personen, die den Inhalt gesehen haben.Vollständige Definition ansehen → liest Ihr Repo, bearbeitet Dateien, führt Befehle aus und pusht Branches. Sie erreichen ihn an mehreren Stellen:

• Codex in ChatGPT (die Cloud-Version), die jede Aufgabe in einer isolierten Sandbox ausführt.
• Die Codex CLI in Ihrem Terminal.
• Die Codex-IDE-Extension für VS Code und dessen Forks wie Cursor.
• GitHub selbst, wo Sie @codex in einem Pull Request erwähnen kkDie durchschnittliche Zahl neuer Nutzer, die jeder bestehende Nutzer über Empfehlungen generiert. Über 1,0 verstärkt sich das Wachstum selbst und wird exponentiell.Vollständige Definition ansehen →önnen.

Er ist über die Codex-GitHub-Integration mit GitHub verbunden und kann PRs daher direkt öffnen und aktualisieren.

Das mentale Modell: Codex ist ein Teammitglied, das die mechanische Arbeit an einer Änderung schnell erledigt, aber nie seinen eigenen Code merged. Sie legen den Scope fest, er erzeugt einen Diff, Sie reviewen und mergen. Die Branch Protection von GitHub setzt diese Grenze durch, richten Sie sie also zuerst ein.

LeitplankenLeitplankenRegeln und Kontrollen, die ein KI-System in sicheren, rechtskonformen und markengerechten Grenzen halten und unerwünschte Ausgaben blockieren.Vollständige Definition ansehen → setzen, bevor Sie anfangen

Aktivieren Sie im Repo Branch Protection (oder ein Ruleset) für Ihren Default-Branch:

• Pull Request vor dem Merge verlangen.
• Mindestens ein genehmigendes Review verlangen.
• Bestandene Status Checks (Ihre CI) verlangen.

Jetzt kann selbst ein Agent, der Code pusht, diesen nicht ohne grünen Build und menschliche Freigabe einspielen. Das ist die wichtigste einzelne Einstellung, wenn ein Agent in einem echten Repo arbeiten soll.

Schritt 1: Das Issue aufgreifen

Starten Sie mit einem echten, sauber abgegrenzten Issue. Codex arbeitet am besten, wenn sich das Issue wie eine Spezifikation liest. Vergleichen Sie:

Schwach: „Login ist unzuverlässig.“

Stark: „Nutzer mit E-Mail-Adressen, die einen +-Alias enthalten (z. B. sam+test@x.com), werden bei der Registrierung abgelehnt. Erwartet: RFC-konforme Adressen mit + werden akzeptiert. Siehe validateEmail in src/auth/validate.ts. Zuerst einen fehlschlagenden Test hinzufügen.“

Die starke Version nennt die Datei und das erwartete Verhalten und verlangt einen Test. Allein diese Vorgabe halbiert den Diff häufig.

Verweisen Sie Codex auf das Repo und fügen Sie die Aufgabe ein. Liegt im Root Ihres Repos eine Datei AGENTS.md, liest Codex sie als dauerhafte Anweisungen: wie Tests laufen, welcher Code-Stil gilt, was nicht angefasst wird. Sie können in Unterordnern weitere AGENTS.md-Dateien für paketspezifische Regeln anlegen. Behandeln Sie diese Datei als die dauerhafte Version Ihrer Custom Instructions für diese Codebasis.

# AGENTS.md
## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Conventions
- TypeScript strict mode. No `any`.
- One logical change per PR. Keep diffs under ~150 lines.
- Never edit files under `src/generated/`.

Schritt 2: Codex einen Branch anlegen lassen

Lassen Sie Codex nicht auf main arbeiten. Weisen Sie ihn an, einen Branch mit einem klaren, auf das Issue bezogenen Namen anzulegen:

codex "Fix issue #214: accept + aliases in validateEmail.
Branch: fix/214-email-plus-alias.
Write a failing test first, then make it pass."

Gute Branch-Namen sind langweilig und nachvollziehbar: fix/214-email-plus-alias, feat/187-csv-export. Mit der Issue-Nummer im Branch-Namen kann jeder den Code bis zu der Diskussion zurückverfolgen, aus der er entstanden ist. Ein Branch, ein Zweck, nach dem Merge leicht zu löschen.

Codex legt los, und Sie sehen, wie er Dateien liest, einen Plan erstellt und Befehle ausführt. Lassen Sie ihn laufen, aber lesen Sie den Plan, bevor er viel schreibt. Wirkt der Plan schon zu groß (er will für einen Einzeiler-Bug drei Module refaktorieren), stoppen Sie ihn und grenzen Sie den Scope sofort ein. Beim Review einzugrenzen kostet mehr.

Schritt 3: Die Änderung implementieren und testen

Die Reihenfolge zählt, und es lohnt sich, sie Codex gegenüber explizit zu machen: zuerst der fehlschlagende Test, dann der Fix. Das ist die Agent-Version von Test-Driven Development. Sie beweist, dass der Bug existiert, und dass Ihr Fix genau diesen Bug behebt und nicht etwas daneben.

Ein sauberer Loop für unser Beispiel mit Vitest:

// src/auth/validate.test.ts
import { describe, it, expect } from "vitest";
import { validateEmail } from "./validate";

describe("validateEmail", () => {
  it.each(["sam+test@example.com", "sam+news+promo@example.com"])(
    "accepts plus alias %s",
    (email) => {
      expect(validateEmail(email)).toBe(true);
    }
  );

  it("still rejects a bare plus", () => {
    expect(validateEmail("+@example.com")).toBe(false);
  });
});

Codex fügt den Test hinzu, führt pnpm test aus, sieht ihn fehlschlagen und bearbeitet dann validateEmail, bis die Suite grün ist. Weil er echte Befehle ausführt, bekommen Sie echten Output statt einer Vermutung, ob der Code funktioniert. Schlägt ein Test unerwartet fehl, iteriert er.

Achten Sie darauf, dass er nicht den Test „repariert“, damit er zum fehlerhaften Verhalten passt. Das ist ein klassischer Fehler von Agents, und genau deshalb haben Sie den fehlschlagenden Test vorab verlangt: Sie können den Test lesen und bestätigen, dass er das gewünschte Verhalten abbildet.

Wenn er fertig ist, berichtet Codex, was sich geändert hat und warum. Lesen Sie diese Zusammenfassung, aber verlassen Sie sich nicht auf sie statt auf den Diff.

Schritt 4: Den Pull Request öffnen

Lassen Sie Codex den PR von seinem Branch nach main öffnen. Eine gute, vom Agent verfasste PR-Beschreibung ermöglicht dem Reviewer eine Freigabe in wenigen Minuten:

## What
Accept email addresses with `+` aliases in `validateEmail`.

## Why
Closes #214. Aliased addresses are RFC 5321 valid; we were rejecting them.

## Changes
- `src/auth/validate.ts`: widened local-part regex to allow `+`.
- `src/auth/validate.test.ts`: added alias-accept and bare-plus-reject cases.

## Testing
- `pnpm test` passes (3 new cases).

Beachten Sie Closes #214. Dieses Schlüsselwort verknüpft den PR mit dem Issue und schließt das Issue, sobald der PR gemergt wird. Ihr Board bleibt korrekt, ohne einen zusätzlichen Klick.

Der PR stößt Ihre CI an. Weil Sie Status Checks verlangt haben, bleibt der Merge-Button deaktiviert, bis der Build durchläuft. Ihre erste automatisierte Kontrolle erledigt ihre Arbeit, bevor überhaupt ein Mensch draufschaut.

Schritt 5: Den Diff reviewen (die eigentliche Kontrolle)

Diesen Schritt delegieren Sie nie. Öffnen Sie den Tab Files changed und lesen Sie jede Zeile, als hätte ein Junior Engineer sie geschrieben, denn funktional hat das einer getan.

Worauf Sie bei Agent-generierten Diffs achten sollten:

• Scope Creep. Hat er nur angefasst, was das Issue erforderte? Neu formatierte Dateien, umbenannte fremde Variablen und Änderungen nach dem Motto „wenn ich schon mal hier bin“ blähen den Diff auf und verstecken die eigentliche Änderung. Bitten Sie Codex, alles Themenfremde zurückzunehmen.
• Die Regex oder Logik, die es „repariert“. Eine erweiterte Regex kann + akzeptieren und gleichzeitig Müll. Lesen Sie das tatsächliche Pattern, denn dort stecken subtile Sicherheits- und Korrektheitsfehler.
• Testqualität. Schlägt der Test ohne den Fix fehl? Prüft er das Richtige? Ein Test, der auch mit vorhandenem Bug besteht, ist schlechter als gar keiner.
• Secrets und Konfiguration. Stellen Sie sicher, dass kein Key hartkodiert und kein Env-Default geändert wurde.

Kleine Diffs machen das möglich. Ein PR mit 40 Zeilen bekommt ein echtes Review. Ein PR mit 600 Zeilen wird überflogen und durchgewinkt, womit die menschliche Kontrolle ihren Sinn verliert. Hat Codex etwas Großes produziert, bitten Sie ihn, die Änderung in zwei oder drei aufeinanderfolgende PRs aufzuteilen, die jeweils für sich reviewbar sind.

Sie können auch Review-Kommentare im PR hinterlassen und @codex taggen, damit er sie abarbeitet. Er pusht neue Commits auf denselben Branch, die CI läuft erneut, und Sie reviewen das Delta. Der Großteil der echten Zusammenarbeit passiert in diesem Kommentar-Loop.

Codex kann auch Code reviewen. Kommentieren Sie @codex review in einem PR oder aktivieren Sie automatische Reviews in den Codex-Einstellungen, dann markiert er wahrscheinliche Bugs. Betrachten Sie das als zweites Paar Augen vor Ihrem eigenen Durchgang. Es ersetzt nicht Ihre Freigabe, und die Branch Protection verlangt weiterhin einen Menschen.

Schritt 6: Mergen und aufräumen

Sobald die CI grün ist und Sie freigegeben haben, mergen Sie. Nutzen Sie für Agent-Arbeit bevorzugt Squash and merge. Der Branch kann ein Dutzend winziger Iterations-Commits enthalten („fix test“, „oops“, „lint“), und Squashing fasst sie zu einem sauberen Commit auf main zusammen, mit Ihrem PR-Titel als Nachricht.

Löschen Sie den Branch nach dem Merge. GitHub bietet direkt nach dem Merge einen Button dafür, und in den Repo-Einstellungen können Sie Auto-Delete aktivieren, damit sich alte Agent-Branches nie ansammeln. Das Issue schließt sich dank Ihrer Zeile Closes #214 automatisch. Issue rein, reviewte und getestete Änderung raus, saubere History.

Ein Hinweis zur Wahl der Oberfläche

Die Oberflächen eignen sich für unterschiedliche Aufgaben:

• Cloud-Codex (ChatGPT oder @codex auf GitHub) eignet sich am besten für asynchrone, in sich geschlossene Aufgaben. Zuweisen, weggehen, den PR reviewen, wenn er fertig ist.
• CLI und IDE-Extension eignen sich am besten, wenn Sie in Echtzeit zusehen und steuern, mit nicht committeten lokalen Änderungen arbeiten oder rein lokales Tooling nutzen wollen. Die IDE-Extension kann eine Aufgabe auch an die Cloud übergeben und das Ergebnis zurückholen.

Alle respektieren Ihre AGENTS.md. Die Codex-Dokumentation ist immer aktueller als jedes Tutorial, setzen Sie also ein Lesezeichen.

Warum dieser Loop skaliert

Codex fügt sich in einen Prozess ein, den es bereits gibt. Sie erfinden keine neue Merge-Policy für KI. Sie setzen einen Agent auf dieselbe Branch Protection, dieselbe CI und dieselbe Review-Kultur an, die Ihre menschlichen Entwickler nutzen, und der Agent übernimmt diese Leitplanken. Fehlschlagende Tests zuerst, kleine Diffs und verpflichtende menschliche Freigabe machen menschliche PRs sicher, und sie machen Agent-PRs aus denselben Gründen sicher.

Der Fehler, den Sie vermeiden sollten, ist Zeitdruck. Codex erzeugt Diffs schnell, und die Versuchung ist groß, ebenso schnell freizugeben. Widerstehen Sie dem. Die Review-Qualität sollte Ihr Engpass sein, denn das Review ist der einzige Schritt, der die plausible, aber falsche Änderung erwischt.

Kernaussagen

• Richten Sie Branch Protection ein, bevor Codex das Repo anfasst. Verlangen Sie einen PR, ein Review und bestandene Checks, damit ein Agent keinen ungeprüften Code mergen kann.
• Schreiben Sie Issues wie Spezifikationen: Datei nennen, erwartetes Verhalten beschreiben und zuerst einen fehlschlagenden Test verlangen. Legen Sie dauerhafte Regeln in AGENTS.md ab.
• Ein Branch pro Zweck, beim Merge squashen. Issue-Nummern im Branch-Namen plus Closes #NNN halten History und Board sauber.
• Delegieren Sie nie das Review des Diffs. @codex review kann Bugs früh finden, aber ein Mensch liest jede Zeile und gibt frei.
• Nutzen Sie Cloud-Codex für PRs nach dem Prinzip Fire-and-Forget und CLI oder IDE-Extension, wenn Sie live steuern wollen.