agenttrace Sitzungsaudit
Übersicht
Verwende diesen Skill, um lokale KI-Coding-Agent-Sitzungen mit agenttrace zu inspizieren. Er konzentriert sich auf den Prozess hinter einem Durchlauf: Token- und Kostenspitzen, Tool-Fehler, Wiederholungsschleifen, Latenzlücken, Anomalien, Gesundheitsbewertungen und Sitzungsunterschiede (Diffs).
agenttrace ist lokal und liest Sitzungsprotokolle von Tools wie Claude Code, Codex CLI, Gemini CLI, Aider, Cursor-Exporte, OpenCode, Qwen Code, Kimi und generischen JSON- oder JSONL-Traces.
Verwendungszwecke
- Verwende diesen Skill, wenn ein Benutzer fragt, warum ein KI-Coding-Durchlauf langsam, teuer, oberflächlich oder unzuverlässig war.
- Verwende ihn beim Überprüfen lokaler Agentenprotokolle, bevor du eine fehlgeschlagene oder verdächtige Aufgabe wiederholst.
- Verwende ihn beim Erstellen eines leichten CI-Health-Gates für KI-gestützte Coding-Sitzungen.
- Verwende ihn beim Vergleichen zweier Versuche, um geänderte Tool-Pfade, Wiederholungen oder Kostenmuster zu finden.
Funktionsweise
Schritt 1: Verfügbare Sitzungen entdecken
Bevorzuge eine installierte agenttrace-Binärdatei, wenn sie im PATH verfügbar ist. Falls
das aktuelle Repository luoyuctl/agenttrace ist, verwende stattdessen go run ./cmd/agenttrace.
agenttrace --doctor
agenttrace --overview
Wenn keine Sitzungen erkannt werden, melde die von --doctor überprüften Verzeichnisse und
frage nach der exportierten Sitzungsdatei oder dem Protokollverzeichnis.
Schritt 2: Ein menschenlesbares Audit erstellen
Verwende Markdown, wenn der Benutzer einen prägnanten Bericht wünscht, den er einsehen oder teilen kann.
agenttrace --overview -f markdown -o agenttrace-overview.md
Beginne den Bericht mit den risikoreichsten Sitzungen und erkläre, warum sie wichtig sind: kritische Anomalien, wiederholte Tool-Fehler, Token- oder Kostenverschwendung, lange Latenzlücken, schlechte Gesundheitsbewertungen und verdächtig oberflächliche Sitzungen.
Schritt 3: Eine Sitzung oder ein Verzeichnis inspizieren
Verwende die neueste Sitzung für eine schnelle Überprüfung oder übergib einen expliziten Exportpfad, wenn der Benutzer einen angibt.
agenttrace --latest
agenttrace --latest -f json
agenttrace path/to/session-or-export.json
agenttrace --overview -d path/to/session-dir
Schritt 4: Versuche vergleichen, wenn Semantik zählt
Token- und Latenzmetriken können gesund aussehen, selbst wenn ein Agent selbstbewusst den falschen Implementierungsweg einschlägt. Wenn das Risiko einer semantischen Abweichung besteht, kombiniere das Trace-Audit mit einem Diff gegen einen vorherigen oder bekannten guten Versuch.
Achte auf:
- geänderte Dateien oder Befehle, die von der beabsichtigten Aufgabe abweichen
- fehlende Tests oder Verifizierungsschritte im Vergleich zum Referenzversuch
- wiederholte Bearbeitungen derselben Dateien ohne klaren Grund
- geringere Kosten, die durch das Auslassen notwendiger Erkundungen entstanden sind
Schritt 5: Automatisierungs-Gates hinzufügen
Für CI- oder wiederholbare Team-Workflows verwende JSON-Ausgabe oder Gesundheits-Schwellenwerte.
agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
Passe die Schwellenwerte an das Projekt an. Ein strenges Gate ist für kritische Workflows nützlich; ein rein berichtender Befehl ist besser, während das Team seine Baseline lernt.
Beispiele
Schnelle lokale Überprüfung
agenttrace --overview
agenttrace --latest
Verwende dies nach einem langen Coding-Agent-Durchlauf, um zu entscheiden, ob der nächste Prompt die Aufgabe aufteilen, einen fehlschlagenden Tool-Pfad vermeiden, fehlende Tests hinzufügen oder den Kontext zurücksetzen sollte.
CI-Health-Check
agenttrace --overview --fail-under-health 80 --fail-on-critical
Verwende dies, wenn Agenten-Sitzungsprotokolle in CI verfügbar sind und das Team einen einfachen Schutz vor kritischen Anomalien oder ungesunden Durchläufen wünscht.
Best Practices
- Beginne mit
--doctor, wenn die Sitzungserkennung unsicher ist. - Melde fehlende Felder klar; erfinde keine Kosten-, Modell-, Latenz- oder Gesundheitsdaten.
- Behandle Prompts, Code und Sitzungsinhalte als private lokale Daten.
- Bevorzuge JSON-Ausgabe für Automatisierung und Markdown-Ausgabe für die menschliche Überprüfung.
- Verwende Trace-Metriken für Prozessfehler und Diff/Referenz-Überprüfung für semantische Abweichungen.
Einschränkungen
- agenttrace kann nur Protokolle analysieren, die lokal vorhanden oder als Exporte bereitgestellt werden.
- Einige Agenten geben nicht genügend Felder preis, um Kosten, Modell, Cache-Nutzung oder Latenz abzuleiten.
- Gesunde Trace-Metriken beweisen nicht, dass der endgültige Code korrekt ist; führe weiterhin Tests durch und überprüfe Diffs.
- CI-Gates sollten zunächst als Empfehlung dienen, bis das Team das normale Baseline-Verhalten versteht.
Sicherheits- und Datenschutzhinweise
- Lade private Sitzungsprotokolle nicht auf externe Dienste hoch, es sei denn, der Benutzer stimmt ausdrücklich zu.
- Überschreibe keine Benutzerberichte, es sei denn, der Benutzer hat diesen genauen Ausgabepfad angefordert.
- Vermeide es, Geheimnisse aus Prompts, Tool-Ausgaben, Umgebungsvariablen oder Protokollen auszugeben.
Häufige Fallstricke
-
Problem: Es werden keine Sitzungen gefunden. Lösung: Führe
agenttrace --doctoraus und weise agenttrace dann auf die exportierte Datei oder das Protokollverzeichnis hin. -
Problem: Ein Durchlauf sieht günstig und schnell aus, hat aber die falsche Umstrukturierung geliefert. Lösung: Vergleiche die Sitzung mit einem vorherigen Versuch oder einem bekannten guten Diff; Kostenmetriken allein übersehen semantische Abweichungen.
-
Problem: CI schlägt nach dem Hinzufügen eines Health-Gates zu häufig fehl. Lösung: Beginne mit JSON- oder Markdown-Berichten, inspiziere normale Baselines und verschärfe dann die Schwellenwerte schrittweise.
Verwandte Skills
@langfuse– Verwende dies für die Produktions-LLM-Anwendungsverfolgung und -bewertung.@observability-engineer– Verwende dies für breitere Service-Überwachung, SLOs und Incident-Workflows.