Anotación de Revisión de Código

Revisa la salida de agentes de coding con IA mediante comentarios en línea sobre el diff al estilo de PR de GitHub, valoraciones de corrección por archivo y veredictos de aprobación o rechazo para evaluar la calidad del código.

Novedad en la v2.4.0

Evaluar los cambios de código que producen los agentes de coding con IA exige algo más que un juicio binario de pasa o no pasa. Los equipos de investigación e ingeniería necesitan valorar la calidad del código a varias granularidades: una línea puede contener un error o una violación de estilo, un archivo entero puede estar bien modificado o sobrar, y el conjunto de cambios puede resolver el problema y a la vez introducir deuda técnica. Es el mismo flujo de trabajo que siguen las personas que revisan pull requests en GitHub.

El modo de anotación de revisión de código de Potato traslada la experiencia de revisión de PR de GitHub a la evaluación de agentes. Los anotadores ven diffs unificados de cada archivo que modificó el agente. Pueden pulsar cualquier línea del diff para dejar un comentario en línea con una etiqueta de categoría. Cada archivo recibe una valoración de corrección y otra de calidad. El anotador emite un veredicto final: aprobar, pedir cambios o solo comentar. Todo esto queda recogido en datos de anotación estructurados, listos para entrenar modelos de calidad de código.

Comentarios en Línea

Los anotadores pulsan cualquier línea de un diff para abrir un formulario de comentario en línea. Cada comentario tiene una categoría, una severidad y contenido en texto libre. El comentario aparece anclado a esa línea concreta, igual que los comentarios de revisión de PR de GitHub.

Categorías de Comentarios

Las categorías de comentario por defecto cubren los tipos de retroalimentación más habituales en una revisión de código:

Categoría	Descripción
`bug`	Error funcional -- el código no funcionará correctamente
`logic`	Error de lógica -- el enfoque está mal aunque la sintaxis sea válida
`security`	Vulnerabilidad de seguridad o práctica insegura
`performance`	Problema de rendimiento -- cálculo innecesario, fuga de memoria, etc.
`style`	Violación de estilo -- nomenclatura, formato, uso idiomático
`suggestion`	Enfoque alternativo que sería mejor
`question`	Hace falta una aclaración -- el revisor no tiene clara la intención
`praise`	Retroalimentación positiva -- algo que el agente hizo bien

Configuración

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

Cambios de Código Sugeridos

Con allow_suggestions activado, los anotadores pueden escribir un reemplazo sugerido para el bloque de código que están comentando. Reproduce la función de «suggestion» de GitHub. La sugerencia aparece en un bloque de código debajo del comentario y sirve para entrenar modelos de reparación 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])"
}

Valoraciones por Archivo

Cada archivo modificado por el agente recibe dos valoraciones independientes: corrección y calidad de código.

Configuración

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 Salida

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 Global

Tras revisar todos los archivos y dejar los comentarios en línea, el anotador emite un veredicto global sobre el conjunto de cambios.

Configuración

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

Referencia de Configuración

Esta es una configuración completa para una tarea de anotación de revisión 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"

El Flujo de Trabajo de Anotación

Esto es lo que ven y hacen los anotadores al completar una tarea de anotación de revisión de código:

Visión general de la tarea: la descripción de la tarea aparece arriba y muestra qué se le pidió al agente (por ejemplo, «Arreglar la prueba que falla en test_parser.py»).
Navegación por el árbol de archivos: la barra lateral izquierda muestra todos los archivos que tocó el agente. Los archivos van con código de color: verde para los nuevos, amarillo para los modificados y rojo para los borrados.
Revisión del diff: el panel principal muestra diffs unificados de cada archivo. Los anotadores recorren los diffs leyendo cada cambio.
Añadir comentarios en línea: al pulsar un número de línea se abre un formulario de comentario. El anotador selecciona una categoría (bug, sugerencia, etc.), opcionalmente elige una severidad, escribe su comentario y, si quiere, añade una sugerencia de código.
Valoraciones por archivo: tras revisar el diff de cada archivo, el anotador lo valora en corrección (1-5) y calidad de código (1-5) con los controles de valoración que hay debajo del diff de cada archivo.
Veredicto global: al final, el anotador elige un veredicto (aprobar, pedir cambios o solo comentar) y escribe un resumen de su revisión.
Envío: el anotador pulsa «Submit» para guardar todos los comentarios en línea, las valoraciones por archivo y el veredicto como un único registro de anotación.

Formato de Datos

La salida completa de una anotación de revisión 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."
    }
  }
}

Exportación

Las anotaciones de revisión de código se pueden exportar en varios 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

El formato code_review_comments resulta especialmente útil para entrenar modelos que generen comentarios de revisión o que predigan la ubicación y la categoría de los problemas del código.

Véase También

Anotación de Agente de Coding -- muestra trazas de agentes de coding con renderizado de diffs y árboles de archivos
Anotación de Recompensa de Proceso -- señales de recompensa por paso para entrenar PRM
Observación de Agentes de Coding en Vivo -- observa e interactúa con agentes de coding en tiempo real
Anotación Agéntica -- anotación de trazas de agente de propósito general
Formatos de Exportación -- todos los formatos de exportación admitidos

Para detalles de implementación, consulta la documentación fuente.