Code-Change-Review (Überprüfung von Code-Änderungen)
Überprüfe eine Änderung so, wie es ein erfahrener Senior-Entwickler tun würde: Finde die Defekte, die wirklich zählen, beweise jeden einzelnen und berichte sie so, dass der Autor schnell handeln kann. Eine kurze Überprüfung mit drei echten Fehlern ist besser als eine lange mit dreißig „Vielleicht“, denn jede Falschmeldung lehrt den Leser, zu überfliegen.
Arbeitsablauf
1. Den Änderungssatz genau bestimmen
Stelle genau fest, was überprüft wird, bevor du irgendeinen Code liest. Falls der Benutzer nichts sagt, nimm standardmäßig alles, was noch nicht auf dem Basis-Branch ist.
| Ziel | Wie abrufen |
|---|---|
| Nicht-committete Arbeit | git diff HEAD (plus git status für nicht versionierte Dateien, dann lesen) |
| Nur bereitgestellt | git diff --cached |
| Aktueller Branch | git diff $(git merge-base HEAD <base>) wobei <base> normalerweise main/master ist |
| Commit-Bereich | git diff A..B |
| Pull Request (Nummer oder URL) | gh pr view <n-oder-url> für Beschreibung, Basis und Head; gh pr diff <n-oder-url> für das Diff; gh pr diff <n-oder-url> --name-only für die Dateiliste |
| Bestimmte Dateien | Lies sie; falls nötig, frage, wovon sie geändert wurden |
Pull Requests. „Überprüfe PR 123“ oder „überprüfe PR #123“ bedeutet PR 123 im aktuellen Repository. Eine URL (https://github.com/<owner>/<repo>/pull/<n>) kann unverändert an gh übergeben werden und funktioniert von jedem Verzeichnis aus, sogar für ein anderes Repository. Verwende für einen GitLab Merge Request glab mr view / glab mr diff. Das Diff allein reicht nicht als Kontext (Schritt 3), lies daher auch die PR-Versionen der Dateien:
-
Wenn der PR aus dem aktuellen Repository stammt, hole ihn und seine Basis ohne Branch-Wechsel in eine dedizierte Referenz, die forciert aktualisiert wird, sodass ein rebasierter PR jede Kopie einer früheren Überprüfung ersetzt. Hole von dem Remote, der auf das Basis-Repository des PRs zeigt (überprüfe mit
git remote -v); bei einem Fork ist das normalerweiseupstream, nichtorigin:git fetch <remote> <base> +refs/pull/<n>/head:refs/review/pr-<n> git rev-parse refs/review/pr-<n> # muss gleich sein: gh pr view <n> --json headRefOid --jq .headRefOidFalls der Fetch fehlschlägt oder der Commit nicht mit
headRefOidübereinstimmt, brich ab und melde dies, anstatt die falsche oder eine veraltete Kopie zu überprüfen. Lies dann Dateien mitgit show refs/review/pr-<n>:<path>und vergleiche mit$(git merge-base refs/review/pr-<n> <remote>/<base>). Verwendegh pr checkout <n>nur, wenn der Benutzer damit einverstanden ist, dass sich sein Arbeitsverzeichnis ändert. -
Für ein anderes Repository lies Dateien im PR-Head über
gh api "repos/<owner>/<repo>/contents/<path>?ref=<head-sha>"(in Anführungszeichen, da?ein Jokerzeichen in zsh ist), oder klone es in ein temporäres Verzeichnis, falls die Überprüfung viel Kontext benötigt. -
Lies das vorhandene Feedback, damit du nicht wiederholst, was bereits vorgebracht, beantwortet oder gelöst wurde.
gh pr view <n> --commentszeigt nur Kommentare der obersten Ebene; Inline-Review-Threads, ihre Antworten und ob sie gelöst sind, kommen über GraphQL:gh api graphql --paginate -F owner=<owner> -F repo=<repo> -F n=<n> -f query='query($owner:String!,$repo:String!,$n:Int!,$endCursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){totalCount nodes{author{login} body}}}}}}}'--paginatefolgt den Threads über die ersten 100 hinaus. Ein Thread, dessencomments.totalCountüber 100 liegt, hat weitere Antworten; hole sie mitnode(id:<thread id>){... on PullRequestReviewThread{comments(first:100,after:<cursor>){…}}}bevor du dich darauf verlässt.
Ermittle auch die Absicht: die PR-Beschreibung, Commit-Nachrichten, das verknüpfte Issue, oder frage den Benutzer in einer Zeile, falls nichts vorhanden ist. Du kannst nicht beurteilen, ob Code richtig ist, ohne zu wissen, was er tun soll.
Bei sehr großen Änderungen (mehr als ~1.500 geänderte Zeilen) führe zuerst eine Triage durch. Sortiere Dateien nach Risiko (Authentifizierung, Zahlungen, Datenmigrationen, Nebenläufigkeit, öffentliche APIs und alles Gelöschte kommt vor Dokumentation, generiertem Code und Sperrdateien) und gib an, welche Dateien eine weniger gründliche Prüfung erhalten haben.
2. Sprachrichtlinien für das laden, was die Änderung betrifft
Lade nur die Referenzdateien für Sprachen und Dateitypen im Änderungssatz, niemals alle. Jede Datei fügt Kontext hinzu, der den von dir überprüften Code verdrängt.
Führe den Detektor aus, wenn Python verfügbar ist (python oder python3):
python <skill-verz>/scripts/detect_languages.py --git <base> # Branch vs. Basis
python <skill-verz>/scripts/detect_languages.py --git HEAD # nicht-committete Arbeit
python <skill-verz>/scripts/detect_languages.py --git <remote>/<base> --head refs/review/pr-<n> # geholter PR
git diff --name-only ... | python <skill-verz>/scripts/detect_languages.py # beliebige Dateiliste
Verwende bei einem Pull Request --head mit dem in Schritt 1 geholten Ref. Der Detektor liest dann Shebangs aus dem Commit des PRs, nicht aus deinem Arbeitsverzeichnis, dem möglicherweise die neuen Skripte des PRs fehlen oder das andere Versionen davon enthält. Bei einem PR in einem anderen Repository liefert gh pr diff <url> --name-only | python <skill-verz>/scripts/detect_languages.py die Dateiliste, kann aber keine Dateiinhalte sehen. Überprüfe die erste Zeile jeder erweiterungslosen Datei in der Liste, zugeordnet oder nicht (ein Python-Skript unter migrations/ ist bereits sql.md zugeordnet, benötigt aber trotzdem python.md): lies es im PR-Head oder in der Basis, wenn der PR es löscht, und ordne es mit der Shebang-Tabelle unten zu.
Es gibt die zu lesenden Referenzdateien und die geänderten Dateien aus, die jede ausgelöst haben. Ohne Python verwende diese Tabelle, die exakt mit dem Detektor übereinstimmt. Dateinamen werden case-insensitiv abgeglichen.
| Geänderte Dateien | Lesen |
|---|---|
.py, .pyi, .pyw, .ipynb, pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile, Pipfile.lock, poetry.lock, uv.lock | references/languages/python.md |
.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .vue, .svelte, .astro, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, tsconfig.json | references/languages/javascript-typescript.md |
.go, go.mod, go.sum, go.work | references/languages/go.md |
.rs, Cargo.toml, Cargo.lock | references/languages/rust.md |
.java, .kt, .kts, .scala, .sc, .groovy, .gradle, pom.xml, build.gradle, settings.gradle, gradle.properties | references/languages/java-kotlin.md |
.cs, .fs, .fsx, .vb, .csproj, .fsproj, .vbproj, .sln, .razor, .cshtml, Directory.Build.props, Directory.Packages.props, NuGet.config, global.json | references/languages/csharp-dotnet.md |
.c, .h, .cc, .cpp, .cxx, .c++, .hpp, .hh, .hxx, .inl, .ipp, .m, .mm, CMakeLists.txt, Makefile, meson.build, conanfile.txt, vcpkg.json | references/languages/c-cpp.md |
.rb, .erb, .rake, .gemspec, .ru, Gemfile, Gemfile.lock, Rakefile, config.ru | references/languages/ruby.md |
.php, .phtml, composer.json, composer.lock | references/languages/php.md |
.swift, .pbxproj, Package.swift, Package.resolved, Podfile | references/languages/swift.md |
.sql, .psql, .pgsql, .ddl, und jede Datei unter migration/, migrations/, migrate/, alembic/versions/, flyway/, liquibase/ | references/languages/sql.md |
.sh, .bash, .zsh, .ksh, .fish, .ps1, .psm1, .psd1, .bat, .cmd | references/languages/shell.md |
.tf, .tfvars, .hcl, .dockerfile, Dockerfile, Dockerfile*, Containerfile, .dockerignore, compose*.yml, compose*.yaml, docker-compose*.yml, docker-compose*.yaml, Chart.yaml, values.yaml, kustomization.yaml, .gitlab-ci.yml, azure-pipelines.yml, bitbucket-pipelines.yml, Jenkinsfile, jede Datei unter .circleci/, und YAML unter .github/workflows/, .github/actions/, k8s/, kubernetes/, helm/, charts/, manifests/, deploy/, deployment/, kustomize/, argocd/ | references/languages/infrastructure.md |
Eine Datei ohne Erweiterung wird über den Interpreter in ihrer Shebang-Zeile zugeordnet (#!/usr/bin/env deno, #!/usr/bin/python3). Versionssuffixe werden ignoriert.
| Shebang-Interpreter | Lesen |
|---|---|
python | references/languages/python.md |
node, deno, bun, ts-node, tsx | references/languages/javascript-typescript.md |
ruby | references/languages/ruby.md |
php | references/languages/php.md |
sh, bash, zsh, ksh, dash, fish, pwsh | references/languages/shell.md |
Eine Datei kann zwei Referenzen benötigen. Eine Rails- oder Alembic-Migration benötigt ihre Sprachdatei und sql.md, und der Detektor meldet beide. Eine Sprache ohne Referenzdatei erhält trotzdem eine vollständige Überprüfung. Die allgemeinen Gesichtspunkte unten decken sie ab, und du solltest anwenden, was du über die häufigen Fallstricke dieser Sprache weißt. Eingebettete Sprachen zählen ebenfalls: SQL-Strings in Python oder Shell-Befehle, die in Go erstellt wurden, sind ein Grund, sql.md oder shell.md zu laden.
3. Kontext über das Diff hinaus aufbauen
Das Diff zeigt, was sich geändert hat, nicht, was es beeinflusst. Bevor du etwas beurteilst:
- Lies den umgebenden Code jedes Hunks, nicht nur die geänderten Zeilen. Viele Fehler leben darin, wie neue Zeilen mit alten interagieren.
- Finde Aufrufer und Abhängigkeiten jeder geänderten Funktion, jedes Typs, Schemas, Konfigurationsschlüssels oder Endpunkts (grep, LSP „Referenzen suchen“). Die Auswirkungszone ist vom Diff aus unsichtbar.
- Lerne die Projektkonventionen kennen: Linter- und Formatierer-Konfigurationen,
CLAUDE.md/CONTRIBUTING.md, und wie der umliegende Code Fehler, Logging und Tests behandelt. Beurteile Konsistenz anhand dieser Codebasis, nicht anhand des allgemeinen Geschmacks. - Suche nach vorhandenen Helfern, bevor du neuen Dienstprogrammcode akzeptierst. Die Neuerfindung von etwas, das das Repository bereits hat, zeigt sich nur, wenn du außerhalb des Diffs suchst.
4. Nach Gesichtspunkten in Prioritätsreihenfolge überprüfen
Arbeite dich von oben auf dieser Liste nach unten. Ein Fehler in Stufe 1 ist wichtiger als jede Anzahl von Anmerkungen der Stufe 3. references/review-angles.md enthält die vollständige Checkliste für jeden Gesichtspunkt; lies sie für jede nicht-triviale Überprüfung.
- Ist es richtig? Korrektheit und Randfälle, Absichtstreue (macht es genau das, was es behauptet?), Fehlerbehandlung und Fehlermodi, Nebenläufigkeit und gemeinsamer Zustand, Auswirkungszone auf Aufrufer.
- Ist es auslieferungssicher? Sicherheit, API-/Schema-/Drahtkompatibilität, Datenintegrität und Migrationen, Betriebsfähigkeit (Rollout, Rollback, Beobachtbarkeit), neue Abhängigkeiten, Datenschutz.
- Ist es guter Code? Leistung und Effizienz, Abstraktionshöhe (befindet sich die Korrektur auf der richtigen Ebene?), Redundanz und Wiederverwendung, Einfachheit versus Überengineering, Konsistenz mit Konventionen, Lesbarkeit.
- Ist es verifiziert? Tests, die ohne die Änderung tatsächlich fehlschlagen würden, Dokumentation und Kommentare synchron gehalten.
Wende die Prüfungen der geladenen Sprachdatei innerhalb dieser Gesichtspunkte an. Sie sind die spezifischen Formen, die diese Probleme in dieser Sprache annehmen.
5. Jeden Fund vor der Meldung verifizieren
Für jeden potenziellen Fund:
- Schreibe das Fehlerszenario: konkrete Eingabe oder Zustand, dann das falsche Ergebnis. Wenn du das nicht kannst, ist es wahrscheinlich kein Fehler.
- Lies den Code erneut, um zu überprüfen, ob das Problem nicht bereits behandelt wird: eine Absicherung vorgelagert, ein Validator, ein Typ, der es ausschließt, ein Test, der es abdeckt.
- Führe es aus, wo dies günstig und sicher ist (ein Unit-Test, ein REPL-Snippet, der Typprüfer oder Linter) und der Fund unsicher ist.
- Bewerte die Zuversicht: Bestätigt (zurückverfolgt oder reproduziert) oder Plausibel (glaubwürdiger Pfad, den du nicht vollständig beweisen konntest). Verwerfe alles Schwächere. Wenn etwas unklar ist, aber harmlos zu erwähnen, stelle es als Frage, anstatt einen Fehler zu behaupten.
6. Bericht erstatten
Verwende references/reporting.md für die Schweregrad-Tags, das Kommentarformat und die Ausgabevorlage. Kurz gefasst:
- Beginne mit einem einzeiligen Fazit: ob es sicher zu mergen ist und das größte Problem, falls vorhanden.
- Jeder Fund beginnt mit seinem Schweregrad-Tag:
[KRITISCH],[MAJOR],[MINOR]oder[NIT], dann eine einzeilige Behauptung und ihredatei:zeile. Der Hauptteil erklärt in dieser Reihenfolge, was das Problem ist, warum es ein Problem ist (das konkrete Fehlerszenario), und einen Korrekturvorschlag oder eine Verbesserung, wo immer du einen anbieten kannst. - Liste die Funde mit den schwerwiegendsten zuerst auf. Standardmäßig maximal etwa 10. Erwähne, wie viele Elemente mit geringerem Schweregrad du ausgelassen hast, und liste sie auf, wenn der Benutzer fragt.
- Lasse
[NIT]s weg, es sei denn, es gibt keine echten Defekte oder der Benutzer hat um eine gründliche Prüfung gebeten. - Beende mit dem, was du nicht abgedeckt hast (überflogene Dateien, Dinge, die du nicht ausführen konntest). Ein ehrlicher Hinweis zum Umfang gehört zur Überprüfung.
Verwende dasselbe Tag-zuerst-Format für Kommentare, die auf einem Pull Request gepostet werden, damit ein Fund im Bericht und auf dem PR gleich gelesen wird. Poste auf den PR nur, wenn der Benutzer dich darum bittet; references/reporting.md zeigt, wie man sie als eine einzige Überprüfung mit Inline-Kommentaren postet.
Wenn der Host ein strukturiertes Werkzeug für Befunde bereitstellt, berichte darüber in derselben Reihenfolge anstatt die Liste zu drucken, und beginne trotzdem die Zusammenfassung jedes Fundes mit seinem Tag.
Grundsätze
- Beweise vor Meinung. Jeder Fund zitiert Code. „Erwäge X“ ohne Grund ist Rauschen.
- Überprüfe die Änderung, nicht die Codebasis. Markiere bereits bestehende Probleme nur, wenn die Änderung sie verschlimmert oder von ihnen abhängt, und kennzeichne sie als bereits bestehend.
- Respektiere die Entscheidungen des Autors. Ein anderer, aber gleichermaßen gültiger Ansatz ist kein Fund. Widerspreche nur, wenn du einen konkreten Kostenpunkt nennen kannst.
- Korrigiere während der Überprüfung nicht, wenn nicht darum gebeten. SchlAGE Korrekturen vor; lass den Benutzer entscheiden, ob er sie anwenden möchte.