Annotazione di code review

Rivedi l'output dei coding agent AI con commenti inline sui diff in stile PR di GitHub, valutazioni di correttezza a livello di file e verdetti di approvazione o rifiuto per la qualità del codice.

Novità della v2.4.0

Per valutare le modifiche al codice prodotte da un coding agent AI non basta un giudizio binario pass/fail. Chi fa ricerca e chi lavora nei team di ingegneria deve valutare la qualità del codice a più livelli di granularità: le singole righe possono contenere bug o violazioni di stile, interi file possono essere modificati correttamente o essere superflui, e l'insieme delle modifiche può risolvere il problema introducendo debito tecnico. È lo stesso flusso che segue un revisore umano quando esamina una pull request su GitHub.

La modalità di annotazione di code review di Potato porta l'esperienza della revisione di PR su GitHub dentro la valutazione degli agenti. Gli annotatori vedono i diff unificati di ogni file modificato dall'agente. Possono cliccare su una riga qualsiasi del diff per lasciare un commento inline con un'etichetta di categoria. Ogni file riceve una valutazione di correttezza e una di qualità. L'annotatore dà un verdetto finale: approvazione, richiesta di modifiche o solo commento. Tutto questo viene raccolto in dati di annotazione strutturati, pronti per addestrare modelli sulla qualità del codice.

Commenti inline

Gli annotatori cliccano su una riga qualsiasi di un diff per aprire il form del commento inline. Ogni commento ha una categoria, una gravità e un contenuto in testo libero. Il commento compare ancorato alla riga specifica, come i commenti di revisione delle PR su GitHub.

Categorie di commento

Le categorie di commento predefinite coprono i tipi di feedback più comuni nelle code review:

Categoria	Descrizione
`bug`	Bug funzionale — il codice non funzionerà correttamente
`logic`	Errore logico — l'approccio è sbagliato anche se la sintassi è valida
`security`	Vulnerabilità di sicurezza o pratica non sicura
`performance`	Problema di prestazioni — calcoli superflui, memory leak, ecc.
`style`	Violazione di stile — nomi, formattazione, uso idiomatico
`suggestion`	Approccio alternativo che sarebbe migliore
`question`	Serve un chiarimento — il revisore non è sicuro dell'intento
`praise`	Feedback positivo — qualcosa che l'agente ha fatto bene

Configurazione

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

Modifiche di codice suggerite

Quando allow_suggestions è attivo, gli annotatori possono scrivere una sostituzione suggerita per il blocco di codice che stanno commentando. Ricalca la funzione «suggestion» di GitHub. Il suggerimento compare in un blocco di codice sotto il commento e può servire ad addestrare modelli di riparazione del codice.

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])"
}

Valutazioni a livello di file

Ogni file modificato dall'agente riceve due valutazioni indipendenti: correttezza e qualità del codice.

Configurazione

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

Formato di output

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
    }
  }
}

Verdetto complessivo

Dopo aver rivisto tutti i file e lasciato i commenti inline, l'annotatore dà un verdetto complessivo sull'intero insieme di modifiche.

Configurazione

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

Riferimento di configurazione

Ecco una configurazione completa per un task di annotazione di code review:

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"

Il flusso di annotazione

Ecco che cosa vedono e che cosa fanno gli annotatori mentre completano un task di annotazione di code review:

Panoramica del task: in cima compare la descrizione del task, che indica che cosa era stato chiesto all'agente (per esempio, «Correggi il test che fallisce in test_parser.py»).
Navigazione nell'albero dei file: la sidebar di sinistra mostra tutti i file toccati dall'agente. I file hanno un codice colore: verde per i nuovi, giallo per i modificati, rosso per gli eliminati.
Revisione dei diff: il pannello principale mostra i diff unificati di ogni file. Gli annotatori li scorrono leggendo ogni modifica.
Aggiunta di commenti inline: cliccando su un numero di riga si apre il form del commento. L'annotatore sceglie una categoria (bug, suggerimento, ecc.), se vuole indica una gravità, scrive il commento e, volendo, aggiunge un suggerimento di codice.
Valutazioni dei file: dopo aver rivisto il diff di ciascun file, l'annotatore lo valuta su correttezza (1-5) e qualità del codice (1-5) usando i widget di valutazione sotto il diff di ogni file.
Verdetto complessivo: in fondo l'annotatore sceglie un verdetto (approvazione, richiesta di modifiche o solo commento) e scrive un riepilogo della revisione.
Invio: l'annotatore clicca su «Submit» per salvare tutti i commenti inline, le valutazioni dei file e il verdetto come un unico record di annotazione.

Formato dei dati

L'output completo di una singola annotazione di code review:

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."
    }
  }
}

Esportazione

Le annotazioni di code review si esportano in diversi formati:

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

Il formato code_review_comments torna particolarmente utile per addestrare modelli che generano commenti di revisione o che prevedono la posizione e la categoria dei problemi nel codice.

Vedi anche

Annotazione di coding agent — mostra le tracce dei coding agent con rendering dei diff e albero dei file
Annotazione di process reward — segnali di reward passo per passo per addestrare un PRM
Osservazione dal vivo di un coding agent — osserva i coding agent e interagisci con loro in tempo reale
Annotazione agentica — annotazione generica di tracce di agenti
Formati di esportazione — tutti i formati di esportazione supportati

Per i dettagli implementativi, vedi la documentazione sorgente.