Annotation von Coding-Agenten

Traces von Coding-Agenten mit Diff-Darstellung, Terminalausgabe und Dateibaum-Navigation annotieren. Import aus Claude Code, Aider, SWE-Agent und weiteren Coding-Assistenten.

Neu in v2.4.0

Coding-Agenten -- Claude Code, Aider, SWE-Agent, OpenHands und andere -- erzeugen Traces, die sich von den Traces allgemeiner Agenten unterscheiden. Sie enthalten Code-Diffs, Terminalausgaben, Dateilesevorgänge, Verzeichnisdurchläufe und Testergebnisse. Solche Traces zu prüfen verlangt eine spezialisierte Darstellung, die den Aufbau von Codeänderungen versteht und sie in einer Form zeigt, die Softwareentwicklern vertraut ist.

Potatos CodingTraceDisplay ist ein eigener Anzeigetyp für Sitzungen von Coding-Agenten. Er stellt Unified Diffs mit rot/grün syntaxhervorgehobenen Zeilen dar, Terminalausgaben in dunklen Blöcken und Dateilesevorgänge mit Zeilennummern und bietet eine Dateibaum-Seitenleiste mit jeder Datei, die der Agent angefasst hat. Annotatoren können zwischen Dateien navigieren, lange Ausgaben auf- und zuklappen und einzelne Operationen oder den gesamten Trace bewerten.

Konfiguration

Die Coding-Trace-Anzeige in der Projektkonfiguration aktivieren:

yaml

agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    # Diff rendering
    diff_style: unified          # "unified" or "side_by_side"
    diff_context_lines: 3        # lines of context around changes
    syntax_highlight: true       # language-aware highlighting
    show_line_numbers: true
 
    # Terminal output
    terminal_theme: dark         # "dark" or "light"
    terminal_max_lines: 80       # auto-collapse after this many lines
    show_exit_codes: true
 
    # File reads
    file_read_max_lines: 100     # auto-collapse file reads longer than this
    show_file_path: true
    show_line_range: true        # display "lines 42-87" when partial reads
 
    # File tree sidebar
    file_tree:
      enabled: true
      position: left             # "left" or "right"
      show_operation_icons: true # icons for read/edit/create/delete
      group_by_directory: true
      click_to_navigate: true    # click a file to jump to its operations
 
    # Collapsible sections
    auto_collapse_threshold: 500 # characters before auto-collapsing
    collapse_file_reads: true
    collapse_terminal_output: true

Merkmale der Anzeige

Unified-Diff-Ansicht

Bearbeitungsvorgänge werden als Unified Diffs mit Rot/Grün-Markierung dargestellt. Gelöschte Zeilen erscheinen mit rotem Hintergrund und einem - davor, hinzugefügte Zeilen mit grünem Hintergrund und einem + davor. Kontextzeilen stehen in neutralem Grau. Dateipfad und Zeilenbereich stehen in einer Kopfleiste über jedem Diff-Block.

Ist diff_style: side_by_side gesetzt, erscheinen die alte und die neue Fassung in nebeneinanderliegenden Spalten, was bei komplexen Änderungen leichter erkennen lässt, was sich geändert hat.

Dunkle Terminalblöcke

Bash- und Shell-Kommandos werden in dunklen Terminalblöcken mit Festbreitenschrift dargestellt. Das Kommando selbst steht mit einem $ als Prompt-Präfix, die Ausgabe darunter. Exit-Codes erscheinen in einem kleinen Badge (grün für 0, rot für alles andere). Lange Ausgaben werden automatisch eingeklappt und lassen sich über „Show N more lines" wieder aufklappen.

Dateilesevorgänge mit Zeilennummern

