Prozesse & Workflows¶

Diese Seite dokumentiert die empfohlenen Arbeitsschritte und Best Practices für die Arbeit mit CC-Sprint.

1. Item-Lifecycle¶

Status-Übergänge¶

Von	Nach	Trigger	Aktion
Offen	In Arbeit	User beginnt Arbeit	Phase → Umsetzung
In Arbeit	Blockiert	Dependency fehlt	Notiz hinzufügen
Blockiert	In Arbeit	Blocker behoben	Notiz aktualisieren
In Arbeit	Erledigt	Arbeit fertig	Phase → Done

Best Practice: Immer Status UND Phase synchron halten.

2. Backlog.md Bearbeitungs-Prozess¶

Manuelles Editieren (direkt in Backlog.md)¶

Mit Claude Code (empfohlener Workflow)¶

WICHTIG: Verwende NIEMALS Edit tool direkt auf Backlog.md!

Schritt-für-Schritt:

Suche das Item mit grep:
```
grep -n "### \[F-0032\]" docs/Backlog.md
```
Output: 245:### [F-0032] Auto-Save System

Lese das Item mit Script:

python scripts/backlog_item.py get F-0032

Arbeite am Code (z.B. implementiere Feature)

Update Status mit Script:

python scripts/backlog_item.py update F-0032 --status "Erledigt" --phase "Done"

Verifiziere in App (öffne Item F-0032, prüfe Status)

Commit Code + Backlog-Änderung zusammen:

git add .
git commit -m "Implement Auto-Save System (F-0032)"

3. Konflikt-Auflösung¶

Szenario A: Externe Änderungen nur (kein Konflikt)¶

1. Claude Code schreibt neue Version von Backlog.md
2. FileWatcher erkennt Änderung nach 500ms
3. Hash-Vergleich: Unterschiedlich
4. Check: Keine ungespeicherten App-Änderungen
5. → Auto-Reload
6. Notification: "Backlog.md neu geladen (3 Items geändert)"

Szenario B: Konkurrente Änderungen (Konflikt)¶

1. User ändert F-0018 Status in App (noch nicht gespeichert)
2. Claude Code ändert F-0032 Beschreibung
3. FileWatcher erkennt Änderung
4. Check: F-0018 hat modified_in_app=true
5. → Konflikt-Banner anzeigen

Banner:
┌─────────────────────────────────────────────┐
│ ⚠️ Backlog.md wurde extern geändert         │
│                                             │
│ Externe Änderungen: F-0032                  │
│ Ihre Änderungen: F-0018 (Status)            │
│                                             │
│ [ Neu laden ] [ Behalten ] [ Merge ]        │
└─────────────────────────────────────────────┘

Optionen:

Option 1: Neu laden¶

Verwirft App-Änderungen (F-0018)
Lädt externe Version (F-0032 geändert)
Schnell, aber Datenverlust

Option 2: Behalten¶

Erstellt Backup von externer Version
Schreibt App-Version nach Backlog.md
Externe Änderungen (F-0032) gehen verloren (aber im Backup)

Option 3: Merge (Manuell)¶

Öffnet DiffView
Zeigt beide Versionen side-by-side
User wählt per Item oder per Feld
Keine Datenverluste, aber manuell

4. Backup & Recovery¶

Automatische Backups¶

Trigger: 1. Vor jeder "Behalten"-Aktion (Overwrite) 2. Vor rebuild_database (wenn konfiguriert) 3. Vor manuellen Lösch-Operationen (wenn konfiguriert)

Speicherort: .backlog-admin/backups/backlog-YYYY-MM-DD_HH-MM-SS.md

Retention: Standard 10 Backups, konfigurierbar

Backup wiederherstellen¶

Via App: 1. Menü → "Backup-Verwaltung" 2. Liste aller Backups mit Timestamp 3. Backup wählen → "Wiederherstellen" 4. Confirmation: "Aktuelle Version wird überschrieben" 5. Restore → Reload

Manuell:

# Backup anzeigen
ls -la .backlog-admin/backups/

# Wiederherstellen
cp .backlog-admin/backups/backlog-2026-02-02_10-30-00.md docs/Backlog.md

# App erkennt Änderung automatisch

5. Context-Management (Claude Code)¶

Problem: Context-Overflow¶

