Claude Code Workflow

Ueberblick

Claude Code hat kein Langzeitgedaechtnis zwischen Sessions. Wer ein Projekt ueber Wochen mit Claude Code entwickelt, kennt das Problem: STATE.md ist veraltet, TODO.md stimmt nicht mehr, und bei jedem Session-Start muss man erklaeren wo man steht.

Dieses Workflow-System loest das durch eingebauten Doku-Sync in jedem Command. Jeder Befehl der Code aendert, aktualisiert automatisch die Projekt-Dokumentation — ohne Rueckfrage, ohne separaten Commit.

Architektur

Drei Schichten, klar getrennt:

Die Custom Commands sind das User-Interface — sie definieren was bei /quick, /build etc. passiert. Die GSD Engine uebernimmt die schwere Arbeit: Planung, Parallelisierung, atomare Commits, Verification. Die State-Dateien sind die Persistenz-Schicht — sie ueberleben Sessions und Context-Resets.

State-Dateien

Vier Dateien bilden das Gedaechtnis des Projekts. Jede hat einen klaren Zweck:

STATE.md — Aktueller Arbeitsstand

# Projekt — Status

**Zuletzt bearbeitet:** 2026-03-09
**Aktive Phase:** Phase 5 — Plattform-Pakete
**Letzter Meilenstein:** Phase 4 abgeschlossen (2026-03-02)

### Was diese Session passiert ist (2026-03-09):
- Quick-Fix: gosec G115 Lint-Warning behoben
- Feature X implementiert

### Naechste Schritte
- Phase 5 planen

### Phasen-Uebersicht
| Phase | Status          |
|-------|-----------------|
| 1-4   | ABGESCHLOSSEN   |
| 5     | NAECHSTER SCHRITT |

### Quick Tasks Completed
| # | Description        | Date       | Commit  | Directory    |
|---|--------------------|------------|---------|--------------|
| 1 | Fix gosec G115     | 2026-03-09 | 265fa39 | [link](...)  |

### Blocker
Keine.

TODO.md — Aufgaben

# Projekt — Aufgaben

## Naechste Schritte
- [ ] **Task A** | Wo: Modul | Prio: hoch
- [ ] **Task B** | Wo: Modul | Prio: mittel

## Spaeter
- [ ] **Task C** | Wo: Modul | Prio: niedrig

## Erledigt
- [x] Task D (2026-03-01)

MEMORY.md — Langzeitgedaechtnis

roadmap.md — Phasenplan

| Phase | Beschreibung       | Status          |
|-------|--------------------|-----------------|
| 1     | Foundation         | ABGESCHLOSSEN   |
| 2     | Feature X          | ABGESCHLOSSEN   |
| 3     | Feature Y          | GEPLANT         |

Commands

Dateien in .claude/commands/. Jede Datei wird als /command-name aufrufbar. $ARGUMENTS wird durch die User-Eingabe ersetzt.

/status — Orientierung

# .claude/commands/status.md

Lies folgende Dateien und gib eine kompakte Zusammenfassung:

1. `STATE.md` — Aktueller Arbeitsstand
2. `TODO.md` — Offene Aufgaben
3. `.planning/roadmap.md` — Nur die Uebersichtstabelle

Zusaetzlich GSD-State pruefen:
- `.continue-here.md` vorhanden? → Hinweis: "Unterbrochene Arbeit gefunden"
- `git log --oneline -5` — Letzte Commits

Ausgabe-Format:
## Status
- **Phase:** [aktive Phase + Status]
- **Letzter Meilenstein:** [was + wann]
- **Naechster Schritt:** [was konkret ansteht]

## Offene Aufgaben
- [Top 3 aus TODO.md, nach Prio]

## Letzte Commits
- [5 letzte Commits einzeilig]

Dann frage: "Weitermachen mit [naechster Schritt], oder anderes Thema?"

/think [thema] — Brainstorming

# .claude/commands/think.md

Iterativer Denk-Modus. Thema: $ARGUMENTS

PHASE 1 — KONTEXT LADEN (still):
Starte einen Explore-Agent:
"Analysiere den aktuellen Projektstand fuer das Thema: [THEMA].
Lies: STATE.md, CLAUDE.md, roadmap.md.
Falls Code betroffen: finde relevante Packages."

