Scripts Design: Granulare Item-Operationen

Status: Implementiert

Dieses Design wurde als Rust CLI (ccs) umgesetzt. Die ursprünglich geplanten Python-Skripte sind deprecated.

Problem

Das Edit-Tool von Claude Code scheitert bei docs/Backlog.md:

• Timestamps ändern sich zwischen Read und Edit
• Unicode-Issues (ä, ö, ü, ß)
• Line-Ending-Konflikte (CRLF vs LF)
• Kein Backup, keine Validierung

Siehe: Edit-Tool Failure

Lösung: Rust CLI (ccs)

Die Lösung ist eine Rust-basierte CLI, die dieselben Funktionen wie die Desktop-App nutzt.

Vorteile

Aspekt	Python (deprecated)	Rust CLI (ccs)
Code-Sharing	Duplicate	Same codebase as App
Maintenance	2 Stellen	1 Stelle
Type Safety	Runtime errors	Compile-time checks
Performance	~200ms	~50ms
Dependencies	Python Runtime	Single Binary

Architektur

┌─────────────────────────────────────────────────────┐
│                    Rust Codebase                     │
│  src-tauri/src/                                     │
│  ├── domain/      (Parser, Renderer, Validator)     │
│  ├── services/    (Backup, FileWatcher, Git)        │
│  └── repository/  (SQLite, Settings)                │
└───────────────────┬─────────────────┬───────────────┘
                    │                 │
         ┌──────────▼──────┐  ┌──────▼──────┐
         │   Tauri App     │  │   CLI Binary │
         │   (Desktop)     │  │   (ccs)      │
         └─────────────────┘  └─────────────┘

Single Point of Implementation: App und CLI nutzen identischen Rust-Code.

CLI Befehle

Timestamp

ccs timestamp --format backlog   # 2026-02-04 19:08
ccs timestamp --format iso       # 2026-02-04T19:08:20+01:00
ccs timestamp --format unix      # 1770228500

Backlog-Operationen

# Validieren
ccs backlog validate --project .
# → { "valid": true, "item_count": 100, "errors": [] }

# Neues Item einfügen
ccs backlog edit --project . --file new_item.md --insert-before "## Technical Tasks"
# → { "success": true, "hash": "...", "itemCount": 101 }

# Pfad anzeigen
ccs backlog path --project .
# → ./docs/Backlog.md

Git-Operationen

# Status
ccs git status --project .
# → { "is_repo": true, "branch": "dev", "has_uncommitted_changes": true }

# Commit & Push
ccs git commit --project . --files docs/Backlog.md --message "Update" --push
# → { "committed": true, "pushed": true, "commit_hash": "abc123" }

Backup-Operationen

ccs backup list --project .
ccs backup create --project .
ccs backup restore --project . backlog-2026-02-04_19-08-00.md
ccs backup validate --project . backlog-2026-02-04_19-08-00.md

Workflow-Vergleich

Vorher (Edit-Tool - KAPUTT)

1. Read docs/Backlog.md        → 3900 Zeilen in Context
2. Edit tool                   → FEHLER: "String not found"
3. Retry, retry...             → Frustration

Nachher (Rust CLI)

# 1. Item finden (grep ist read-only, erlaubt)
grep -n "### \[F-0032\]" docs/Backlog.md

# 2. Code implementieren
# ... Edit .rs/.tsx files ...

# 3. Status aktualisieren (via App oder CLI)
# In App: Item öffnen → Status ändern → Speichern

# 4. Neues Item hinzufügen (falls nötig)
cat > /tmp/new_item.md << 'EOF'
### [F-0051] Neues Feature
- **Status**: Offen
- **Priorität**: Mittel
- **Phase**: Idee
- **Bereich**: funktional
EOF

ccs backlog edit --project . --file /tmp/new_item.md --insert-before "## Technical Tasks"

# 5. Commit
ccs git commit --project . --files docs/Backlog.md --message "Add F-0051" --push

Features der Rust-Lösung

Automatisches Backup

ccs backlog edit ...
# → Erstellt automatisch Backup in .backlog-admin/backups/

Auto-Cleanup

Bei jedem Edit werden automatisch bereinigt:

• Duplicate Section Headers
• Excessive Blank Lines (>2 → 2)
• Leading Spaces in Headers

Validierung

ccs backlog validate --project .
# Prüft:
# - Format (Header, Sections, Items)
# - Pflichtfelder (Status, Priorität)
# - Gültige Werte (Offen, In Arbeit, etc.)
# - Unique IDs

JSON Output

Alle Befehle geben JSON zurück – einfach zu parsen:

result=$(ccs backlog validate --project .)
if [ "$(echo $result | jq '.valid')" = "false" ]; then
  echo "Errors: $(echo $result | jq '.errors')"
fi

Performance

Operation	Python (alt)	Rust CLI
Validate	~500ms	~50ms
Edit	~800ms	~100ms
Backup	~200ms	~30ms

Deprecated: Python Scripts

Deprecated

Die folgenden Python-Skripte sind deprecated und werden nicht mehr gepflegt:

• scripts/get_time.py → ccs timestamp
• scripts/safe_backlog_edit.py → ccs backlog edit
• scripts/backlog_item.py → Nie implementiert, ersetzt durch App + CLI

Verwende stattdessen die ccs CLI!

Siehe auch

• CLI Referenz – Alle ccs Befehle
• Claude Code Regeln – Workflow-Regeln
• Edit-Tool Failure – Problem-Beschreibung

---

Letzte Aktualisierung: 2026-02-04