+190 XP

End to end: vom Issue zum gemergten Pull Request

# End to end: vom Issue zum gemergten Pull Request

Sie haben ein Issue in Ihrem GitHub-Repo liegen, und am Ende dieses Durchlaufs soll ein gemergter Pull Request stehen, der es schließt, mit einem Menschen, der den Diff als letztes Gate prüft. Das ist die ganze Aufgabe, und Codex ist darauf gebaut, den größten Teil davon zu übernehmen, während Sie die Kontrolle behalten.

Diese Lektion geht diesen Loop konkret durch: Issue aufnehmen, Codex branchen und implementieren lassen, Tests laufen lassen, PR öffnen, reviewen, mergen. Die Disziplin, die das funktionieren lässt, ist nichts Ausgefallenes: Branch-Hygiene, kleine Diffs und ein Review, das ein echter Checkpoint ist und kein Abnicken.

Wo Codex in diesem Workflow sitzt

Codex ist der Software-Engineering-Agent von OpenAI. Er läuft in einer isolierten Cloud-Sandbox, liest Ihr Repo, bearbeitet Dateien, führt Befehle aus und pusht Branches. Sie erreichen ihn über die Codex-Sidebar in ChatGPT und über die Codex CLI in Ihrem Terminal, und über die Codex-GitHub-Integration ist er mit GitHub verbunden, sodass er PRs direkt öffnen und aktualisieren kann.

Das mentale Modell: Codex ist ein Teamkollege, der die mechanische Arbeit einer Änderung schnell erledigen kann, aber seinen eigenen Code niemals mergt. Sie legen den Scope fest, er produziert einen Diff, Sie reviewen und mergen. GitHubs Branch Protection erzwingt diese Grenze, also richten Sie sie zuerst ein.

Setzen Sie die Guardrails, bevor Sie anfangen

Aktivieren Sie im Repo Branch Protection auf Ihrem Default-Branch:

  • Pull Request vor dem Merge erforderlich.
  • Mindestens ein zustimmendes Review erforderlich.
  • Status Checks (Ihre CI) müssen bestehen.

Jetzt kann selbst ein Agent, der Code pusht, ihn nicht ohne grünen Build und menschliche Zustimmung landen. Das ist die wichtigste Einstellung überhaupt, wenn Sie einen Agenten in einem echten Repo arbeiten lassen.

Schritt 1: Das Issue aufnehmen

Starten Sie mit einem echten, gut abgegrenzten Issue. Codex arbeitet am besten, wenn das Issue wie eine Spezifikation klingt und nicht wie ein Gefühl. Vergleichen Sie:

Schwach: „Login ist instabil.“

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

Die starke Version benennt die Datei, das erwartete Verhalten und verlangt einen Test. Allein diese Einschränkung halbiert den Diff meistens.

Zeigen Sie Codex in der Sidebar auf das Repo und fügen Sie die Aufgabe ein. Wenn Ihr Repo eine codex.md oder eine AGENTS.md im Root hat, liest Codex sie als dauerhafte Anweisungen: wie Tests laufen, Code-Style, was nicht angefasst werden darf. Behandeln Sie diese Datei als die dauerhafte Version Ihrer Custom Instructions für diese Codebasis.

markdown
# 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 branchen lassen

Lassen Sie Codex nicht auf main arbeiten. Sagen Sie ihm, er soll einen Branch mit einem klaren, am Issue hängenden Namen anlegen:

bash
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. Die Issue-Nummer im Branch-Namen bedeutet, dass jeder Code zurück zu der Konversation verfolgen kann, aus der er entstanden ist. Das ist Branch-Hygiene: ein Branch, eine Absicht, nach dem Merge leicht zu löschen.

Codex fährt seine Sandbox hoch, klont den Branch und beginnt zu arbeiten. Sie sehen, wie er Dateien liest, einen Plan aufstellt und Befehle ausführt. Lassen Sie ihn laufen, aber lesen Sie den vorgeschlagenen Plan, bevor er viel schreibt. Wenn der Plan schon zu groß riecht (er will drei Module refactoren für einen Einzeiler-Bug), stoppen Sie ihn und schneiden Sie den Scope jetzt zu, nicht erst beim Review.

Schritt 3: Die Änderung implementieren und testen

Die Reihenfolge zählt, und es lohnt sich, sie Codex gegenüber explizit zu machen: erst der fehlschlagende Test, dann der Fix. Das ist die Agentenversion von Test-Driven Development, und sie bewirkt zwei Dinge. Sie beweist, dass der Bug existiert, und sie beweist, dass Ihr Fix ihn tatsächlich behebt und nicht irgendetwas daneben.

Ein saubererer Loop für unser Beispiel sieht so aus:

python
# tests/test_validate.py
import pytest
from src.auth.validate import validate_email

