Skip to content

Разметка ревью кода

Разбирайте вывод ИИ-агентов по коду с комментариями прямо в диффе в стиле пул-реквестов GitHub, оценками корректности по файлам и вердиктами о принятии или отклонении.

Появилось в v2.4.0

Оценка изменений кода, сделанных ИИ-агентами, требует не просто вердикта «сдал или нет». Исследователям и инженерным командам нужно судить о качестве кода на нескольких уровнях: в отдельных строках могут быть ошибки или нарушения стиля, целые файлы могут быть изменены верно или изменены зря, а весь набор правок может решать задачу, но добавлять технический долг. Это тот же процесс, которому следуют живые ревьюеры, разбирая пул-реквесты на GitHub.

Режим разметки ревью кода в Potato приносит опыт разбора пул-реквестов GitHub в оценку агентов. Разметчик видит единые диффы по каждому файлу, который агент изменил. Он может кликнуть по любой строке диффа и оставить комментарий с категорией. Каждый файл получает оценку корректности и качества. В конце разметчик выносит вердикт: принять, вернуть на доработку или только прокомментировать. Всё это сохраняется структурными данными разметки, готовыми для обучения моделей качества кода.

Комментарии в строках

Разметчик кликает по любой строке диффа, и открывается форма комментария. У каждого комментария есть категория, серьёзность и свободный текст. Комментарий крепится к конкретной строке, как комментарии при разборе пул-реквеста на GitHub.

Категории комментариев

Категории по умолчанию покрывают самые частые виды замечаний при разборе кода:

КатегорияОписание
bugФункциональная ошибка — код не будет работать правильно
logicОшибка в логике — подход неверен, даже если синтаксис в порядке
securityУязвимость или небезопасная практика
performanceПроблема производительности — лишние вычисления, утечка памяти и т. п.
styleНарушение стиля — именование, форматирование, неидиоматичность
suggestionАльтернативный подход, который был бы лучше
questionНужно уточнение — ревьюер не уверен в замысле
praiseПоложительный отзыв — что-то, что агент сделал хорошо

Конфигурация

yaml
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

Предлагаемые правки кода

Когда включён allow_suggestions, разметчик может написать предлагаемую замену для блока кода, который комментирует. Это повторяет функцию «suggestion» на GitHub. Предложение выводится блоком кода под комментарием и может использоваться для обучения моделей исправления кода.

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

Оценки по файлам

Каждый изменённый агентом файл получает две независимые оценки: корректность и качество кода.

Конфигурация

yaml
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

Формат вывода

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

Итоговый вердикт

Разобрав все файлы и оставив комментарии в строках, разметчик выносит общий вердикт по всему набору изменений.

Конфигурация

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

Справочник по конфигурации

Вот законченная конфигурация задачи разметки ревью кода:

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

Как идёт разметка

Вот что разметчик видит и делает, выполняя задачу разметки ревью кода:

  1. Обзор задачи: сверху выводится описание задачи — что агента просили сделать (например, «Fix the failing test in test_parser.py»).

  2. Навигация по дереву файлов: в левой панели видны все файлы, которых агент касался. Файлы окрашены: зелёные — новые, жёлтые — изменённые, красные — удалённые.

  3. Разбор диффа: в основной панели выводятся единые диффы по каждому файлу. Разметчик прокручивает их, читая каждое изменение.

  4. Комментарии в строках: клик по номеру строки открывает форму комментария. Разметчик выбирает категорию (ошибка, предложение и т. д.), при желании выставляет серьёзность, пишет комментарий и при желании добавляет предлагаемую правку кода.

  5. Оценки файлов: разобрав дифф каждого файла, разметчик оценивает его по корректности (1–5) и качеству кода (1–5) виджетами под диффом файла.

  6. Итоговый вердикт: внизу разметчик выбирает вердикт (принять, вернуть на доработку или только прокомментировать) и пишет краткое резюме разбора.

  7. Отправка: разметчик нажимает «Submit», и все комментарии в строках, оценки файлов и вердикт сохраняются одной записью разметки.

Формат данных

Полный вывод для одной разметки ревью кода:

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

Экспорт

Разметку ревью кода можно выгрузить в нескольких форматах:

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

Формат code_review_comments особенно полезен для обучения моделей, которые пишут комментарии к коду или предсказывают место и категорию проблемы.

Смотрите также

Детали реализации — в исходной документации.