Zum Inhalt

Workflow Design: Claude Code Integration

Optimierter Workflow für Claude Code bei der Arbeit mit CC-Sprint.

Ziel-Workflow

Effizienter, sicherer Workflow OHNE Edit-Tool auf Backlog.md.

Aktueller Workflow (Kaputt)

Diagramm

Probleme: - Context-Overflow - Edit-Tool scheitert meist - Ineffiziente Workarounds - Git-Diffs unübersichtlich

Neuer Workflow (Effizient)

Diagramm

Vorteile: - ✅ Kein Context-Overflow - ✅ Kein Edit-Tool nötig - ✅ Schnell (<1s pro Operation) - ✅ Saubere Git-Diffs - ✅ Automatische Backups

Detaillierte Schritte

1. Item finden

# Schnelle Suche (kein Full-File-Read)
grep -n "### \[F-0032\]" docs/Backlog.md
# Output: 245:### [F-0032] Auto-Save System

Claude's Gedanken: "Item F-0032 ist in Zeile 245"

2. Item-Details laden

python scripts/backlog_item.py get F-0032

Output (JSON): 

{
  "id": "F-0032",
  "title": "Auto-Save System",
  "type": "F",
  "status": "Offen",
  "priority": "Hoch",
  "phase": "Analyse",
  "area": "funktional",
  "description": "Implementiere Auto-Save mit 2s debounce...",
  "acceptance_criteria": [
    {"text": "Auto-Save nach 2s Idle", "done": false},
    {"text": "Debounce funktioniert korrekt", "done": false}
  ],
  "dependencies": ["T-0015"],
  "technical_notes": "Verwende useAutoSave Hook in app/src/hooks/"
}

Claude's Context: Nur 20 Zeilen statt 3900!

3. Relevante Code-Files lesen

# Nur Files die für Feature relevant sind
Read app/src/hooks/useAutoSave.ts
Read app/src/components/ItemDetailView.tsx

Context: ~300 Zeilen (statt 3900 für Backlog.md)

4. Implementieren

// Normaler Code-Edit Workflow
Edit app/src/hooks/useAutoSave.ts
Edit app/src/components/ItemDetailView.tsx

Edit-Tool funktioniert hier: ✅ Normale .ts Dateien, keine Probleme!

5. Testen

# Manual oder automated
npm run dev
# Test in Browser

6. Status aktualisieren

# Wenn Feature fertig:
python scripts/backlog_item.py update F-0032 \
  --status "Erledigt" \
  --phase "Done"

Backlog.md wird aktualisiert (nur Item-Section): 

 ### [F-0032] Auto-Save System
-- **Status**: Offen
-- **Phase**: Analyse
+- **Status**: Erledigt
+- **Phase**: Done

7. Commit

git add .
git commit -m "$(cat <<'EOF'
Implement Auto-Save System (F-0032)

- Add useAutoSave hook with 2s debounce
- Integrate into ItemDetailView
- Tests passing

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
EOF
)"

Git-Diff: Nur geänderte Dateien + Item-Section in Backlog.md (3-5 Zeilen)

Use Cases

Use Case 1: Neues Feature implementieren

# 1. Check welche Features offen sind
python scripts/backlog_item.py list --type F --status "Offen" --priority "Hoch"

# Output:
# F-0032: Auto-Save System (Hoch, Offen, Analyse)
# F-0045: Dependency Graph (Hoch, Offen, Idee)

# 2. Wähle Feature
python scripts/backlog_item.py get F-0032

# 3. Starte Arbeit (Status → In Arbeit)
python scripts/backlog_item.py update F-0032 --status "In Arbeit" --phase "Umsetzung"

# 4. Implementiere...

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

Use Case 2: Bug fixen

# 1. Finde Bug
python scripts/backlog_item.py list --type B --status "Offen"

# Output:
# B-0007: Auto-Save Reload Problem (Hoch, Offen)

# 2. Details
python scripts/backlog_item.py get B-0007

# 3. Fix implementieren...

# 4. Bug als erledigt markieren
python scripts/backlog_item.py update B-0007 --status "Erledigt" --phase "Done"

Use Case 3: Neues Item erstellen

# Claude erkennt: "Neue Anforderung, nicht im Backlog"

python scripts/backlog_item.py add \
  --type F \
  --title "Dark Mode Support" \
  --status "Offen" \
  --priority "Mittel" \
  --phase "Idee" \
  --area "design" \
  --description "Implementiere Dark Mode Toggle..."