PHASE 2 — ITERATIVES PING-PONG:
- KURZ. Max 3-5 Saetze pro Gedanke, dann Rueckfrage.
- Eigene Meinung einbringen, nicht nur Optionen listen.
- JEDE Antwort endet mit EINER konkreten Rueckfrage.
  Nicht "Was denkst du?" sondern:
  "Soll der Updater als Goroutine laufen oder im Sync-Loop?"

PHASE 3 — KONVERGENZ:
Nach 3+ Antworten ohne Richtungsaenderung:
"Wir sind uns einig. Soll ich das als Plan-Datei festhalten?"

WAS /think NICHT tut:
- Keinen Code schreiben
- Keine Dateien aendern ausser Plan-Dateien am Ende
- Keine langen Monologe

/quick [aufgabe] — Kleiner Fix

# .claude/commands/quick.md

Schneller Fix. Aufgabe: $ARGUMENTS

Dieser Command delegiert an GSD quick.
Rufe `/gsd:quick $ARGUMENTS` auf.

GSD uebernimmt: Planung, Execution, atomare Commits, State-Tracking.

Flags (optional):
- `--discuss` — Diskussion vor Planung
- `--full` — Plan-Checking + Verification

---

## Nach GSD-Quick: Doku-Sync (PFLICHT)

Wenn GSD quick abgeschlossen ist, fuehre IMMER aus:

### 1. TODO.md pruefen
- Passender Eintrag vorhanden? → abhaken mit `[x]` und Datum
- Kein TODO vorhanden? → kein neuer Eintrag noetig

### 2. STATE.md aktualisieren
- Einzeilige Notiz: `- Quick-Fix: [was gemacht wurde]`
- Datum im Header aktualisieren falls veraltet

### 3. MEMORY.md pruefen (nur bei Bedarf)
- Neue Eigenheit aufgedeckt? → eintragen
- Sonst: nichts aendern

Alle Schritte ohne Rueckfrage — kein separater Commit.

/prepare [thema] — Feature planen

# .claude/commands/prepare.md

Feature-Plan erstellen. Thema: $ARGUMENTS

ABLAUF:
1. /gsd:discuss-phase $ARGUMENTS — sammelt Kontext
2. /gsd:plan-phase — erstellt PLAN.md

## Nach Plan-Erstellung: Doku-Sync (PFLICHT)

### 1. roadmap.md aktualisieren
- Phase eintragen, Status GEPLANT

### 2. STATE.md aktualisieren
- "Aktive Phase" und "Naechste Schritte" anpassen

Ohne Rueckfrage ausfuehren.

/build [args] — Phase implementieren

# .claude/commands/build.md

Autonomer Build-Workflow. Argument: $ARGUMENTS

Rufe `/gsd:execute-phase` auf.

## Nach Phase-Complete: Doku-Sync (PFLICHT)

### 1. TODO.md — Passende Eintraege abhaken, neue eintragen
### 2. roadmap.md — Phase-Status auf ABGESCHLOSSEN
### 3. STATE.md — Zusammenfassung + Naechste Schritte
### 4. MEMORY.md — Neue Patterns, Meilensteine eintragen

Ohne Rueckfrage — kein separater Commit.

/test [scope] — Quality Gates

# .claude/commands/test.md

Quality Gates ausfuehren und Ergebnis zusammenfassen.

Modus: $ARGUMENTS
- Kein Argument: Alle Gates (lint + test + vuln)
- "lint" / "test" / "server" / "client" / "vuln": Einzeln

Gates PARALLEL ausfuehren. Ergebnis kompakt:
Lint:    [OK / N issues]
Server:  [OK / FAIL] — Coverage: XX.X%
Client:  [OK / FAIL] — Coverage: XX.X%
Vuln:    [OK / N vulnerabilities]

Bei Fehlern: Ursache analysieren, Fix vorschlagen, fragen.
Bei Erfolg: Nur Zusammenfassung.

/todo [text] — Aufgabe eintragen

# .claude/commands/todo.md

Fuege einen neuen Eintrag in TODO.md hinzu: $ARGUMENTS

