chukaofili/agent-plugins

Gestapelte PRs

Das Größenbudget

Zielen Sie auf etwa 300 geänderte Zeilen pro PR ab, mit 500 als Obergrenze. Bei dieser Größe kann ein Mensch die gesamte Änderung für einen schnellen Durchlauf im Kopf behalten, und Review-Agenten liefern saubere, spezifische Ergebnisse, anstatt nur zu überfliegen.

Was zählt: handgeschriebener Code und Tests.

Was nicht zählt: Lockfiles, generierter Code (Migrationen, Codegen, OpenAPI-Ausgabe), Snapshots, Fixtures und eingekaufte Dateien. Diese werden überflogen, nicht gelesen. Listen Sie im PR-Text auf, welche Dateien generiert sind, damit der Reviewer weiß, was er überspringen soll.

Vor dem Schreiben aufteilen, nicht danach. Die Aufteilung wird im Plan festgelegt (siehe coding-process). Wenn eine geplante Phase 500 überschreiten würde, planen Sie sie neu. Übliche Aufteilungen:

• Tests können als eigene Phase landen. Beispielsweise Logik mit Unit- und Integrationstests, dann UI mit E2E-Tests.
• Schema oder Datenmodell, dann der Service, der es verwendet, dann die API-Oberfläche, dann die UI.
• Ein Refactoring, das die Änderung einfach macht, dann die Änderung selbst.
• Eine Docs-Synchronisation, die zu groß zum Mitnehmen ist, erhält eine reine Docs-Phase oben drauf.

Wirklich nicht aufteilbare Änderungen, wie eine zusammenhängende Migration oder eine Umbenennung über 80 Dateien hinweg, dürfen darüber hinausgehen. Der PR-Text erklärt warum und verweist den Reviewer auf den Teil, der tatsächlich gelesen werden muss.

Atomare Commits gelten weiterhin innerhalb jedes PRs. Das Budget gilt pro PR und ersetzt nicht die Commit-Hygiene.

Stapeln

Mehrphasige Arbeit wird als Stapel von PRs ausgeliefert, niemals als ein einziger Branch, der den gesamten Plan trägt. Jeder PR ist eine Phase und zielt auf den Branch der vorherigen Phase, nicht auf main. Jeder Diff, den der Reviewer sieht, ist also nur die Änderung dieser Phase, und eine riskante Phase (eine Migration, eine Auth-Änderung) kann eigenständig überprüft und zurückgesetzt werden.

• Verzweigen Sie jede Phase vom Kopf der vorherigen Phase. Nur der unterste PR zielt auf main:

  gh pr create --base <previous-stage-branch>
  

• Vermerken Sie die Position im Text jedes PRs (Gestapelt auf #123), damit ein Reviewer, der einen in der falschen Reihenfolge öffnet, weiß, worum es sich handelt.
• Von unten nach oben landen. Wenn sich ein Basis-Branch ändert (ein Review-Fix oder das Zusammenführen der Basis), rebasen Sie die darüberliegenden Branches und pushen Sie diese force. Force-Push auf Ihre eigenen ungemergten Stapel-Branches ist Routine. Force-Push auf main oder einen gemeinsamen Branch ist das nie.
• Nachdem ein PR im Stapel gemergt wurde, synchronisieren Sie den Rest auf die neue Basis, bevor Sie mit der nächsten Phase beginnen.
• Korrekturen aus einem Review oder einer Verifizierungsphase auf einer UI-Oberfläche werden als neue Phase oben drauf ausgeliefert, sodass der Build und die Korrekturen separat überprüfbar bleiben.
• Stapelwerkzeuge wie gh stack, Graphite oder git-town sind optional. Reines Git und gh reichen aus.

Sequentielle Überprüfung

Überprüfen Sie einen Stapel eine Phase nach der anderen. Fordern Sie ein Review vom Reviewer des Projekts an (siehe Projekt-Gates in AGENTS.md) nur für den untersten PR, dann:

1. Fordern Sie ein Review für diese eine Phase an.
2. Bearbeiten Sie jeden Fund (siehe unten).
3. Fordern Sie erneut ein Review an und wiederholen Sie den Vorgang, bis die Phase genehmigt ist.
4. Erst dann fordern Sie ein Review für die nächste Phase oben an.

Fordern Sie kein Review für den gesamten Stapel auf einmal an. Ein Fund in Phase 1 kann Kommentare ungültig machen, die bereits zu Phase 2 bis 5 geschrieben wurden, und die sequenzielle Überprüfung hält den Aufwand für den Reviewer begrenzt.

Wenn eine Phase ins Stocken gerät (kein Review kommt zurück oder ein Fund, der eine Produktentscheidung erfordert), markieren Sie sie und bauen Sie die darüberliegenden Phasen lokal weiter, wo sie nicht von der Antwort abhängen.

Umgang mit Review-Funden (jeder PR, gestapelt oder nicht)

• Überprüfen Sie jeden Fund technisch, bevor Sie darauf reagieren. Lesen Sie den Code, auf den er verweist, und reproduzieren Sie das Problem, wenn möglich.
• Beheben Sie ihn oder widersprechen Sie mit Begründung. Reviewer, ob Mensch oder Bot, liegen als normaler Vorgang selbstbewusst falsch. Eine schlechte Änderung vorzunehmen, um zustimmend zu wirken, ist schlimmer als zu argumentieren. Keine performative Zustimmung.
• Bewerten Sie Funde nach realer Wahrscheinlichkeit. Widersprechen Sie Korrekturen für Szenarien, die realistisch nicht eintreten können, und Vorschlägen, die Komplexität ohne echten Gewinn hinzufügen.
• Fügen Sie keine Tests hinzu, die nicht fehlschlagen können. Ein Test, der besteht, egal ob der Fehler existiert oder nicht, ist Rauschen. Führen Sie ihn zuerst gegen den fehlerhaften Code aus (siehe testing).
• Antworten Sie auf jeden Fund, damit der Reviewer sehen kann, was damit passiert ist: behoben in welchem Commit, oder warum nicht.