Go-Code-Review (hypergadam/agent-skills)

Go-Code-Review

Ziel: Die Änderung soll die Codebasis gesünder machen. Sie muss nicht perfekt sein. Blockiere eine Änderung nicht aus persönlichem Geschmack.

Schritt 1: Die Änderung holen

• Wenn der Benutzer einen Diff, PR oder Dateien angegeben hat, verwende diese.
• In einem Git-Repository: git diff --stat main...HEAD, dann git diff main...HEAD (versuche master oder origin/main, falls main nicht existiert). Für uncommittete Arbeit: git diff und git diff --staged.
• Wenn der Zweck der Änderung unklar ist, frage in einem kurzen Satz nach.

Schritt 2: Den Kontext lesen

• Öffne die gesamte Datei um jede geänderte Funktion herum, nicht nur die Diff-Zeilen.
• Finde Aufrufer von geänderten exportierten Funktionen: grep -rn "FuncName(" --include=*.go
• Überprüfe die Go-Version in go.mod. Manche Ratschläge hängen davon ab (Schleifenvariablen sind pro Iteration seit Go 1.22).

Schritt 3: Die Tools ausführen (wenn du Befehle ausführen kannst)

go build ./...
go vet ./...
go test -race ./...              # nur geänderte Pakete, wenn das Repository langsam ist
golangci-lint run ./...          # nur wenn installiert oder das Repository eine Konfiguration hat

Melde echte Fehler. Für Formatierung sage einmal „führe gofmt aus“; liste nicht jede Zeile auf. Wenn du keine Befehle ausführen kannst, sage dies in einem Satz.

Schritt 4: In dieser Reihenfolge reviewen

Große Dinge zuerst. Wenn das Design falsch ist, sage das zuerst und überspringe die Kleinigkeiten.

1. Design – Gehört diese Änderung hierher (dieses Paket, dieser Service)? Passt sie zum Rest des Systems? Ist es der richtige Zeitpunkt dafür?
2. Funktionalität – Tut sie das, was der Autor beabsichtigt hat? Ist das gut für diejenigen, die sie nutzen (Endbenutzer und zukünftige Entwickler)? Denke an Randfälle und Nebenläufigkeit.
3. Komplexität – Kann ein Leser sie schnell verstehen? Achte auf Over-Engineering: Code, der für eine imaginäre Zukunft statt für das heutige Problem gebaut wurde.
4. Tests – Gibt es Tests in der gleichen Änderung? Würden sie fehlschlagen, wenn der Code kaputt ginge? Sind sie einfach?
5. Namensgebung – Klar, nicht zu lang, Go-Stil.
6. Kommentare – Erkläre warum, nicht was. Veraltete Kommentare und erledigte TODOs entfernt.
7. Stil – gofmt, Style Guide. Persönliche Vorliebe = Nur Nit.
8. Konsistenz – Style Guide gewinnt gegenüber umgebendem Code. Wenn der Guide nichts sagt, folge dem umgebenden Code.
9. Dokumentation – README, godoc, Konfigurations-/Umgebungsvariablen, Migrationen aktualisiert, wenn sich das Verhalten geändert hat.
10. Jede Zeile – Lies den gesamten menschengeschriebenen Code. Generierten Code (*.pb.go, Mocks, sqlc-Ausgabe) kann man überfliegen.
11. Code-Gesundheit – Wird das gesamte System durch diese Änderung besser oder schlechter?
12. Gute Dinge – Nenne echte gute Dinge, die du siehst.

Für Go-spezifische Prüfungen in jedem Bereich lies references/go-checklist.md. Überprüfe immer dessen Abschnitte Fehler, Nebenläufigkeit und Ressourcen; die meisten Go-Fehler leben dort.

Schweregrad-Etiketten

• Blocker – Fehler, Datenrace, Goroutine-Leck, Sicherheitsproblem, kaputter Test, falsches Design. Muss vor dem Merge behoben werden.
• Should fix – Echtes Problem, nicht dringend. Der Autor kann argumentieren.
• Nit – Kleine optionale Verbesserung. Beginne den Kommentar immer mit „Nit:“.
• Frage – Etwas, das du nicht verstehst. Wenn du es nicht verstehst, werden andere es auch nicht; bitte um klareren Code.

Erfinde keine Probleme. Eine gute Änderung erhält ein kurzes Review. Wenn du dir nicht sicher bist, ob etwas ein Fehler ist, verwende Frage, nicht Blocker. Wenn du gebeten wirst, nur bestimmte Dateien oder Aspekte zu reviewen, sage, welche Teile du reviewt hast.

Ausgabeformat

## Zusammenfassung
1–2 Sätze: Was die Änderung tut. Urteil: Zustimmen / Mit Kommentaren zustimmen / Änderungen erforderlich.

## Blocker
- `path/file.go:42` – Was falsch ist und warum es wichtig ist.
```go
  // vorgeschlagene Korrektur
```

## Sollte behoben werden
## Nits
## Fragen
## Gute Dinge

## Was ich überprüft habe
Ausgeführte Tools und Ergebnisse, überprüfte Dateien, alles, was übersprungen wurde.

Leere Abschnitte weglassen. Jeder Kommentar: Problem, warum, Korrektur. Kurz halten.