Zum Inhalt

Code-Review-Report-Template

Dieses Template ist verpflichtend für alle Block-Abschlüsse ab Block 3.

Das installierte code-review-Plugin ist PR-orientiert und liefert seine Findings in einem Format, das für den Kontext dieses Projekts (lokale Branch-Entwicklung, keine PRs) angepasst werden muss. Das Template hält das Ergebnis so fest, dass die Deferred-Items für offene-todos.md ohne Retro-Arbeit übernommen werden können.

Prompt-Erweiterung für zukünftige Block-Prompts

Im Block-Commit-Abschnitt jedes Block-Prompts folgende Passage einbauen:

Mandatory Code Review (erweitertes Reporting): Nach Implementierung und vor dem Commit:

  1. code-review-Plugin (oder Agent mit klarem Diff-Scope) auf den geänderten Code anwenden.
  2. Für jedes Finding folgende Felder im Report liefern:
    • ID (H1, H2, M1, M2, L1, …) mit Severity-Score (0–100)
    • Datei:Zeile
    • 2–3 Sätze Problem-Beschreibung
    • 1–2 Sätze Lösungsvorschlag
    • Entscheidung: Fix-Now / Deferred / False-Positive
    • Bei Deferred: Rationale in einem Satz (mit konkretem Trigger, wann das fixiert wird)
    • Bei False-Positive: kurze Begründung, warum das Finding nicht zutrifft (z. B. "Konzept §X schließt das explizit aus")
  3. High-Severity-Findings (Score ≥ 80) IMMER fixen vor Commit.
  4. Medium-Severity (Score 50–79): Fix-Now, außer mit expliziter Deferral-Begründung.
  5. Low-Severity (Score < 50): Deferral ist Default, Fix optional.
  6. Alle Deferred-Items in docs-kora/offene-todos.md unter Aus Block <N> — <Titel> (Commit <hash>) eintragen BEVOR committed wird. Schema: TODO-B<N>-<NN>. False-Positives werden NICHT in offene-todos.md geführt, nur im Report referenziert.
  7. Integration-Learnings (Überraschungen, Workarounds, nicht-offensichtliche Fixes aus dem Block) als L-B<N>-<NN> in offene-todos.md unter "Integration-Learnings" eintragen.

  8. Report-Output:

    ### Code-Review — Block <N>

**<M> Findings, <X> Fix-Now, <Y> Deferred, <Z> False-Positive**

| ID | Sev | Datei:Zeile | Titel | Entscheidung |
|---|---|---|---|---|
| H1 | 92 | file.py:42 | Resource-Leak | Fix-Now |
| M1 | 65 | other.py:10 | Input-Validation | Deferred (Block X) |
| M2 | 55 | ... | TOTP-Enforcement | False-Positive (Konzept §2.6) |

**Details:**

<pro Finding: 4–5 Zeilen mit Problem, Lösung, Entscheidung, bei
Deferred + Rationale, bei False-Positive + Begründung>

**Deferred-Items nach `offene-todos.md` übertragen:** TODO-B<N>-01 …
TODO-B<N>-<YY>
**Integration-Learnings nach `offene-todos.md` übertragen:** L-B<N>-01 …
L-B<N>-<ZZ>

Severity-Scoring-Guide

Score Kategorie Beispiele
90–100 Critical SQL-Injection, Auth-Bypass, Secret im Code, Data-Loss-Risk ohne Recovery
80–89 High Resource-Leak, fehlendes Error-Handling bei kritischen Pfaden, Race-Condition, ungeprüfter externer Input bei Admin-Operationen
60–79 Medium Ineffiziente Queries in Hot-Paths, fehlende Input-Validation bei Admin-Endpoints, unklare API-Design-Entscheidung mit Follow-up-Wirkung
40–59 Low Naming-Inkonsistenz, fehlende Docstrings bei Public-API, Minor-Performance, Log-Leak von Debug-Infos
< 40 Nitpick Formatierung, optionale Refactorings, Style-Präferenzen

Ein Finding wird nur dann auf ≥ 80 gehoben, wenn der Reviewer einen konkreten Weg beschreiben kann, wie der Issue in realistischer Nutzung eintritt. "Könnte theoretisch" reicht nicht — Score 50 ist die Default- Position für "plausibel, aber nicht bewiesen".

Deferral-Rationale-Beispiele

Gute Deferral-Begründungen:

  • "Betrifft Pfad, der in Block X ohnehin umgebaut wird (Refactoring wäre doppelt)."
  • "Low-Severity, einziger Caller ist interner Admin-Flow; Block 16 Testing & Docs deckt das Thema ganzheitlich."
  • "Wartet auf Infrastruktur aus Block Y (z. B. Rate-Limiting-Framework, Correlation-ID-Middleware)."
  • "Kosmetik, wird mit anderen Naming-Bereinigungen im Phase-A-Abschluss-Refactor gebündelt."

Schlechte Deferral-Begründungen (nicht akzeptiert):

  • "Später, wenn Zeit ist" — kein konkreter Trigger.
  • "Probably fine in practice" — Severity überdenken oder Risiko konkret argumentieren.
  • "Würde größeren Refactor erfordern" — wenn Severity es rechtfertigt: machen oder Severity anzweifeln.

False-Positive-Beispiele

Ein Finding wird als False-Positive markiert, wenn:

  • Das Konzept (docs-kora/konzepte/multitenancy-fundament.md) das Verhalten explizit als gewollt beschreibt. Beispiel: Reviewer fordert TOTP-Enforcement für Vendor-User, aber Konzept §2.6 nennt nur "Login wird auditiert".
  • Die Spec des Block-Prompts das Verhalten explizit anders fordert. Beispiel: Reviewer fordert Backfill-Fenster beim Audit-Poller-Start, aber der Block-Prompt fordert "Cursor auf 'jetzt' beim ersten Start, keine historischen Events nachsenden".
  • Der Reviewer eine nicht existierende Funktion/Abhängigkeit annimmt (meistens Tooling-bedingt).

In allen drei Fällen: kurze Begründung in den Details, False-Positive- Zähler hochzählen, nicht nach offene-todos.md übernehmen.

Retro-Beispiel: Block 2

Block 2 hat den Review-Flow zum ersten Mal durchlaufen. Die Ergebnisse liegen in offene-todos.md als TODO-B2-01 bis TODO-B2-08 und L-B2-01 bis L-B2-04. Der Review-Lauf fand nach dem ursprünglichen Commit statt (2 False-Positives wurden nicht explizit als solche markiert, sondern implizit nicht gefixt); genau diese Retro-Arbeit soll das Template künftig verhindern.