Claude Code Regeln (MANDATORY)¶

Strikte Regeln für AI-Agenten bei der Arbeit mit CC-Sprint.

BLOCKING REQUIREMENTS

Diese Regeln MÜSSEN befolgt werden. Verstöße führen zu Datenkorruption oder -verlust.

NEVER (Absolut verboten)¶

1. Edit tool auf docs/Backlog.md¶

# ❌ NIEMALS
Edit docs/Backlog.md

Warum: Edit-Tool scheitert systematisch (siehe Edit-Tool Failure)

Fehler: "String to replace not found"

Alternative: Rust Command safe_backlog_edit oder CLI ccs backlog edit

2. Komplettes Backlog.md in Context laden¶

# ❌ NIEMALS (außer absolut nötig)
Read docs/Backlog.md  # 3900+ Zeilen → Context voll

Warum: Context-Overflow, langsame Responses

Alternative: Nur relevante Items via Tauri Commands laden

3. Timestamps raten¶

# ❌ NIEMALS
# "**Letzte Aktualisierung**: 2026-02-03 19:45"  # Geraten!

Warum: Timestamp-Mismatch führt zu Edit-Fehlern

Alternative: Rust Command get_timestamp oder CLI ccs timestamp

4. Item-Inhalte aus Gedächtnis annehmen¶

# ❌ NIEMALS annehmen, dass Item so aussieht wie zuletzt gelesen

Warum: File kann sich zwischen Reads geändert haben

Alternative: Immer aktuell via list_items / get_item laden

5. Bash für File-Edits auf Projekt-Dateien¶

# ❌ NIEMALS
echo "..." >> docs/Backlog.md
sed -i 's/.../...' docs/Backlog.md

Warum: Kein Backup, keine Validierung, kein File-Watcher Trigger

Alternative: Rust Commands oder ccs CLI

ALWAYS (Pflicht)¶

1. Rust Commands für Backlog-Änderungen¶

// ✅ IMMER - Tauri Commands verwenden
await invoke('safe_backlog_edit', {
  projectPath: '.',
  mode: { mode: 'InsertBefore', marker: '## Technical Tasks' },
  content: newItem
})

Oder CLI:

# ✅ IMMER
ccs backlog edit --project . --file new_item.md --insert-before "## Technical Tasks"

Warum: Sicher, validiert, automatisches Backup

2. Timestamps mit Rust holen¶

// ✅ IMMER
const timestamp = await invoke('get_timestamp', { format: 'backlog' })

Oder CLI:

ccs timestamp --format backlog

3. Status UND Phase synchron halten¶

// ✅ IMMER beide aktualisieren
await invoke('update_item', {
  projectId,
  itemId: 'F-0032',
  request: { status: 'Erledigt', phase: 'Done' }
})

Mapping: | Status | Typische Phase | |--------|----------------| | Offen | Idee, Analyse | | In Arbeit | Umsetzung, Test | | Erledigt | Done | | Blockiert | (beliebige Phase) |

4. Validieren vor Commit¶

# ✅ IMMER nach Backlog-Änderungen
ccs backlog validate --project .

# Oder in App: Konsistenzprüfung im Dashboard

5. Konsistenzprüfung nutzen¶

// ✅ IMMER - Prüft alle Items
const result = await invoke('check_consistency', { projectId })
if (!result.isConsistent) {
  console.error('Konsistenzfehler:', result.issues)
}

Workflow-Templates¶

Template: Feature implementieren¶

# 1. Finde Feature (grep ist erlaubt für read-only)
grep -n "### \[F-XXXX\]" docs/Backlog.md

# 2. Lade Details via Tauri/CLI
ccs backlog validate --project .  # Prüft ob alles konsistent

# 3. Update Status → In Arbeit (via App oder API)
# In App: Item öffnen → Status ändern → Speichern

# 4. Lese relevante Code-Files (max 5-10)
Read app/src/components/Foo.tsx
Read app/src/hooks/useBar.ts

