Skip to content

コードレビューアノテーション

GitHub PRスタイルのインラインdiffコメント、ファイル単位の正確性評価、承認・却下の判定を使って、AIコーディングエージェントの出力をコード品質の観点からレビューします。

v2.4.0の新機能

AIコーディングエージェントが生成したコード変更の評価には、合否の二値判断以上のものが要ります。研究者やエンジニアリングチームは、複数の粒度でコード品質を見る必要があります。個々の行にバグやスタイル違反が混ざることもあれば、ファイル単位で見て変更が適切な場合も不要な場合もあり、変更セット全体としては問題を解いていても技術的負債を持ち込んでいることもあります。これは、GitHubでpull requestをレビューするときに人間のレビュアーが辿るのと同じ流れです。

Potatoのコードレビューアノテーションモードは、GitHubのPRレビュー体験をエージェント評価に持ち込みます。アノテーターは、エージェントが変更したすべてのファイルについて統一diffを見ます。diffの任意の行をクリックして、カテゴリタグ付きのインラインコメントを残せます。各ファイルには正確性と品質の評価が付きます。最後にアノテーターが判定を下します。approve、request changes、comment onlyのいずれかです。これらはすべて構造化されたアノテーションデータとして記録され、コード品質モデルの訓練にそのまま使えます。

インラインコメント

アノテーターはdiffの任意の行をクリックして、インラインコメントのフォームを開きます。各コメントにはカテゴリ、重大度、自由記述の内容があります。コメントはGitHubのPRレビューコメントと同じように、特定の行に紐づいて表示されます。

コメントカテゴリ

デフォルトのコメントカテゴリは、コードレビューで最もよく使われるフィードバックの種類を網羅しています。

カテゴリ説明
bug機能上のバグ -- コードが正しく動作しない
logicロジックの誤り -- 構文は正しくてもアプローチに欠陥がある
securityセキュリティ脆弱性、または安全でない書き方
performance性能上の問題 -- 不要な計算、メモリリークなど
styleスタイル違反 -- 命名、書式、イディオムの使い方
suggestionより良い代替アプローチ
question確認が必要 -- レビュアーが意図を掴めていない
praise肯定的なフィードバック -- エージェントがうまくやった点

設定

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

コードの修正提案

allow_suggestionsを有効にすると、アノテーターはコメント対象のコードブロックに対する置き換え案を書けます。GitHubの「suggestion」機能に相当します。提案はコメントの下にコードブロックとして表示され、コード修復モデルの訓練に利用できます。

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

ファイル単位の評価

エージェントが変更した各ファイルには、正確性とコード品質という2つの独立した評価が付きます。

設定

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

出力形式

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

設定リファレンス

コードレビューアノテーションタスクの完全な設定です。

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"

アノテーションの流れ

コードレビューアノテーションタスクで、アノテーターが目にするものと行うことは次のとおりです。

  1. タスクの概要：上部にタスクの説明が表示され、エージェントが何を指示されたかが分かります（例：「test_parser.pyの失敗しているテストを直す」）。

  2. ファイルツリーの操作：左サイドバーにエージェントが触れたすべてのファイルが並びます。ファイルは色分けされていて、新規は緑、変更は黄、削除は赤です。

  3. diffのレビュー：メインパネルに各ファイルの統一diffが表示されます。アノテーターはdiffをスクロールしながら、変更を1つずつ読んでいきます。

  4. インラインコメントの追加：行番号をクリックするとコメントフォームが開きます。アノテーターはカテゴリ（bug、suggestionなど）を選び、必要に応じて重大度を選び、コメントを書き、必要ならコードの修正提案を添えます。

  5. ファイルの評価：各ファイルのdiffをレビューしたあと、diffの下にある評価ウィジェットで正確性（1〜5）とコード品質（1〜5）を付けます。

  6. 全体の判定：一番下で判定（approve、request changes、comment only）を選び、レビューの要約を書きます。

  7. 送信：「Submit」をクリックすると、インラインコメント、ファイル評価、判定が1件のアノテーションレコードとして保存されます。

データ形式

1件のコードレビューアノテーションの完全な出力です。

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形式は、コードレビューコメントを生成するモデルや、コードの問題箇所とそのカテゴリを予測するモデルの訓練に特に向いています。

参考資料

実装の詳細については、ソースドキュメントを参照してください。