@pytest.mark.parametrize("email", [
    "sam+test@example.com",
    "sam+news+promo@example.com",
])
def test_plus_alias_is_accepted(email):
    assert validate_email(email) is True

def test_bare_plus_still_rejected():
    assert validate_email("+@example.com") is False

Codex fügt den Test hinzu, führt ihn aus, sieht ihn fehlschlagen und bearbeitet dann validate_email, bis die Suite grün ist. Weil er Befehle in seiner Sandbox ausführt, bekommen Sie die echte Ausgabe und keine Vermutung darüber, ob der Code funktioniert. Wenn ein Test auf unerwartete Weise fehlschlägt, iteriert er. Achten Sie darauf, dass er nicht den Test „repariert“, damit er zum fehlerhaften Verhalten passt. Das ist ein klassischer Agenten-Fehlermodus, und genau deshalb haben Sie den fehlschlagenden Test vorab verlangt: Sie können den Test lesen und bestätigen, dass er das Verhalten kodiert, das Sie tatsächlich wollen.

Wenn er fertig ist, berichtet Codex, was sich geändert hat und warum. Lesen Sie diese Zusammenfassung, aber vertrauen Sie ihr nicht anstelle des Diffs.

Codex: From Issue to Pull Request

Watch on YouTube

Schritt 4: Den Pull Request öffnen

Lassen Sie Codex den PR von seinem Branch nach main öffnen. Ein guter, von einem Agenten geschriebener PR-Text ist so strukturiert, dass ein Reviewer in Minuten zustimmen kann:

markdown
## 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 `+`.
- `tests/test_validate.py`: added alias-accept and bare-plus-reject cases.

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

Beachten Sie Closes #214. Dieses Keyword verknüpft den PR automatisch mit dem Issue und schließt das Issue, wenn der PR gemergt wird. Es hält Ihr Board ehrlich, ohne einen einzigen zusätzlichen Klick.

Der PR triggert Ihre CI. Weil Sie Status Checks verlangt haben, bleibt der Merge-Button deaktiviert, bis der Build besteht. Das ist Ihr erstes automatisches Gate, das seine Arbeit tut, bevor überhaupt ein Mensch hinschaut.

Schritt 5: Den Diff reviewen (das echte Gate)

Das ist der Schritt, den Sie niemals delegieren. Öffnen Sie den Tab Files changed und lesen Sie jede Zeile so, als hätte ein Junior-Entwickler sie geschrieben, denn funktional war es einer.

Worauf Sie bei agentengenerierten Diffs speziell achten sollten:

  • Scope Creep. Hat er nur angefasst, was das Issue brauchte? Neu formatierte Dateien, umbenannte unbeteiligte Variablen und „da war ich schon mal hier“-Edits blähen den Diff auf und verstecken die eigentliche Änderung. Bitten Sie Codex, alles Themenfremde zurückzunehmen.
  • Die Regex oder Logik, die es „behebt“. Eine aufgeweitete Regex kann + akzeptieren und gleichzeitig Müll durchlassen. Lesen Sie das tatsächliche Pattern. Hier wohnen die subtilen Security- und Korrektheitsbugs.
  • Testqualität. Schlägt der Test ohne den Fix fehl? Prüft er das Richtige? Ein Test, der auch mit vorhandenem Bug besteht, ist schlimmer als kein Test.
  • Secrets und Config. Stellen Sie sicher, dass nichts einen Key hartkodiert oder einen Env-Default geändert hat.

Kleine Diffs machen das möglich. Ein PR mit 40 Zeilen bekommt ein echtes Review; ein PR mit 600 Zeilen wird überflogen und durchgewinkt, was den ganzen Sinn des menschlichen Gates zerstört. Wenn Codex etwas Großes produziert hat, teilen Sie es auf: Bitten Sie ihn, die Änderung als zwei oder drei aufeinanderfolgende PRs zu öffnen, jeder unabhängig reviewbar.

Sie können Review-Kommentare auch direkt am PR hinterlassen und Codex bitten, sie abzuarbeiten. Er pusht neue Commits auf denselben Branch, die CI läuft erneut, und Sie reviewen das Delta. In diesem kommentargetriebenen Loop passiert die meiste echte Zusammenarbeit.

Wissenscheck

1. Welches mentale Kernmodell nutzt die Lektion, um die Rolle von Codex im Workflow von Issue bis Merge zu beschreiben?

2. Warum nennt die Lektion Branch Protection „die wichtigste Einstellung überhaupt“, wenn ein Agent in einem echten Repo arbeitet?

3. Warum produziert ein klar abgegrenztes Issue laut Lektion bessere Ergebnisse als ein vages wie „Login ist instabil“?

MEHRFACHAUSWAHL

4. Wählen Sie ALLE Branch-Protection-Regeln aus, die die Lektion für den Default-Branch empfiehlt.

Wählen Sie alle richtigen Antworten aus.