# Output:
# ✓ Created item F-0086
# ✓ Backup created: .backlog-admin/backups/backlog-2026-02-03_10-30-00.md
# ✓ File updated: docs/Backlog.md

Claude Code Regeln (MANDATORY)

NEVER

  • ❌ Edit tool auf docs/Backlog.md verwenden
  • ❌ Komplettes Backlog.md in Context laden
  • ❌ safe_backlog_edit.py verwenden (außer Notfall)

ALWAYS

  • ✅ grep für Suche verwenden
  • ✅ backlog_item.py get für Details
  • ✅ backlog_item.py update für Änderungen
  • ✅ Status aktualisieren wenn Work starts/ends
  • ✅ Phase synchron mit Status halten

Status-Management

Event Aktion
Beginne Arbeit an Item --status "In Arbeit" --phase "Umsetzung"
Feature fertig implementiert --status "Erledigt" --phase "Done"
Item blockiert --status "Blockiert" + Notiz in Beschreibung
Bug gefixed --status "Erledigt" --phase "Done"

Context-Management

Optimierte Context-Usage

Vor (schlecht): 

Read docs/Backlog.md           # 3900 Zeilen
Read app/src/hooks/useAutoSave.ts  # 150 Zeilen
Read app/src/components/ItemDetailView.tsx  # 200 Zeilen
---
Total: ~4250 Zeilen in Context

Nach (gut): 

grep "### \[F-0032\]" docs/Backlog.md  # 1 Zeile Output
python scripts/backlog_item.py get F-0032  # 20 Zeilen JSON
Read app/src/hooks/useAutoSave.ts  # 150 Zeilen
Read app/src/components/ItemDetailView.tsx  # 200 Zeilen
---
Total: ~371 Zeilen in Context (11x weniger!)

Context-Clearen Trigger

Clearne Context wenn: 1. Session >30 Minuten 2. Wechsel zu neuem großem Feature 3. Context-voll Warnung 4. Nach mehreren großen File-Reads

User: /clear
Claude: Context cleared. Wie kann ich helfen?
User: Implementiere F-0045

Error-Handling

Item nicht gefunden

$ python scripts/backlog_item.py get F-9999
Error: Item F-9999 not found in docs/Backlog.md

# Claude's Reaktion:
# "Item F-9999 existiert nicht. Verfügbare Features:"
$ python scripts/backlog_item.py list --type F

Parse-Fehler nach Update

$ python scripts/backlog_item.py update F-0032 --status "Invalid"
Error: Validation failed:
  - Invalid status 'Invalid'. Must be: Offen, In Arbeit, Blockiert, Erledigt

# Claude's Reaktion:
# "Korrigiere Status auf gültigen Wert"
$ python scripts/backlog_item.py update F-0032 --status "Erledigt"

Backup-Recovery

# Wenn etwas schiefgeht:
ls -la .backlog-admin/backups/
# backlog-2026-02-03_10-15-00.md
# backlog-2026-02-03_10-30-45.md

# Restore latest backup:
cp .backlog-admin/backups/backlog-2026-02-03_10-30-45.md docs/Backlog.md

# App erkennt Änderung automatisch via FileWatcher

Integration mit App

App erkennt Script-Änderungen

1. Claude: python scripts/backlog_item.py update F-0032 --status "Erledigt"
2. Script: Writes Backlog.md mit Backup
3. FileWatcher: Erkennt Änderung (nach 500ms)
4. App: Hash-Check → External Change
5. App: Kein Konflikt (keine ungespeicherten Änderungen)
6. App: Auto-Reload → Parser → DB Update
7. UI: Zeigt F-0032 mit Status "Erledigt"

Latenz: ~600ms (500ms debounce + 100ms parse)

Performance-Metriken

Vorher (safe_backlog_edit.py)

Operation Time Context-Lines Git-Diff-Lines
Update Status 5s 3900 3900
Add Item 5s 3900 3900
Find Item 2s 3900 N/A

Nachher (backlog_item.py)

Operation Time Context-Lines Git-Diff-Lines
Update Status <200ms 20 (JSON) 2-5
Add Item <200ms 0 (direkt) ~15
Find Item <50ms 1 (grep) N/A

Speedup: ~25x schneller, ~200x weniger Context

Nächste Schritte

  1. Implementiere backlog_item.py (siehe Scripts Concept)
  2. Update CLAUDE.md mit neuen Regeln
  3. Teste mit echten Claude Code Sessions
  4. Dokumentiere Edge-Cases
  5. Erstelle Beispiele für alle Use Cases

Siehe auch