Wie Sie Fehlfunktionen von AI-Agenten in Ihrer Codebasis zurückverfolgen und beheben
makedream٣٠ يوليو ٢٠٢٦
0
Computing/Software
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
Wenn Sie AI-Agenten wie Claude Code oder Codex in ein Backend-Repository mit mehr als 100.000 Zeilen Code einbinden, sind Sie zunächst von der Geschwindigkeit begeistert. Doch sobald sich ein paar falsche Zeilen in den Prompt einschleichen, durchbricht die KI die Absicherungen und vergreift sich selbst an gemeinsamen Utilities oder Konfigurationsdateien. Die Session-Logs schwellen auf mehrere Megabyte an, der Build schlägt fehl, und nach einer Stunde Durchsuchen von Git Diffs auf der Suche nach der Ursache denkt man sich: Ich hätte es lieber gleich selbst geschrieben.
Um Agenten Autonomie zu gewähren und gleichzeitig unnötige Dateibeschädigungen zu verhindern, sind eine klare harte Isolierung und ein visualisiertes Trace-Tracking-System erforderlich.
Dateien mit Anweisungen in natürlicher Sprache wie CLAUDE.md oder .aiignore werden vom Agenten gerne umgangen, sobald das Kontextfenster zu lang wird. Aufforderungen auf Prompt-Ebene sind lediglich Empfehlungen – sobald der Kontext verloren geht, überschreitet die Werkzeugausführung des Agenten hemmungslos die Grenzen.
Um den Zugriff des Agenten physisch zu blockieren, sollten Sie eine deterministische Rechtesteuerungs-Engine namens .claude/settings.json direkt im Projekt-Stammverzeichnis platzieren.
json { "permissions": { "deny": [ "Edit(src/core/config/**)", "Edit(src/shared/utils/**)", "Read(./.env*)", "Bash(rm -rf *)" ], "ask": [ "Edit(src/api/v1/legacy/**)" ] } }
Nach dem Einrichten expliziter Blockierungsregeln ist es sicherer, das Dateisystem auf Betriebssystemebene noch einmal zusätzlich zu sperren. Bei Produktions-Build-Skripten oder Sicherheitsschlüssel-Dateien ist es am saubersten, die Schreibrechte auf OS-Ebene zu entziehen.
.claude/settings.json im Projekt-Stammverzeichnis.permissions.deny ein.chmod 444 .env*.Durch diese Zugriffssteuerung lassen sich Build-Fehler, die entstehen, weil die KI unerwartet gemeinsame Module verändert, zu einem großen Teil vermeiden.
Wenn Session-Logs (.jsonl) nur in der lokalen Umgebung des einzelnen Entwicklers verbleiben, ist die Ursachenforschung bei später auftretenden Seiteneffekten schwierig. Richten Sie einen GitHub Actions Workflow ein, der Session-Traces zum Zeitpunkt des PR-Erstellens komprimiert und überprüft.
`yaml
name: AI Agent Session Audit & Risk Analysis
on:
pull_request:
types: [opened, synchronize]
jobs:
audit-session:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Mindwalk Telemetry Extractor
run: |
docker run --rm -v ${{ github.workspace }}:/workspace \
cosmtrek/mindwalk:v0.1.0 parse --log-dir=./.claude/sessions --out=telemetry.json
- name: Run Deterministic Repo Audit
id: repo_audit
run: |
curl -sSL https://github.com/aletheore/releases/download/v1.0/aletheore -o aletheore
chmod +x aletheore
./aletheore audit --telemetry=telemetry.json --max-allowed-depth=3
- name: Upload Mindwalk 3D Visual Artifact
uses: actions/upload-artifact@v4
with:
name: mindwalk-3d-trace-${{ github.event.pull_request.number }}
path: telemetry.json
`
Durch die Einbindung einer Rust-basierten Analyse-Engine oder von Tree-sitter zur Überprüfung, ob der Agent seinen Scope verlassen hat, kann der CI-Build sofort als fehlgeschlagen markiert werden, wenn übergeordnete Module außerhalb des zulässigen Bereichs geändert wurden.
Es ist nützlich, das Änderungsrisiko basierend auf der Knotenkonnektivität anstelle der bloßen Anzahl von Codezeilen zu berechnen.
Hierbei ist die Anzahl der geänderten Dateien und die durchschnittliche 3D-Konnektivität der geänderten Knoten. Wenn der Schwellenwert überschritten wird, kann eine Slack-Benachrichtigung mit einem Link zur visuellen 3D-Karte gesendet werden, sodass der Reviewer das Risiko sofort einschätzen kann.
Wenn der Agent Chaos angerichtet hat, sollten Sie, anstatt den gesamten Commit zu verwerfen, die Zeitachse nachverfolgen und nur die beschädigten Dateien selektiv wiederherstellen. Sobald Sie den genauen Zeitraum ermittelt haben, in dem die Fehlfunktion begann, extrahieren Sie mit jq den Prompt und den Reasoning-Pfad aus dem JSONL-Log.
bash jq -c 'select(.timestamp >= "2026-07-11T14:20:00Z" and .timestamp <= "2026-07-11T14:25:00Z") | {timestamp: .timestamp, prompt: .payload.prompt, tool_use: .payload.tool_use, thinking: .payload.thinking}' \ ./.claude/sessions/session_abc123.jsonl
Sobald die Ursache bestätigt ist, wird die Wiederherstellung in folgenden drei Schritten durchgeführt:
git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)git clean -fd -- src/unwanted_generated_dir/)Mit dieser Methode können Sie nur die beschädigten Dateien sauber korrigieren, ohne versehentlich ordnungsgemäß funktionierenden Code zu löschen.
In einer Monorepo-Umgebung mit tensenden von Knoten kann das Visualisierungstool selbst abstürzen. Wenn der Browser langsam wird, vergeht auch die Lust am Debuggen. Um unnötige Verzeichnisse vom Rendering auszuschließen, müssen Sie Ausschlussfilter in mindwalk.config.json präzise definieren.
json { "visualization": { "excludePatterns": [ "**/node_modules/<strong>", "</strong>/vendor/<strong>", "</strong>/.git/<strong>", "</strong>/dist/<strong>", "</strong>/coverage/<strong>", "</strong>/*.log", "**/*.pb.go" ], "maxDepth": 5, "groupingStrategy": "directory-segmented" } }
Schließlich sollten Sie beim Ausführen von Visualisierungspipelines oder Analysetools als Docker-Container im Hintergrund die Ressourcenzuweisung begrenzen, damit die lokale IDE nicht einfriert.
mindwalk.config.json, um Knoten von Abhängigkeitsverzeichnissen aus der Visualisierung auszuschließen.--cpus="1.5" und --memory="2g" an.--nice=19 an das Ende des Hintergrundprozess-Befehls an, um die CPU-Priorität auf die niedrigste Stufe zu senken.