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

Revise a saída de agentes de codificação com IA usando comentários inline em diffs no estilo de PRs do GitHub, avaliações de correção por arquivo e veredictos de aprovação ou rejeição para avaliar a qualidade do 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:

Categoria	Descrição
`bug`	Bug funcional -- o código não vai funcionar corretamente
`logic`	Erro de lógica -- a abordagem é falha mesmo que a sintaxe seja válida
`security`	Vulnerabilidade de segurança ou prática insegura
`performance`	Problema de desempenho -- computação desnecessária, vazamento de memória, etc.
`style`	Violação de estilo -- nomenclatura, formatação, uso idiomático
`suggestion`	Abordagem alternativa que seria melhor
`question`	Esclarecimento necessário -- o revisor não tem certeza sobre a intenção
`praise`	Retorno positivo -- algo que o agente fez bem

Configuração

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

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.

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

Avaliações por arquivo

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

Configuração

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

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

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

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

Referência de configuração

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

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"

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:

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").
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.
Revisão do diff: o painel principal mostra diffs unificados de cada arquivo. Os anotadores rolam pelos diffs, lendo cada mudança.
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.
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.
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.
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:

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

Exportação

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

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

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.