Zum Inhalt

Edit-Tool Fehler (P-001)

Problem

Claude Code's Edit tool scheitert systematisch beim Versuch, docs/Backlog.md zu bearbeiten.

Symptom: Error editing file: String to replace not found

Ursachen-Analyse

Ursache 1: Timestamp-Änderung

Szenario: 

1. Claude: Read docs/Backlog.md
   → Sieht Header mit "**Letzte Aktualisierung**: 2026-02-01 18:44"

2. External Script: Aktualisiert Timestamp
   → Neuer Header: "**Letzte Aktualisierung**: 2026-02-01 18:50"

3. Claude: Edit tool mit altem String
   → FEHLER: String "2026-02-01 18:44" not found

Warum problematisch: Header ändert sich häufig (jede Backlog-Änderung)

Ursache 2: Unicode-Encoding

Problem: Deutsche Umlaute (ä, ö, ü, ß) können unterschiedlich encodiert sein.

Beispiel: 

File auf Disk:  "Abhängigkeiten" (UTF-8)
Claude liest:   "Abhängigkeiten" (möglicherweise anders normalisiert)
Edit sucht:     "Abhängigkeiten" → NICHT GEFUNDEN

NFD vs NFC: Unicode Normalization Forms können differieren.

Ursache 3: Line-Endings

Windows vs Git: - Windows Editor speichert: CRLF (\r\n) - Git konvertiert zu: LF (\n) - Claude liest File mit: LF - Edit sucht String mit: CRLF → NICHT GEFUNDEN

Ursache 4: File-Größe

Problem: Backlog.md mit 85+ Items = 3900+ Zeilen

Impact: - Füllt Context-Fenster komplett - Edit-Tool hat wenig "Arbeits-Context" - String-Matching wird unzuverlässiger - Performance-Degradation

Reproduktion

Setup: 1. Backlog.md mit 50+ Items 2. Header mit Timestamp 3. Deutsche Umlaute in Beschreibungen

Schritte: 

Claude> Read docs/Backlog.md
Claude> Edit docs/Backlog.md:
  old_string: "### [F-0032] Feature Name"
  new_string: "### [F-0032] Neuer Feature Name"

Ergebnis: ❌ "String to replace not found"

Warum: Zwischen Read und Edit kann sich File geändert haben (FileWatcher, AutoSave, User-Edit).

Impact

Entwicklung blockiert

  • Claude Code kann Backlog.md nicht direkt bearbeiten
  • Jede Backlog-Änderung erfordert Workaround
  • Workflow unterbrochen

Ineffiziente Workarounds

  • safe_backlog_edit.py --write (Full-File-Rewrite)
  • Manuelles Editieren + Reload
  • Beide ineffizient bei großen Files

Merge-Konflikte

  • Full-File-Rewrite → Git-Diff zeigt alles als geändert
  • Merge-Konflikte bei parallelen Branches wahrscheinlicher

Aktuelle Workarounds

1. safe_backlog_edit.py (Full-File-Rewrite)

python scripts/safe_backlog_edit.py --write "$(cat <<'EOF'
# Kompletter neuer Inhalt von Backlog.md
...
EOF
)"

Vorteile: - ✅ Funktioniert immer - ✅ Automatisches Backup - ✅ Triggert FileWatcher

Nachteile: - ❌ Ineffizient (komplettes File) - ❌ Git-Diff unübersichtlich - ❌ Erfordert Context für komplettes File

2. Manuelle Bearbeitung

# User öffnet Backlog.md in Editor
# User macht Änderung
# User speichert
# App erkennt Änderung via FileWatcher

Vorteile: - ✅ Kein Scripting nötig - ✅ Editor-Features (Syntax-Highlighting, etc.)

Nachteile: - ❌ Nicht automatisierbar durch Claude Code - ❌ Manuelle Fehleranfälligkeit - ❌ Kein Backup automatisch

3. Strikte Regeln für Claude Code

CLAUDE.md Regeln: 

## NEVER
- Edit tool auf docs/Backlog.md verwenden

## ALWAYS
- grep für Suche verwenden
- Scripts für Änderungen verwenden

Problem: Verlässt sich auf AI-Compliance, nicht auf System-Design.

Langfristige Lösung

Siehe Solutions: Scripts Concept für:

  • backlog_item.py mit granularen Operationen:
  • get <ID> - Einzelnes Item lesen
  • update <ID> - Einzelnes Item ändern
  • add --type F - Neues Item erstellen
  • delete <ID> - Item entfernen

Vorteile: - ✅ Keine Full-File-Reads - ✅ Surgical Editing (nur betroffene Zeilen) - ✅ Automatische Backups - ✅ Validierung vor Write - ✅ Saubere Git-Diffs

Metriken

Aktueller Zustand

Metrik Wert
Edit-Tool Erfolgsrate ~20% (scheitert meist)
Context-Usage pro Edit 3900+ Zeilen (85 Items)
Time pro Edit 5-10 Sekunden (inkl. Retry)
Git-Diff-Größe Komplettes File

Mit backlog_item.py (Ziel)

Metrik Wert
Edit-Tool Erfolgsrate N/A (nicht verwendet)
Context-Usage pro Edit ~20 Zeilen (einzelnes Item)
Time pro Edit <1 Sekunde
Git-Diff-Größe Nur geänderte Item-Section

Nächste Schritte

  1. Implementiere backlog_item.py (siehe Scripts Concept)
  2. Update CLAUDE.md mit neuen Workflow-Regeln
  3. Teste mit verschiedenen Item-Typen
  4. Dokumentiere in Developer Guide

Siehe auch