Annotazione di code review

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:

Configurazione

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

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.

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

Valutazioni a livello di file

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

Configurazione

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

Formato di output

{
  "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

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

Riferimento di configurazione

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

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"

Il flusso di annotazione

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

1. 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»).

2. 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.

3. Revisione dei diff: il pannello principale mostra i diff unificati di ogni file. Gli annotatori li scorrono leggendo ogni modifica.

4. 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.

5. 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.

6. Verdetto complessivo: in fondo l'annotatore sceglie un verdetto (approvazione, richiesta di modifiche o solo commento) e scrive un riepilogo della revisione.

7. 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:

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

Esportazione

Le annotazioni di code review si esportano in diversi formati:

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

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.