# 5. Implementiere Feature
Edit app/src/components/Foo.tsx
Edit app/src/hooks/useBar.ts

# 6. Teste (manuell oder automated)

# 7. Update Status → Erledigt (via App)

# 8. Commit
git add .
git commit -m "Implement Feature X (F-XXXX)"

Template: Bug fixen¶

# 1. Bug identifizieren (in App oder via grep)
grep -n "### \[B-" docs/Backlog.md | head -10

# 2. Status → In Arbeit (via App)

# 3. Debug & Fix...

# 4. Status → Erledigt (via App)

# 5. Commit
git commit -m "Fix Bug X (B-XXXX)"

Template: Neues Item via CLI erstellen¶

# Item-Datei erstellen
cat > /tmp/new_item.md << 'EOF'
### [F-0051] Feature Name
- **Status**: Offen
- **Priorität**: Mittel
- **Phase**: Idee
- **Bereich**: funktional
- **Beschreibung**:
  Beschreibung des Features...
EOF

# Einfügen via CLI
ccs backlog edit --project . --file /tmp/new_item.md --insert-before "## Technical Tasks"

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

Status-Management¶

Status-Übergänge¶

Von	Nach	Wann	Phase
Offen	In Arbeit	Arbeit beginnt	→ Umsetzung
In Arbeit	Erledigt	Arbeit fertig	→ Done
In Arbeit	Blockiert	Dependency fehlt	(unverändert)
Blockiert	In Arbeit	Blocker gelöst	(unverändert)

Gültige Werte¶

Feld	Gültige Werte
Status	Offen, In Arbeit, Blockiert, Erledigt
Priorität	Hoch, Mittel, Niedrig
Phase	Idee, Analyse, Umsetzung, Test, Done, -
Bereich	funktional, technisch, design, sonstiges, -
Typ	F, T, B, C

Error-Handling¶

Validierungs-Fehler¶

$ ccs backlog validate --project .
{
  "valid": false,
  "errors": ["Item F-0032: Invalid status 'Planung'"]
}

# Reaktion: In App korrigieren oder via safe_backlog_edit

Konsistenz-Warnung¶

const result = await invoke('check_consistency', { projectId })
// result.issues enthält:
// { itemId: "F-0032", message: "Status ist 'Erledigt', aber Phase ist 'Umsetzung'" }

// Reaktion: Phase auf 'Done' setzen

Recovery bei Problemen¶

Backup wiederherstellen¶

# Liste Backups
ccs backup list --project .

# Restore
ccs backup restore --project . backlog-2026-02-04_15-30-00.md

# App reloaded automatisch via FileWatcher

Datenbank neu aufbauen¶

// In App oder via API
await invoke('rebuild_database', { projectId })

Best Practices¶

1. Minimale Context-Usage¶

# ❌ Schlecht (4000+ Zeilen)
Read docs/Backlog.md

# ✅ Gut - Nur Item-Details laden
grep -n "### \[F-0032\]" docs/Backlog.md
# Dann in App Details anschauen

2. Rust Commands bevorzugen¶

Operation	Bevorzugt	Alternativ
Backlog editieren	`safe_backlog_edit`	`ccs backlog edit`
Timestamp holen	`get_timestamp`	`ccs timestamp`
Validieren	`check_consistency`	`ccs backlog validate`
Git Commit	`git_commit_and_push`	`ccs git commit`

3. Status nicht vergessen¶

# ❌ Häufiger Fehler: Feature implementiert, Status nicht aktualisiert

# ✅ Korrekt: Status immer mitpflegen
# In App: Item öffnen → Status: Erledigt, Phase: Done → Speichern

Siehe auch¶

CLI Referenz - ccs Befehle
API Referenz - Tauri Commands
Edit-Tool Failure - Warum Edit-Tool scheitert

Letzte Aktualisierung: 2026-02-04