Liest der Agent eine Datei, wird der Inhalt mit Zeilennummern in einem hellen Codeblock angezeigt. Bei Teilausschnitten steht der Zeilenbereich dabei (etwa „lines 42-87 of 312"). Die Syntaxhervorhebung richtet sich nach der Dateiendung.

Dateibaum-Seitenleiste

Die Dateibaum-Seitenleiste zeigt jede Datei, die der Agent im Verlauf des Trace angefasst hat. Die Dateien sind nach Verzeichnis gruppiert und alphabetisch sortiert. Ein Symbol pro Datei zeigt an, welche Operationen ausgeführt wurden:

Stiftsymbol für bearbeitete Dateien
Augensymbol für nur gelesene Dateien
Plussymbol für neu angelegte Dateien
Papierkorbsymbol für gelöschte Dateien
Terminalsymbol für ausgeführte Skripte

Ein Klick auf eine Datei im Baum scrollt das Hauptfenster zur ersten Operation, an der diese Datei beteiligt ist.

Einklappbare lange Ausgaben

Jeder Ausgabeblock oberhalb von auto_collapse_threshold wird automatisch eingeklappt. Eine Zusammenfassungszeile zeigt die ersten und letzten Zeilen samt einer Schaltfläche „Show all N lines". So bleibt der Trace navigierbar, auch wenn einzelne Operationen Hunderte von Ausgabezeilen erzeugen.

Trace-Konverter

Potato bringt vier Konverter speziell für Coding-Agenten mit, die verschiedene Trace-Formate in die einheitliche Coding-Trace-Darstellung überführen.

Konverter	Quelle	Format
`claude_code`	Claude Code / Anthropic API	Messages API mit `tool_use`-Blöcken (Tools Read, Edit, Bash, Write)
`aider`	Aider	Markdown-Chatprotokolle mit SEARCH/REPLACE- und ORIGINAL/UPDATED-Blöcken
`swe_agent_trajectory`	SWE-Agent	Trajektorien-JSON mit Tripeln aus Gedanke, Aktion und Beobachtung
`auto`	automatische Erkennung	prüft den Aufbau des Trace und wählt selbstständig den passenden Konverter

Den Konverter in der Konfiguration angeben:

yaml

agentic:
  trace_converter: claude_code    # or aider, swe_agent_trajectory, auto

Claude-Code-Konverter

Der Konverter claude_code verarbeitet Traces der Anthropic Messages API, in denen Tool-Nutzung als tool_use- und tool_result-Inhaltsblöcke dargestellt ist. Er erkennt die Standard-Tools von Claude Code:

Read-Aufrufe werden zu Anzeigen von Dateilesevorgängen
Edit-Aufrufe werden zu Unified Diffs
Write-Aufrufe werden zu Anzeigen neu angelegter Dateien
Bash-Aufrufe werden zu Terminalblöcken
Glob/Grep-Aufrufe werden zu Anzeigen von Suchergebnissen

Aider-Konverter

Der Konverter aider liest Aiders markdownbasiertes Chatformat. Er entnimmt daraus SEARCH/REPLACE-Blöcke (sowie das ältere ORIGINAL/UPDATED-Format) und wandelt sie in Unified Diffs um. Shell-Kommandos und ihre Ausgabe werden aus Codeblöcken mit der Auszeichnung bash oder shell gezogen.

SWE-Agent-Trajektorien-Konverter

Der Konverter swe_agent_trajectory liest die Trajektorien-JSON-Dateien von SWE-Agent. Jeder Eintrag einer Trajektorie enthält einen Gedanken (das Reasoning des Agenten), eine Aktion (das ausgeführte Kommando) und eine Beobachtung (die Ausgabe des Kommandos). Der Konverter ordnet Aktionen in Dateibearbeitungen, Dateilesevorgänge, Shell-Kommandos und Navigationsschritte ein.

Nutzung über die Kommandozeile

Rohe Traces vor dem Start des Annotationsservers konvertieren:

bash

# Convert Claude Code traces
python -m potato.trace_converter \
  -i traces.json \
  -f claude_code \
  -o data/converted.jsonl
 
# Convert Aider chat logs
python -m potato.trace_converter \
  -i aider_chat_history/ \
  -f aider \
  -o data/aider_converted.jsonl
 
# Convert SWE-Agent trajectories
python -m potato.trace_converter \
  -i trajectories/ \
  -f swe_agent_trajectory \
  -o data/swe_converted.jsonl
 
# Auto-detect format
python -m potato.trace_converter \
  -i mixed_traces/ \
  -f auto \
  -o data/auto_converted.jsonl

Der Schalter -i nimmt eine einzelne Datei oder ein Verzeichnis entgegen. Wird ein Verzeichnis angegeben, werden alle .json- und .jsonl-Dateien verarbeitet. Der Konverter schreibt ein JSON-Objekt pro Zeile in die Ausgabedatei.

Weitere Optionen:

bash

# Filter by file extension
python -m potato.trace_converter \
  -i traces/ -f claude_code -o data/out.jsonl \
  --include "*.json"
 
# Add metadata fields from a CSV
python -m potato.trace_converter \
  -i traces/ -f claude_code -o data/out.jsonl \
  --metadata metadata.csv --join-key trace_id
 
# Validate output without writing
python -m potato.trace_converter \
  -i traces.json -f claude_code --validate

Datenformat

Nach der Konvertierung folgt jede Zeile der JSONL-Ausgabedatei diesem Aufbau:

json

{
  "id": "trace_001",
  "task_description": "Fix the failing test in test_parser.py",
  "repository": "myproject",
  "structured_turns": [
    {
      "type": "file_read",
      "tool": "Read",
      "file_path": "src/parser.py",
      "content": "def parse(input_str):\n    tokens = tokenize(input_str)\n    ...",
      "line_start": 1,
      "line_end": 45
    },
    {
      "type": "edit",
      "tool": "Edit",
      "file_path": "src/parser.py",
      "old_content": "    if len(tokens) == 0:\n        return None",
      "new_content": "    if len(tokens) == 0:\n        raise ParseError('Empty input')",
      "line_start": 12,
      "line_end": 13
    },
    {
      "type": "terminal",
      "tool": "Bash",
      "command": "python -m pytest test_parser.py -v",
      "output": "test_parser.py::test_empty_input PASSED\ntest_parser.py::test_valid_input PASSED\n\n2 passed in 0.34s",
      "exit_code": 0
    },
    {
      "type": "file_write",
      "tool": "Write",
      "file_path": "src/parser.py",
      "content": "...",
      "is_new_file": false
    }
  ],
  "metadata": {
    "agent": "claude_code",
    "model": "claude-sonnet-4-20250514",
    "total_tokens": 15234,
    "duration_seconds": 42
  }
}

Das Array structured_turns bewahrt die genaue Reihenfolge der Operationen. Jeder Turn hat ein Feld type (file_read, edit, terminal, file_write, search, thought) und dazu passende typspezifische Felder.

Konfigurationsreferenz

Eine vollständige Konfiguration, die die Coding-Trace-Anzeige mit Annotationsschemata zur Bewertung der Ausgabe von Coding-Agenten verbindet:

yaml

task_name: "Coding Agent Evaluation"
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: 3
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    terminal_max_lines: 80
    show_exit_codes: true
    file_read_max_lines: 100
    file_tree:
      enabled: true
      position: left
      show_operation_icons: true
      group_by_directory: true
      click_to_navigate: true
    auto_collapse_threshold: 500
 
annotation_schemes:
  # Did the agent complete the task?
  - annotation_type: radio
    name: task_completion
    description: "Did the agent successfully complete the task?"
    labels:
      - "Fully Complete"
      - "Partially Complete"
      - "Failed"
      - "Made Things Worse"
 
  # Per-step correctness
  - annotation_type: per_turn_rating
    name: step_quality
    description: "Rate this step"
    target: agentic_steps
    rating_type: radio
    labels:
      - "Good"
      - "Acceptable"
      - "Unnecessary"
      - "Incorrect"
 
  # Code quality rating
  - annotation_type: likert
    name: code_quality
    description: "Rate the quality of the code changes"
    min: 1
    max: 5
    labels:
      1: "Very Poor"
      2: "Poor"
      3: "Acceptable"
      4: "Good"
      5: "Excellent"
 
  # Free-text notes
  - annotation_type: text
    name: notes
    description: "Any additional observations about the coding trace"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Beispielprojekte ausführen

Potato enthält Beispielprojekte für die Annotation von Coding-Agenten:

bash

# Clone the repository
git clone https://github.com/davidjurgens/potato.git
cd potato
 
# Run the Claude Code trace evaluation example
potato start example/coding_agent_eval/config.yaml -p 8000
 
# Run the SWE-bench evaluation example
potato start example/swe_bench_eval/config.yaml -p 8000
 
# Run the multi-agent comparison example
potato start example/coding_agent_comparison/config.yaml -p 8000

Zu jedem Beispiel gehören Beispiel-Traces, eine vollständige Konfigurationsdatei und eine README mit der Beschreibung der Annotationsaufgabe.

Siehe auch

Process-Reward-Annotation -- Reward-Signale pro Schritt für das PRM-Training erheben
Code-Review-Annotation -- Inline-Review für Codeänderungen im Stil eines GitHub-PR
Live-Beobachtung von Coding-Agenten -- Coding-Agenten in Echtzeit zusehen und mit ihnen interagieren
Agentische Annotation -- allgemeine Annotation von Agent-Traces
Exportformate -- Annotationsdaten für das Modelltraining exportieren

Implementierungsdetails stehen in der Quelldokumentation.