Code-Review-Annotation

Ausgaben von KI-Coding-Agenten prüfen: Inline-Kommentare im Diff im Stil eines GitHub-PR, Korrektheitsbewertungen pro Datei und Urteile zu Freigabe oder Ablehnung für die Bewertung der Codequalität.

Neu in v2.4.0

Codeänderungen von KI-Coding-Agenten zu bewerten, verlangt mehr als ein binäres Pass/Fail-Urteil. Forschungsgruppen und Engineering-Teams müssen Codequalität auf mehreren Granularitätsstufen einschätzen: Einzelne Zeilen können Bugs oder Stilverstöße enthalten, ganze Dateien können korrekt geändert oder schlicht überflüssig sein, und die Änderung insgesamt kann das Problem lösen und dabei technische Schulden aufbauen. Genau nach diesem Ablauf arbeiten menschliche Reviewer, wenn sie Pull Requests auf GitHub durchsehen.

Der Code-Review-Modus von Potato bringt die Review-Erfahrung eines GitHub-PR in die Agent-Evaluation. Annotatoren sehen Unified Diffs für jede Datei, die der Agent geändert hat. Sie können auf eine beliebige Diff-Zeile klicken und dort einen Inline-Kommentar mit Kategorie hinterlassen. Jede Datei bekommt eine Bewertung für Korrektheit und Qualität. Am Ende fällt der Annotator ein Urteil: freigeben, Änderungen anfordern oder nur kommentieren. All das landet in strukturierten Annotationsdaten, die sich direkt zum Training von Modellen für Codequalität nutzen lassen.

Inline-Kommentare

Annotatoren klicken auf eine beliebige Zeile in einem Diff und öffnen damit ein Formular für einen Inline-Kommentar. Jeder Kommentar hat eine Kategorie, einen Schweregrad und Freitext. Der Kommentar erscheint an der jeweiligen Zeile verankert, genau wie Review-Kommentare in einem GitHub-PR.

Kommentarkategorien

Die voreingestellten Kategorien decken die häufigsten Arten von Review-Rückmeldungen ab:

Kategorie	Beschreibung
`bug`	Funktionaler Bug -- der Code funktioniert nicht korrekt
`logic`	Logikfehler -- der Ansatz ist fehlerhaft, auch wenn die Syntax stimmt
`security`	Sicherheitslücke oder unsichere Praxis
`performance`	Performance-Problem -- unnötige Berechnung, Speicherleck usw.
`style`	Stilverstoß -- Benennung, Formatierung, idiomatische Verwendung
`suggestion`	Alternativer Ansatz, der besser wäre
`question`	Klärungsbedarf -- der Reviewer ist sich über die Absicht unsicher
`praise`	Positive Rückmeldung -- etwas, das der Agent gut gemacht hat

Konfiguration

yaml

annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Click any diff line to add an inline comment"
 
    # Categories offered on each inline comment
    comment_categories:
      - bug
      - logic
      - security
      - performance
      - style
      - suggestion
      - question

Vorgeschlagene Codeänderungen

Ist allow_suggestions aktiviert, können Annotatoren einen Ersatzvorschlag für den kommentierten Codeblock schreiben. Das entspricht der Suggestion-Funktion von GitHub. Der Vorschlag erscheint als Codeblock unter dem Kommentar und lässt sich zum Training von Modellen für Codereparatur verwenden.

json

{
  "category": "bug",
  "file": "src/parser.py",
  "line": 42,
  "text": "Off-by-one error: range should be inclusive of end"
}

Bewertungen pro Datei

Jede Datei, die der Agent geändert hat, bekommt zwei unabhängige Bewertungen: Korrektheit und Codequalität.

Konfiguration

yaml

annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Rate each modified file"
 
    # One 1-5 rating per dimension, per file touched by the diff
    file_rating_dimensions:
      - correctness
      - quality

Ausgabeformat

json

{
  "file_ratings": {
    "src/parser.py": {
      "correctness": 4,
      "quality": 3
    },
    "tests/test_parser.py": {
      "correctness": 5,
      "quality": 4
    },
    "src/utils.py": {
      "correctness": 2,
      "quality": 2
    }
  }
}

Gesamturteil

Nachdem alle Dateien durchgesehen und die Inline-Kommentare gesetzt sind, gibt der Annotator ein Gesamturteil über den kompletten Änderungssatz ab.

Konfiguration

yaml

annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Give an overall verdict on the code changes"
 
    verdict_options:
      - approve
      - request_changes
      - comment_only