Format: - [ ] **Beschreibung** | Wo: Modul | Prio: hoch/mittel/niedrig | [Datum]
Heutiges Datum verwenden.
Falls kein Modul erkennbar: "Gesamt"
Falls keine Prio angegeben: "mittel"

Doku-Sync — Das Herzstueck

Der Doku-Sync ist der entscheidende Unterschied zu "normalem" Claude Code + GSD. Er ist als PFLICHT-Block in jeden Command eingebaut der Code aendert.

Was wird wann aktualisiert?

Warum "ohne Rueckfrage"?

Jeder Doku-Sync-Block endet mit "Alle Schritte ohne Rueckfrage ausfuehren". Das ist entscheidend — wenn Claude fragt "Soll ich TODO.md aktualisieren?", sagt der User oft "nein" oder ignoriert es. Durch die PFLICHT-Formulierung im Command-Prompt fuehrt Claude den Sync automatisch aus.

Auto-Routing

In der CLAUDE.md definiert man Regeln, damit Claude automatisch den richtigen Workflow waehlt — auch wenn der User keinen expliziten Command nutzt:

# In CLAUDE.md:

## Auto-Routing

Claude erkennt automatisch welcher Workflow passt:

- Frage/Idee/Impuls → wie /think (kurz, Rueckfrage, iterativ)
- Konkreter Bug/Fix → wie /quick
- "Bau das" / "Implementier das" → Plan pruefen, sonst /prepare vorschlagen
- Neue Session / Gruss → wie /status (Context-Recovery)

Recovery-Kette

Bei Session-Start oder Context-Reset liest Claude automatisch den Projektzustand. Die Reihenfolge ist in CLAUDE.md als IMPORTANT markiert:

# In CLAUDE.md:

## Recovery-Kette (bei Context-Reset oder Session-Start)

IMPORTANT — Bei der ERSTEN Nachricht einer neuen Session:

1. STATE.md lesen (still) — wo stehen wir?
2. GSD-State pruefen: .continue-here.md vorhanden? → /gsd:resume-work empfehlen
3. Falls kein GSD-State: git log --oneline -10 als Fallback
4. User gibt Aufgabe → Kontext nutzen, nicht erst fragen
5. User gruesst oder unklar → wie /status verhalten

Typische Flows

Feature entwickeln

Bug fixen nach /test

Mehrere Bugs

Idee festhalten

Session starten

Setup fuer ein neues Projekt

Voraussetzungen

• Claude Code installiert
• GSD Plugin installiert (/gsd:help funktioniert)
• Projekt mit Git initialisiert

Schritt 1: State-Dateien anlegen

touch STATE.md TODO.md
mkdir -p .planning

STATE.md und TODO.md mit den Grundstrukturen befuellen (siehe State-Dateien).

Schritt 2: GSD initialisieren

/gsd:new-project

Erstellt .planning/ROADMAP.md, PROJECT.md, und die GSD-Infrastruktur.

Schritt 3: Commands anlegen

Die Command-Dateien von oben kopieren und an das Projekt anpassen. Insbesondere /test muss an die Toolchain angepasst werden (z.B. npm test statt make test).

Schritt 4: CLAUDE.md schreiben

Muss enthalten:

1. Projekt-Beschreibung (1-2 Saetze)
2. Checklisten vor Code-Aenderungen (Security, Patterns, Domain-Regeln)
3. Konventionen (Sprache, Packages, Config, Commits)
4. Command-Uebersicht mit typischen Flows
5. Auto-Routing Regeln
6. State-Pflichten (was manuell, was automatisch)
7. Recovery-Kette bei Session-Start

Schritt 5: MEMORY.md initialisieren

# In Claudes Auto-Memory Verzeichnis:
# ~/.claude/projects/<project-path>/memory/MEMORY.md

# Projekt Memory

## Build-Fortschritt
(wird mit der Zeit befuellt)

## Wichtige Pfade
- Projekt: /pfad/zum/projekt

## Bekannte Eigenheiten
(wird bei Bedarf befuellt)

Schritt 6: Testen

Starte Claude Code im Projekt und tippe /status. Wenn die Zusammenfassung erscheint, funktioniert das System. Dann /quick "test: hello world" — wenn danach STATE.md und TODO.md aktualisiert wurden, ist der Doku-Sync aktiv.