Anotación de Revisión de 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:

Configuración

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

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.

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

Valoraciones por Archivo

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

Configuración

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 Salida

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

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

Referencia de Configuración

Esta es una configuración completa para una tarea de anotación de revisión de código:

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"

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:

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

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

3. Revisión del diff: el panel principal muestra diffs unificados de cada archivo. Los anotadores recorren los diffs leyendo cada cambio.

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

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

6. Veredicto global: al final, el anotador elige un veredicto (aprobar, pedir cambios o solo comentar) y escribe un resumen de su revisión.

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

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

Exportación

Las anotaciones de revisión de código se pueden exportar en varios formatos:

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

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.