Konfigurationsreferenz

Eine vollständige Konfiguration für eine Code-Review-Annotationsaufgabe:

yaml

annotation_task_name: "Coding Agent Code Review"
task_dir: "."
 
data_files:
  - "data/coding_traces.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
instance_display:
  fields:
    - key: structured_turns
      type: coding_trace
      label: "Agent changes"
      display_options:
        diff_view: unified
        terminal_theme: dark
        collapse_long_outputs: true
        max_output_lines: 50
        show_file_tree: true
        show_step_numbers: true
        show_reasoning: true
 
annotation_schemes:
  # Inline comments, file ratings and the overall verdict are all one scheme
  - annotation_type: code_review
    name: review
    description: "Review the agent's code changes"
    comment_categories:
      - bug
      - logic
      - security
      - performance
      - style
      - suggestion
      - question
      - praise
    file_rating_dimensions:
      - correctness
      - quality
    verdict_options:
      - approve
      - request_changes
      - comment_only
 
  # A free-text summary is a separate scheme
  - annotation_type: text
    name: summary
    description: "Summarize your review"
    rows: 4
 
output_annotation_dir: "output/"
export_annotation_format: "jsonl"

Der Annotationsablauf

Das sehen und tun Annotatoren bei einer Code-Review-Annotationsaufgabe:

Aufgabenüberblick: Oben steht die Aufgabenbeschreibung, also das, was der Agent tun sollte (etwa „Fix the failing test in test_parser.py").
Navigation im Dateibaum: Die linke Seitenleiste zeigt alle Dateien, die der Agent angefasst hat. Die Farbcodierung: grün für neue Dateien, gelb für geänderte, rot für gelöschte.
Diff-Durchsicht: Das Hauptpanel zeigt Unified Diffs für jede Datei. Annotatoren scrollen durch die Diffs und lesen jede Änderung.
Inline-Kommentare setzen: Ein Klick auf eine Zeilennummer öffnet das Kommentarformular. Der Annotator wählt eine Kategorie (Bug, Vorschlag usw.), optional einen Schweregrad, schreibt seinen Kommentar und fügt bei Bedarf einen Codevorschlag an.
Dateibewertungen: Nach der Durchsicht des Diffs einer Datei bewertet der Annotator sie über die Bewertungs-Widgets unter dem jeweiligen Diff auf Korrektheit (1-5) und Codequalität (1-5).
Gesamturteil: Ganz unten wählt der Annotator ein Urteil (freigeben, Änderungen anfordern oder nur kommentieren) und schreibt eine Zusammenfassung seines Reviews.
Absenden: Ein Klick auf „Submit" speichert alle Inline-Kommentare, Dateibewertungen und das Urteil als einen einzigen Annotationsdatensatz.

Datenformat

Die vollständige Ausgabe einer einzelnen Code-Review-Annotation:

json

{
  "instance_id": "trace_042",
  "annotator": "reviewer_01",
  "verdict": "request_changes",
  "comments": [
    {
      "category": "bug",
      "file": "src/parser.py",
      "line": 42,
      "text": "This will throw IndexError when tokens list is empty"
    },
    {
      "category": "style",
      "file": "src/parser.py",
      "line": 15,
      "text": "Variable name 'x' is not descriptive"
    },
    {
      "category": "praise",
      "file": "tests/test_parser.py",
      "line": 28,
      "text": "Good edge case coverage for empty input"
    }
  ],
  "file_ratings": {
    "src/parser.py": { "correctness": 3, "quality": 2 },
    "tests/test_parser.py": { "correctness": 5, "quality": 4 }
  }
}

Export

Code-Review-Annotationen lassen sich in mehreren Formaten exportieren:

bash

python -m potato.export \
  -c config.yaml \
  -f coding_eval \
  -o results/ \
  --option types=code_review

Das Format code_review_comments ist besonders nützlich für das Training von Modellen, die Code-Review-Kommentare erzeugen oder Ort und Kategorie von Codeproblemen vorhersagen.

Siehe auch

Annotation von Coding-Agenten -- Traces von Coding-Agenten mit Diff-Darstellung und Dateibäumen anzeigen
Process-Reward-Annotation -- Reward-Signale pro Schritt für das PRM-Training
Live-Beobachtung von Coding-Agenten -- Coding-Agenten in Echtzeit beobachten und in ihre Arbeit eingreifen
Agentische Annotation -- allgemeine Annotation von Agent-Traces
Exportformate -- alle unterstützten Exportformate

Implementierungsdetails stehen in der Quelldokumentation.