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. Предложение выводится блоком кода под комментарием и может использоваться для обучения моделей исправления кода.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Экспорт

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

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

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

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

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