Claude Code hat ein begrenztes Context-Fenster. Bei großen Backlog.md Dateien (85+ Items, 3900+ Zeilen) wird der Context schnell voll.

Symptome: - "String to replace not found" (Edit tool) - Langsame Responses - Wiederholungen in Antworten

Lösung: Context-Sparsamkeit¶

DO: - ✅ Nur relevante Items lesen (via Script) - ✅ grep für Suche verwenden (nicht full file read) - ✅ Context clearen nach großen Tasks (/clear command) - ✅ Neue Session für neue große Tasks

DON'T: - ❌ Komplettes Backlog.md in Context laden - ❌ Edit tool auf Backlog.md verwenden - ❌ Mehrfach gleiche Files lesen

Context-Clearen-Trigger¶

Clearne Context wenn: 1. Session >30 Minuten läuft 2. Mehrere Files (>10) gelesen wurden 3. Context-voll Warnung erscheint 4. Wechsel zu komplett neuer Task

Wie:

User: /clear
Claude: Context cleared. Wie kann ich helfen?
User: [Neue Task beschreiben]

6. Entwicklungs-Workflow (Claude Code Session)¶

Empfohlener Ablauf¶

flowchart TD
    A[Session starten] --> B[Context prüfen]
    B --> C{Context zu voll?}
    C -->|Ja| D[/clear command]
    C -->|Nein| E[Task identifizieren]
    D --> E
    E --> F[Item-ID finden grep]
    F --> G[Item lesen Script]
    G --> H[Relevante Code-Files lesen]
    H --> I[Änderungen machen]
    I --> J[Testen]
    J --> K{Tests OK?}
    K -->|Nein| I
    K -->|Ja| L[Status in Backlog updaten Script]
    L --> M[Commit & Push]
    M --> N{Weitere Tasks?}
    N -->|Ja| O{Context noch OK?}
    N -->|Nein| Z[Session beenden]
    O -->|Ja| E
    O -->|Nein| D

Best Practices¶

Start: Status → "In Arbeit", Phase → "Umsetzung"
Während: Nur relevante Files lesen (max 5-10)
Ende: Status → "Erledigt", Phase → "Done"
Commit: Descriptive Message mit Item-ID
Review: Prüfe in App ob Status korrekt

7. Testing-Prozess¶

Unit Tests¶

Trigger: Nach Code-Änderungen an Parser/Renderer/Validator

cd src-tauri
cargo test

Wichtig: Snapshot-Tests mit insta:

cargo test
# Bei Änderungen:
cargo insta review

Integration Tests¶

Trigger: Nach DB-Schema-Änderungen, Migrations

cargo test --test integration

E2E Tests (Future)¶

Trigger: Vor Release

cd app
npm run test:e2e

8. Release-Prozess¶

Vorbereitung¶

Alle Items in "Done" → Status überprüfen
Backlog.md committen
Tests laufen (Unit + Integration)
Version-Bump in Cargo.toml und package.json

Build¶

npm run tauri build

Output: src-tauri/target/release/bundle/ - Windows: .msi - macOS: .dmg - Linux: .deb, .AppImage

Deployment¶

# Kopiere Builds nach deploy/
mkdir -p deploy/v0.X.0
cp src-tauri/target/release/bundle/msi/*.msi deploy/v0.X.0/
# ... etc

# Commit
git add deploy/v0.X.0/
git commit -m "Release v0.X.0"
git tag v0.X.0
git push origin v0.X.0

9. Troubleshooting¶

Problem: App lädt Backlog.md nicht¶

Diagnose: 1. Check: Existiert docs/Backlog.md? 2. Check: Ist Format valide? (Parser-Errors in Console) 3. Check: Sind Permissions OK? (File readable)

Lösung:

# Format prüfen
python scripts/backlog_validator.py docs/Backlog.md

# Permissions prüfen (Linux/Mac)
ls -la docs/Backlog.md

Problem: FileWatcher erkennt Änderungen nicht¶

Diagnose: 1. Check: Läuft App im Dev-Mode? (FileWatcher nur in Tauri-App aktiv) 2. Check: Logs in DevTools Console (File change events)

Lösung: - Restart App - Check Tauri Permissions (capabilities/default.json)

Ursache: Hash stimmt nicht mit File-Inhalt überein