MEHRFACHAUSWAHL

5. Wählen Sie ALLE Aussagen aus, die die in der Lektion betonten Disziplinen und Praktiken korrekt wiedergeben.

Wählen Sie alle richtigen Antworten aus.

Schritt 6: Mergen und aufräumen

Sobald die CI grün ist und Sie zugestimmt haben, mergen Sie. Bevorzugen Sie Squash and merge für Agentenarbeit: Der Branch enthält möglicherweise ein Dutzend winzige Iterations-Commits („fix test“, „oops“, „lint“), und Squashing fasst sie zu einem sauberen Commit auf main zusammen, mit Ihrem PR-Titel als Message. Die History bleibt lesbar.

Löschen Sie den Branch nach dem Merge. GitHub bietet das direkt nach dem Merge als Button an, und Sie können in den Repo-Einstellungen Auto-Delete aktivieren, damit sich alte Agenten-Branches nie stapeln. Das Issue schließt sich automatisch wegen Ihrer Closes #214-Zeile. Der Loop ist abgeschlossen: Issue rein, reviewte und getestete Änderung raus, saubere History.

Eine Anmerkung zu den zwei Wegen, Codex zu betreiben

Sie werden zwischen zwei Oberflächen wechseln, und sie passen zu unterschiedlichen Aufgaben:

  • Cloud (ChatGPT-Sidebar / GitHub-Integration): am besten für asynchrone, in sich geschlossene Aufgaben, die Sie anstoßen und später prüfen. Zuweisen, weggehen, den PR reviewen, wenn er sich meldet.
  • Codex CLI (lokal): am besten, wenn Sie in Echtzeit zuschauen und steuern wollen, ihn gegen nicht committeten lokalen Stand laufen lassen oder in einem Repo mit nur lokal verfügbarem Tooling arbeiten.

Beide öffnen PRs; beide respektieren Ihre AGENTS.md. Die Lektüre auf platform.openai.com/docs und die Developer-Docs sind immer aktueller als jedes Tutorial, also legen Sie sich Bookmarks an.

Warum dieser Loop skaliert

Der Grund, warum das im Teammaßstab funktioniert, ist, dass Codex sich in einen bereits existierenden Prozess einfügt. Sie erfinden keine neue Merge-Policy für KI. Sie zeigen einem Agenten dieselbe Branch Protection, CI und Review-Kultur, die Ihre Menschen nutzen, und der Agent erbt diese Guardrails. Die Gewohnheit „erst der fehlschlagende Test“, kleine Diffs und die verpflichtende menschliche Zustimmung sind genau die Praktiken, die menschliche PRs sicher machen. Sie machen Agenten-PRs aus denselben Gründen sicher.

Der Fehlermodus, den Sie vermeiden müssen, ist Geschwindigkeitsdruck: Codex produziert Diffs schnell, und es ist verlockend, entsprechend schnell zuzustimmen. Widerstehen Sie dem. Ihr Durchsatz-Bottleneck sollte die Review-Qualität sein, nicht die Agenten-Geschwindigkeit, denn das Review ist der einzige Schritt, der die plausible, aber falsche Änderung abfängt.

Key Takeaways

  • Richten Sie Branch Protection ein, bevor Sie Codex ans Repo lassen. Verlangen Sie einen PR, ein Review und bestehende Checks, damit ein Agent ungeprüften Code physisch nicht mergen kann.
  • Schreiben Sie Issues wie Spezifikationen. Benennen Sie die Datei, das erwartete Verhalten und verlangen Sie zuerst einen fehlschlagenden Test. Enger Input produziert enge, reviewbare Diffs.
  • Ein Branch pro Absicht, und beim Merge squashen. Nachvollziehbare Branch-Namen mit der Issue-Nummer plus Closes #NNN im PR halten History und Board automatisch sauber.
  • Delegieren Sie das Diff-Review niemals. Lesen Sie jede Zeile auf Scope Creep, zweifelhafte Logik und schwache Tests. Kleine Diffs machen ehrliches Review erst möglich.
  • Passen Sie die Oberfläche zur Aufgabe: Cloud-Codex für Fire-and-forget-PRs, die Codex CLI, wenn Sie live zuschauen und steuern wollen.

Was Sie aus dieser Lektion umsetzen

Diese Maßnahmen sind im Playbook der Rolle zusammengefasst.

  • Branch Protection einrichten: PR, Review und erfolgreiche Checks verpflichtend, bevor Codex läuft
  • Autonome Loops nur mit maschinell prüfbarer Done-Bedingung und harten Obergrenzen laufen lassen
  • Jeden Diff auf den Trick mit gelöschten fehlschlagenden Tests und auf Scope Creep prüfen
Vollständiges Action Playbook ansehen →

Zurück

Codex auf GitHub: PR-Reviews und Actions

Zurück zum Lernpfad