Anotação de Revisão de Código

Novidade na v2.4.0

Avaliar mudanças de código produzidas por agentes de codificação com IA exige mais do que um julgamento binário de aprovado/reprovado. Pesquisadores e equipes de engenharia precisam avaliar a qualidade do código em várias granularidades: linhas individuais podem conter bugs ou violações de estilo, arquivos inteiros podem ter sido modificados corretamente ou ser desnecessários, e o conjunto geral de mudanças pode resolver o problema, mas introduzir dívida técnica. Esse é o mesmo fluxo de trabalho que os revisores de código humanos seguem ao revisar pull requests no GitHub.

O modo de anotação de revisão de código do Potato traz a experiência de revisão de PR do GitHub para a avaliação de agentes. Os anotadores veem diffs unificados de cada arquivo que o agente modificou. Eles podem clicar em qualquer linha do diff para deixar um comentário inline com uma etiqueta de categoria. Cada arquivo recebe uma avaliação de correção e de qualidade. O anotador dá um veredicto final: aprovar, solicitar mudanças ou apenas comentar. Tudo isso é capturado em dados de anotação estruturados, prontos para treinar modelos de qualidade de código.

Comentários inline

Os anotadores clicam em qualquer linha de um diff para abrir um formulário de comentário inline. Cada comentário tem uma categoria, uma severidade e um conteúdo em texto livre. O comentário aparece ancorado à linha específica, exatamente como os comentários de revisão de PR do GitHub.

Categorias de comentário

As categorias de comentário padrão cobrem os tipos mais comuns de retorno em revisões de código:

Configuração

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

Mudanças de código sugeridas

Quando allow_suggestions está habilitado, os anotadores podem escrever uma substituição sugerida para o bloco de código que estão comentando. Isso espelha o recurso de "suggestion" do GitHub. A sugestão aparece em um bloco de código abaixo do comentário e pode ser usada para treinar modelos de reparo de código.

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

Avaliações por arquivo

Cada arquivo modificado pelo agente recebe duas avaliações independentes: correção e qualidade do código.

Configuração

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 de saída

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

Veredicto geral

Após revisar todos os arquivos e deixar comentários inline, o anotador dá um veredicto geral para o conjunto inteiro de mudanças.

Configuração

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

Referência de configuração

A seguir está uma configuração completa para uma tarefa de anotação de revisão de código:

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, 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/"
output_annotation_format: "jsonl"

O fluxo de anotação

Veja o que os anotadores observam e fazem ao completar uma tarefa de anotação de revisão de código:

1. Visão geral da tarefa: a descrição da tarefa aparece no topo, mostrando o que o agente foi solicitado a fazer (por exemplo, "Corrigir o teste que falha em test_parser.py").

2. Navegação na árvore de arquivos: a barra lateral esquerda mostra todos os arquivos que o agente tocou. Os arquivos têm cores: verde para arquivos novos, amarelo para arquivos modificados, vermelho para arquivos excluídos.

3. Revisão do diff: o painel principal mostra diffs unificados de cada arquivo. Os anotadores rolam pelos diffs, lendo cada mudança.

4. Adicionando comentários inline: clicar em um número de linha abre um formulário de comentário. O anotador seleciona uma categoria (bug, suggestion, etc.), opcionalmente seleciona uma severidade, escreve seu comentário e, opcionalmente, adiciona uma sugestão de código.

5. Avaliações de arquivo: depois de revisar o diff de cada arquivo, o anotador o avalia em correção (1-5) e qualidade do código (1-5) usando os widgets de avaliação abaixo do diff de cada arquivo.

6. Veredicto geral: na parte inferior, o anotador seleciona um veredicto (aprovar, solicitar mudanças ou apenas comentar) e escreve um resumo da sua revisão.

7. Envio: o anotador clica em "Submit" para salvar todos os comentários inline, as avaliações de arquivo e o veredicto como um único registro de anotação.

Formato dos dados

A saída completa para uma única anotação de revisão de código:

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

Exportação

As anotações de revisão de código podem ser exportadas em vários formatos:

# 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

O formato code_review_comments é especialmente útil para treinar modelos que geram comentários de revisão de código ou que preveem a localização e a categoria de problemas no código.

Veja também

• Anotação de Agente de Codificação -- exibe traços de agentes de codificação com renderização de diff e árvores de arquivos
• Anotação de Recompensa de Processo -- sinais de recompensa por etapa para treinamento de PRM
• Observação de Agente de Codificação ao Vivo -- observe e interaja com agentes de codificação em tempo real
• Anotação Agêntica -- anotação de traços de agentes de uso geral
• Formatos de Exportação -- todos os formatos de exportação suportados

Para detalhes de implementação, consulte a documentação de origem.