Wenn du mit Codex Code überprüfst, tauchen manche Kommentare immer wieder auf. Vielleicht muss ein älterer API-Vertrag weiterhin gelten, vielleicht dürfen keine Kundendaten in die Logs gelangen oder eine Umbenennung würde einen anderen Dienst lahmlegen. Solche Prüfungen sind wichtig, geraten aber leicht in Vergessenheit, wenn nur wenige im Team die Hintergründe kennen.
Codex Code Review kann jetzt eigene Repository-Regeln aus AGENTS.md heranziehen, um solche Probleme zu erkennen und im Kommentar auf die zugrunde liegende Regel zu verweisen. Wenn du AGENTS.md bereits für Programmieraufgaben nutzt, kannst du in derselben Datei auch festhalten, worauf Codex bei Reviews achten soll. Das hilft besonders dann, wenn Mitwirkende oder Coding-Agenten in einem Teil des Repositorys arbeiten, mit dessen Vorgeschichte sie noch nicht vertraut sind. In diesem Beitrag zeigen wir, wo Repository-Regeln sinnvoll sind, wie du sie formulierst und was wir beim Testen gelernt haben.
Mehr Code ausliefern
Coding-Agenten können größere Änderungen übernehmen und über längere Zeit an einer Aufgabe arbeiten. So können Teams mehr ihrer Ideen in Code umsetzen. Bei OpenAI hat sich die Zahl der Pull Requests pro Woche seit dem vierten Quartal mehr als verdoppelt. Bei vielen Unternehmen, die unsere Produkte nutzen, beobachten wir eine ähnliche Entwicklung. Mehr Code hilft Teams, neue Funktionen auszuliefern und mehr Probleme zu lösen. Zugleich warten mehr Pull Requests darauf, dass jemand mit der nötigen Erfahrung sie prüft. So kann die Codeprüfung schnell zum Engpass werden.
Wenn mehrere Änderungen gleichzeitig eintreffen, wird die Prüfung schwieriger. Ein Diff kann völlig plausibel aussehen und trotzdem dazu führen, dass ein älterer Client nicht mehr funktioniert oder eine Grenze überschritten wird, die der Person hinter der Änderung unbekannt war. Jemand muss diese Zusammenhänge kennen und rechtzeitig darauf hinweisen, damit sich die Änderung noch anpassen lässt.
Wenn Reviews zum Engpass werden
Je mehr Pull Requests eingehen, desto weniger Zeit bleibt im Review, um das Ziel jeder Änderung zu verstehen und vor der Rückmeldung den nötigen Kontext zusammenzutragen. Wer inzwischen an etwas anderem arbeitet, braucht selbst für eine kleine Korrektur oft länger. Mit schnellem Feedback können Teams die Vorteile kürzerer Entwicklungszeiten nutzen, ohne dass einzelne Teammitglieder zum Engpass werden.
Manche Probleme sind im Diff allein schwer zu erkennen. Ein Feld in einer Antwort umzubenennen, sieht vielleicht nach einer gewöhnlichen Aufräumarbeit aus. Clients, die sich noch auf den bestehenden API-Vertrag verlassen, könnten dadurch aber ausfallen. Wer den Dienst schon öfter geprüft hat, weiß vielleicht noch, warum das Feld bleiben muss. Wer neu zum Projekt beiträgt oder als Agent zum ersten Mal an dem Dienst arbeitet, weiß das vermutlich nicht.
Regeln als Schnittstelle
Wie vermittelst du einem Coding-Agenten das Wissen, das sich dein Team normalerweise nach und nach aneignet? Über die neue Schnittstelle für Repository-Regeln kannst du in AGENTS.md kurze Review-Hinweise mit klar abgegrenztem Geltungsbereich hinterlegen. Codex Code Review kann die für eine Änderung relevanten Regeln anwenden und sie im jeweiligen Kommentar zitieren. So steht die Erklärung direkt bei dem Code, für den sie gilt, und du musst sie nicht in jedem Pull Request wiederholen.
Modelle für Programmieraufgaben lassen sich immer gezielter steuern. Schon eine kurze, klar eingegrenzte Anweisung kann bei einem umfangreichen Review den Blick auf das lenken, was deinem Team wichtig ist. Auch im Codex-Repository stehen die Regeln für Code Review in AGENTS.md. Sie behandeln unter anderem den für das Modell sichtbaren Kontext und Änderungen, die die Kompatibilität beeinträchtigen.
Ein Beispiel aus der Praxis:
Der App Server von Codex sendet eine interne Benachrichtigung namens rawResponseItem/completed. Sie ist als experimentell gekennzeichnet, wird aber bereits von Codex Cloud verarbeitet. Die Review-Regel für inkompatible Änderungen im Repository nennt rawResponseItem/* ausdrücklich als Integrationsschnittstelle, die auch im experimentellen Stadium erhalten bleiben soll.
Der bei der Übertragung verwendete Name ist im Protokoll für den App Server definiert. Stell dir vor, beim Aufräumen des Codes würde sich eine Zeile ändern:
-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"
Der geänderte Code lässt sich kompilieren. Clients, die auf die bisherige Benachrichtigung warten, würden sie jedoch nicht mehr empfangen. Der relevante Auszug aus den Repository-Regeln ist kurz:
## Code Review Rules
### Breaking changes
Search for breaking changes in external integration surfaces:
- raw response item events (`rawResponseItem/*`), even while experimental
Für diesen beispielhaften Diff könnte ein Hinweis von Code Review so lauten:
Behalte die bestehende Benachrichtigung
rawResponseItem/completedbei. Clients von Codex Cloud warten auf genau diesen Namen. Nach einer Umbenennung würden sie das Ereignis nicht mehr empfangen, auch wenn es noch experimentell ist. Behalte den bisherigen Namen bei oder füge ein abwärtskompatibles Ereignis hinzu, wie inAGENTS.mdbeschrieben.
Das Codex-Team hat diese Regel eigens zum Schutz der Clients von Codex Cloud hinzugefügt. Lege Regeln für das gesamte Repository im Stammverzeichnis ab und Regeln für einzelne Dienste im jeweiligen Verzeichnis. Beim Review kann Codex die Vorgaben für die geänderten Dateien anwenden und auf die passende Regel verweisen. Für eine Änderung, die den App Server nicht betrifft, braucht Codex dessen Kontext nicht.
Regeln ergänzen die Werkzeuge, mit denen Teams bereits arbeiten. Tests und Linter eignen sich für Prüfungen, deren Ergebnis sich eindeutig aus dem Code ableiten lässt. Mit Repository-Regeln lässt sich auch festhalten, worauf es bei Entscheidungen ankommt, die sich schwerer automatisieren lassen. Kompatibilitätsanforderungen und Vorgaben dazu, wo Daten verarbeitet werden dürfen, sind gute Ausgangspunkte. Wer eine Änderung vornimmt, muss nicht jeden früheren Vorfall und jede lokale Konvention kennen. Die relevanten Hinweise stehen bereits im Repository.
Regeln schreiben, die sich in der Praxis bewähren
Wir haben getestet, wie gut Code Review die Vorgaben eines Repositorys anwenden kann. Unsere Testfälle umfassten bekannte Regelverstöße und unbedenkliche Gegenbeispiele. In der Haupttestreihe erkannten die Varianten mit Repository-Regeln 98 % der Probleme, auf die sie gemäß den eigenen Regeln hinweisen sollten. Die Kontrollvariante erreichte 58,3 %.
Einen Regelverstoß zu erkennen, ist nur ein Teil der Aufgabe. Wir wollten auch wissen, was passiert, wenn mehrere Regeln gleichzeitig relevant sind oder ein Pull Request bereits viele Änderungen enthält. Wir haben sowohl Verstöße mit spürbaren Folgen als auch Änderungen getestet, die keinen Kommentar erfordern. Die Ergebnisse haben wir anhand von vier Fragen ausgewertet:
Was wir untersucht haben
Abdeckung
Erkennt Codex die gesuchten Verstöße auch in umfangreichen Diffs, wenn mehrere Regeln gleichzeitig zu beachten sind?
Zurückhaltung
Verzichtet Codex bei fehlerfreien Änderungen und zulässigen Ausnahmen auf unnötige Kommentare?
Erkennung anderer Fehler
Erkennt Code Review weiterhin gewöhnliche Fehler, die keine Repository-Regel abdeckt?
Umsetzbarkeit
Nennt jeder Hinweis die einschlägige Regel, die betroffene Stelle im Code und die Priorität?
Wir haben auch gängige Formen ausprobiert, um Vorgaben festzuhalten, von kurzen Stichpunktlisten bis hin zu Abschnitten, für die jeweils ein bestimmtes Team verantwortlich ist.
Beim Einsatz der Regeln in internen Repositorys zeigte sich dasselbe Muster. Codex konnte lokale Vorgaben finden und zitieren, die bei einem Review ohne eigene Regeln womöglich unberücksichtigt geblieben wären. Zu allgemein formulierte Anweisungen führten allerdings leicht zu überflüssigen Kommentaren. Mit wenigen, eng gefassten Regeln, die ausdrücklich eine zulässige Vorgehensweise nannten, konnte sich Codex auf hilfreiche Hinweise konzentrieren, ohne jede Änderung im Umfeld zu beanstanden.
Beginne mit einer wichtigen Bedingung, die sich nicht von selbst versteht. Halte eine Prüfung fest, die dein Team bei Reviews immer wieder erklären muss, etwa eine Kompatibilitätsanforderung oder eine Vorgabe zum Umgang mit Daten. Wenn das Review ohne eine Regel genauso ausfallen würde, lass sie weg.
Lege Regeln dort ab, wo sie gelten. Vorgaben für das gesamte Repository gehören ins Stammverzeichnis, dienstspezifische Vorgaben in eine AGENTS.md im entsprechenden Unterverzeichnis. So lenken sachfremde Anweisungen nicht vom Review ab, und es bleibt klar, wer für die Regeln zuständig ist.
Beschreibe, was erhalten bleiben muss und wie eine sichere Änderung aussieht. Die Regel zu rawResponseItem/* benennt das Kompatibilitätsrisiko. „Behalte den bisherigen Namen bei oder füge ein abwärtskompatibles Ereignis hinzu“ zeigt eine konkrete Alternative auf.
Formuliere Regeln, die Bestand haben, und halte sie aktuell. Beschreibe das gewünschte Ergebnis. Funktionsnamen können sich ändern. Prüfe Änderungen an den Regeln. Wenn eine Regel wiederholt unnötige Kommentare auslöst, grenze sie ein oder entferne sie.
Überlass die Formatierung und andere mechanische Prüfungen der CI. Nutze Repository-Regeln für Fragen, die dein Team sonst im nächsten Review wieder stellen müsste.
Erste Schritte
Wenn Codex Code Review für dein Repository bereits aktiviert ist, füge zwei oder drei Regeln in die passende AGENTS.md ein und öffne einen für das Repository typischen Pull Request. Wenn du Code Review zum ersten Mal nutzt, erfährst du in der Kurzanleitung zu Code Review, wie du die Funktion für ein GitHub-Repository aktivierst. Mit @codex review kannst du auch direkt ein Review anfordern.
Beginne mit einer Erklärung, die dein Team bei Reviews häufig wiederholt, oder mit einem für das Repository typischen Fehler, der unentdeckt ernste Folgen hätte. Probiere drei Änderungen aus: eine, bei der die Regel greifen soll, ein unbedenkliches Gegenbeispiel und eine Änderung, die mit der Regel nichts zu tun hat. Prüfe, ob Codex im ersten Fall einen hilfreichen Hinweis gibt und in den beiden anderen auf unnötige Kommentare verzichtet. Passe die Regel anhand dieser Ergebnisse an.
Codex Code Review ergänzt die Prüfung durch dein Team. Für die verbindliche Durchsetzung der Anforderungen sorgen weiterhin Tests, Schutzregeln für Branches und vorgeschriebene Genehmigungen.
Wenn du mehr Zeit damit verbringst, Änderungen zu prüfen, als sie zu schreiben, beginne mit einer Prüfung, die dein Team immer wieder vornimmt. Halte sie in AGENTS.md fest und probiere Codex Code Review bei deinem nächsten Pull Request aus.