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:
  - name: inline_comments
    annotation_type: code_review_comments
    description: "Click any diff line to add an inline comment"
 
    inline_comments:
      # Comment categories
      categories:
        - value: bug
          display: "Bug"
          color: "#ef4444"
          icon: "bug"
        - value: logic
          display: "Logic Error"
          color: "#f97316"
          icon: "alert-triangle"
        - value: security
          display: "Security"
          color: "#dc2626"
          icon: "shield-alert"
        - value: performance
          display: "Performance"
          color: "#eab308"
          icon: "zap"
        - value: style
          display: "Style"
          color: "#6b7280"
          icon: "palette"
        - value: suggestion
          display: "Suggestion"
          color: "#3b82f6"
          icon: "lightbulb"
        - value: question
          display: "Question"
          color: "#8b5cf6"
          icon: "help-circle"
        - value: praise
          display: "Praise"
          color: "#22c55e"
          icon: "thumbs-up"
 
      # Severity levels (optional)
      severity:
        enabled: true
        levels:
          - value: critical
            display: "Critical"
          - value: major
            display: "Major"
          - value: minor
            display: "Minor"
          - value: nit
            display: "Nit"
 
      # Behavior
      require_category: true
      require_severity: false
      allow_multi_line: true       # comments can span a range of lines
      allow_suggestions: true      # annotator can write suggested replacement code
      min_comments: 0              # minimum comments required before submission

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.

yaml

# In inline comment output:
{
  "file": "src/parser.py",
  "line_start": 42,
  "line_end": 44,
  "category": "bug",
  "severity": "critical",
  "comment": "Off-by-one error: range should be inclusive of end",
  "suggestion": "for i in range(start, end + 1):\n    process(tokens[i])"
}

Bewertungen pro Datei

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

Konfiguration

yaml

annotation_schemes:
  - name: file_ratings
    annotation_type: code_review_file_ratings
    description: "Rate each modified file"
 
    file_ratings:
      dimensions:
        - name: correctness
          display: "Correctness"
          description: "Are the changes to this file functionally correct?"
          scale:
            min: 1
            max: 5
            labels:
              1: "Broken -- introduces bugs or breaks existing functionality"
              2: "Mostly broken -- significant functional issues"
              3: "Partially correct -- works but has edge cases or minor bugs"
              4: "Mostly correct -- minor issues only"
              5: "Fully correct -- changes work as intended"
 
        - name: quality
          display: "Code Quality"
          description: "How well-written are the changes to this file?"
          scale:
            min: 1
            max: 5
            labels:
              1: "Very poor -- unreadable, no structure"
              2: "Poor -- hard to follow, inconsistent style"
              3: "Acceptable -- works but could be cleaner"
              4: "Good -- clean, idiomatic, well-structured"
              5: "Excellent -- exemplary code, would merge as-is"
 
      # Files to rate
      include_unchanged: false     # only rate files the agent modified
      include_new_files: true      # include files the agent created
      include_deleted_files: true  # include files the agent deleted
 
      # Behavior
      require_all_files: true      # must rate every modified file

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:
  - name: verdict
    annotation_type: code_review_verdict
    description: "Give an overall verdict on the code changes"
 
    verdict:
      options:
        - value: approve
          display: "Approve"
          description: "Changes are correct and ready to merge"
          color: "#22c55e"
          icon: "check-circle"
        - value: request_changes
          display: "Request Changes"
          description: "Changes need fixes before merging"
          color: "#ef4444"
          icon: "x-circle"
        - value: comment_only
          display: "Comment Only"
          description: "Leaving feedback without a verdict"
          color: "#6b7280"
          icon: "message-circle"
 
      # Optional summary text
      require_summary: true
      summary_placeholder: "Summarize your review..."
      summary_min_length: 20

Konfigurationsreferenz

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

yaml

task_name: "Coding Agent Code Review"
task_dir: "."
 
data_files:
  - "data/coding_traces.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified
    diff_context_lines: 5
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    file_tree:
      enabled: true
      position: left
      show_operation_icons: true
      click_to_navigate: true
 
annotation_schemes:
  # Inline comments on diff lines
  - name: inline_comments
    annotation_type: code_review_comments
    inline_comments:
      categories:
        - { value: bug, display: "Bug", color: "#ef4444" }
        - { value: logic, display: "Logic Error", color: "#f97316" }
        - { value: security, display: "Security", color: "#dc2626" }
        - { value: performance, display: "Performance", color: "#eab308" }
        - { value: style, display: "Style", color: "#6b7280" }
        - { value: suggestion, display: "Suggestion", color: "#3b82f6" }
        - { value: question, display: "Question", color: "#8b5cf6" }
        - { value: praise, display: "Praise", color: "#22c55e" }
      severity:
        enabled: true
        levels:
          - { value: critical, display: "Critical" }
          - { value: major, display: "Major" }
          - { value: minor, display: "Minor" }
          - { value: nit, display: "Nit" }
      require_category: true
      allow_multi_line: true
      allow_suggestions: true
 
  # File-level correctness and quality
  - name: file_ratings
    annotation_type: code_review_file_ratings
    file_ratings:
      dimensions:
        - name: correctness
          display: "Correctness"
          scale: { min: 1, max: 5 }
        - name: quality
          display: "Code Quality"
          scale: { min: 1, max: 5 }
      require_all_files: true
 
  # Overall verdict
  - name: verdict
    annotation_type: code_review_verdict
    verdict:
      options:
        - { value: approve, display: "Approve", color: "#22c55e" }
        - { value: request_changes, display: "Request Changes", color: "#ef4444" }
        - { value: comment_only, display: "Comment Only", color: "#6b7280" }
      require_summary: true
      summary_min_length: 20
 
output_annotation_dir: "output/"
output_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

{
  "id": "trace_042",
  "annotator": "reviewer_01",
  "timestamp": "2025-01-15T14:30:00Z",
  "annotations": {
    "inline_comments": [
      {
        "file": "src/parser.py",
        "line_start": 42,
        "line_end": 42,
        "category": "bug",
        "severity": "critical",
        "comment": "This will throw IndexError when tokens list is empty",
        "suggestion": "if tokens:\n    return tokens[0]\nreturn None"
      },
      {
        "file": "src/parser.py",
        "line_start": 15,
        "line_end": 15,
        "category": "style",
        "severity": "nit",
        "comment": "Variable name 'x' is not descriptive"
      },
      {
        "file": "tests/test_parser.py",
        "line_start": 28,
        "line_end": 30,
        "category": "praise",
        "comment": "Good edge case coverage for empty input"
      }
    ],
    "file_ratings": {
      "src/parser.py": { "correctness": 3, "quality": 2 },
      "tests/test_parser.py": { "correctness": 5, "quality": 4 }
    },
    "verdict": {
      "decision": "request_changes",
      "summary": "The core fix is on the right track but has an edge case bug with empty input. The test coverage is good. Fix the IndexError and clean up variable naming."
    }
  }
}

Export

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

bash

# Export as structured code review JSON
python -m potato.export \
  -i output/ \
  -f code_review \
  -o results/reviews.jsonl
 
# Export inline comments only (for training code comment models)
python -m potato.export \
  -i output/ \
  -f code_review_comments \
  -o results/comments.jsonl
 
# Export file ratings as a CSV (for analysis)
python -m potato.export \
  -i output/ \
  -f code_review_file_ratings \
  -o results/file_ratings.csv
 
# Export verdict distribution summary
python -m potato.export \
  -i output/ \
  -f code_review_verdicts \
  -o results/verdicts.json

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.