279 lines
13 KiB
Markdown
279 lines
13 KiB
Markdown
# Claude Kontext — Clowdex
|
||
|
||
Dieses Projekt nutzt Clowdex, ein umfassendes Workflow-System für Claude Code.
|
||
Lies immer zuerst `.claude/memory.md` bevor du handelst.
|
||
|
||
## Schnellstart
|
||
- `/start` — Arbeit beginnen
|
||
- `/sync` — Zwischendurch Kontext auffrischen
|
||
- `/end-day` — Arbeitstag beenden
|
||
- `/audit` — Qualität der letzten Arbeit prüfen
|
||
- `/flush` — Kontext sicher leeren und frisch fortfahren
|
||
- `/unstick` — Wenn du feststeckst
|
||
- `/retro` — Sprint-Retrospektive
|
||
- `/system-audit` — Tiefenprüfung der Infrastruktur
|
||
|
||
## Wichtige Dateien
|
||
- Memory: `.claude/memory.md` (aktueller Kontext — zuerst lesen)
|
||
- Wissensdatenbank: `.claude/knowledge-base.md` (systemweite Regeln — vor jeder Aufgabe lesen)
|
||
- Aufgabenboard: `Task Board.md`
|
||
- Notizblock: `Scratchpad.md` (schnelle Notizen, verarbeitet bei /sync, geleert bei /end-day)
|
||
- Tagesnotizen: `Daily Notes/` (automatisch erstellt durch /start)
|
||
- Wissensvorschläge: `.claude/knowledge-nominations.md` (Lernkandidaten — Sentinel prüft)
|
||
- Befehlsindex: `.claude/command-index.md` (alle Befehle mit Auslösern und Tools)
|
||
|
||
## Systemarchitektur
|
||
- **Agenten** (`.claude/agents/`): Spezialisierte Sub-Agenten mit persistentem Memory
|
||
- `sentinel` — Qualitätskontrolle. Prüft Arbeit, befördert Wissen, schlägt SOP-Änderungen vor
|
||
- `pathfinder` — Hilft bei Blockaden. Ursachenanalyse und frische Lösungsansätze
|
||
- `decoder` — Übersetzt kryptische Fehlermeldungen in konkrete Fixes. Mustererkennung über Sessions hinweg
|
||
- `mirror` — Bringt dich dazu, das eigentliche Problem zu formulieren. Sokratisches Debugging
|
||
- `scribe` — Schreibt PR-Beschreibungen, Commit-Messages und Changelogs aus Diffs
|
||
- `compass` — Erkennt Scope-Creep. „Du wolltest X machen, aber jetzt machst du Y"
|
||
- `ledger` — Verfolgt technische Schulden. Katalogisiert Abkürzungen, empfiehlt Rückzahlung
|
||
- `scout` — Lernt neue Codebases schnell. Architektur-Maps, Identifikation wichtiger Dateien
|
||
- `historian` — Gräbt aus, warum Code existiert. Git Blame + Kontextrekonstruktion
|
||
- **Befehle** (`.claude/commands/`): Workflow-Rituale und Werkzeuge
|
||
- **Hooks** (`.claude/hooks/`): Deterministische Sicherheitsmaßnahmen (Logging, Validierung)
|
||
- **Logs** (`.claude/logs/`): Prüfprotokoll + Vorfallslog — automatisch durch Hooks befüllt
|
||
- **Skills** (`.claude/skills/`): Fachwissen, bei Bedarf geladen
|
||
|
||
## Memory-Architektur (6 Stufen)
|
||
1. **memory.md** — Aktiver Session-Kontext (was du gerade machst)
|
||
2. **Agent Memory** (`.claude/agent-memory/`) — Persistentes Wissen pro Agent über Sessions hinweg
|
||
3. **Wissensdatenbank** (`.claude/knowledge-base.md`) — Systemweite Regeln (durch Sentinel geprüft)
|
||
4. **Wissensvorschläge** (`.claude/knowledge-nominations.md`) — Pipeline für Lernkandidaten
|
||
5. **MCP Knowledge Graph** — Strukturierte Entitäten und Relationen (falls Memory-MCP aktiviert)
|
||
6. **Tagesnotizen** — Chronologische Session-Historie und Übergabeprotokolle
|
||
|
||
## Befehlsnutzung
|
||
|
||
Alle Agenten können Systembefehle aufrufen. Lies `.claude/command-index.md` für den vollständigen Katalog.
|
||
|
||
- **Selbst ausführen**: Wenn du die nötigen Tools hast, lies `.claude/commands/{name}.md` und folge der Anleitung direkt.
|
||
- **Empfehlen**: Wenn dir Tools fehlen, gib `RECOMMEND: /command [args] — [reason]` an den Orchestrator aus.
|
||
- Agenten sollten Befehle proaktiv aufrufen, wenn die Auslösebedingungen zutreffen.
|
||
|
||
## Schnellzugriff — Wo du was findest
|
||
|
||
| Du brauchst... | Prüfe zuerst | Dann |
|
||
|---|---|---|
|
||
| Was mache ich gerade? | `memory.md` → Now | Task Board → Today |
|
||
| Wie geht ein Verfahren? | `.claude/commands/` oder `.claude/skills/` | CLAUDE.md |
|
||
| Eine Regel oder Erkenntnis | `knowledge-base.md` | Agent Memory |
|
||
| Was an einem bestimmten Tag passiert ist | `Daily Notes/MMDDYY.md` | Prüfprotokoll |
|
||
| Was früher schiefgelaufen ist | `knowledge-base.md` → Hard Rules | Agent Memory → Known Patterns |
|
||
| Welche Befehle es gibt | `.claude/command-index.md` | `.claude/commands/{name}.md` |
|
||
|
||
## Session-Zustand
|
||
|
||
Sessions haben begrenzten Kontext. Aufwendige Operationen verbrauchen ihn schnell.
|
||
|
||
**Automatisches Sicherheitsnetz (Hooks):**
|
||
- `PreCompact`-Hook sichert den Zustand vor der Auto-Komprimierung
|
||
- `SessionStart(compact)`-Hook stellt den Kontext nach der Komprimierung wieder her
|
||
- `SessionStart(user)`-Hook setzt veraltete Gate-Dateien bei jeder neuen Session zurück
|
||
|
||
**Validierungschecks (PreToolUse Write|Edit — harte Blockaden):**
|
||
- **knowledge-base.md**: Jeder Eintrag braucht `[Source:]`-Herkunft, max 200 Zeilen, kein TBD/TODO
|
||
- **memory.md**: Max 100 Zeilen (nur Write)
|
||
- **settings.json**: Muss valides JSON sein (defektes JSON bricht alle Hooks)
|
||
- **Agent-Definitionen** (`.claude/agents/*.md`): Kein TBD/TODO — Anweisungen müssen definitiv sein
|
||
- **Ohne Gate** (iterativ): Daily Notes, Scratchpad, Templates, Logs, Commands, Skills
|
||
|
||
**Selbstüberwachung (weiche Signale — Claudes Verantwortung):**
|
||
- Nach ~30+ Tool-Aufrufen oder 3+ großen Datei-Lesevorgängen: `/flush` proaktiv ausführen
|
||
- Bei „compacting conversation"-Warnung: `/flush` sofort ausführen
|
||
- Bei Qualitätsverlust (Wiederholungen, übersehene Details): `/flush` ausführen
|
||
- Nach Abschluss einer mehrstufigen Aufgabe: `/flush` vor der nächsten unzusammenhängenden Aufgabe erwägen
|
||
- Beim Wechsel zwischen Aufgabenbereichen: Grenze anerkennen, `/flush` bei großen Wechseln bevorzugen
|
||
|
||
**So funktioniert /flush:** Destilliert den Session-Zustand in memory.md + Tagesnotiz-Übergabe und bewahrt Suchpfade. Setzt dann automatisch fort, indem der komprimierte Kontext neu geladen und die nächste Aktion ausgeführt wird. Nahtlos für den Nutzer.
|
||
|
||
## Wartung
|
||
- memory.md kompakt halten (<100 Zeilen)
|
||
- Veraltete Einträge konsequent entfernen
|
||
- Done-Liste freitags leeren
|
||
- Vorfallslog bei /sync und /end-day prüfen
|
||
- Sentinel schlägt SOP-Änderungen vor — Nutzer genehmigt vor Übernahme
|
||
|
||
---
|
||
|
||
## PROJEKTABLAUF-PROTOKOLL (Verbindlich)
|
||
|
||
Du folgst bei JEDEM Projekt diesem 7-Phasen-Protokoll.
|
||
Du darfst KEINE Phase überspringen.
|
||
Du prüfst vor jedem Phasenwechsel die Exit-Kriterien der aktuellen Phase.
|
||
Wenn Exit-Kriterien nicht erfüllt sind, bleibst du in der Phase und kommunizierst was fehlt.
|
||
|
||
### Aktueller Projektstatus (wird von dir gepflegt)
|
||
```
|
||
PHASE: [ ] 1-Scope [ ] 2-Architektur [ ] 3-Entwicklung
|
||
[ ] 4-QA [ ] 5-Security [ ] 6-Deployment [ ] 7-Doku
|
||
AKTUELLE PHASE: ___
|
||
LETZTER SCHRITT: ___
|
||
OFFEN: ___
|
||
```
|
||
|
||
---
|
||
|
||
### PHASE 1 — Scope & Setup
|
||
**Trigger:** Neues Projekt wird gestartet oder `/project-start` wird aufgerufen.
|
||
|
||
**Du führst aus (in dieser Reihenfolge):**
|
||
1. Frage den Nutzer: Projektname, Projekttyp (SaaS-App / n8n-Workflow / Python-Script / Static-Website), DSGVO-relevant (ja/nein)
|
||
2. Kopiere das Base Project: `cp -r ~/C-Stone\ Cloud/Claude\ Code/projekte/Base\ Project ~/C-Stone\ Cloud/Claude\ Code/projekte/[PROJEKTNAME]`
|
||
3. Führe `rag_query` aus mit: "Gibt es ähnliche Projekte oder Vorlagen für [PROJEKTNAME]?"
|
||
4. Lege GitHub-Repo an: `gh repo create c-stone-[projektname] --private --source=. --push`
|
||
5. Befülle `Task Board.md` mit mindestens 5 konkreten Tickets aus dem Scope
|
||
6. Aktualisiere `memory.md`: Projektname, Typ, DSGVO-Status, Startdatum
|
||
7. Trage in Projektstatus oben ein: PHASE = 1-Scope ✅, wechsle zu Phase 2
|
||
|
||
**Exit-Kriterien (alle müssen erfüllt sein):**
|
||
- [ ] Projektordner unter `projekte/[NAME]/` vorhanden
|
||
- [ ] GitHub-Repo angelegt, initialer Push erfolgt
|
||
- [ ] DSGVO-Anforderung in memory.md dokumentiert
|
||
- [ ] Task Board hat ≥ 5 Tickets
|
||
- [ ] RAG-Query ausgeführt, Ergebnis in Scratchpad.md notiert
|
||
|
||
---
|
||
|
||
### PHASE 2 — Architektur
|
||
**Trigger:** Phase 1 Exit-Kriterien erfüllt.
|
||
|
||
**Stack-Entscheidung (automatisch nach Projekttyp):**
|
||
- SaaS-App → FastAPI + PostgreSQL + Redis + React/Vite + Docker Compose + Traefik
|
||
- n8n-Workflow → n8n Webhook + Flask Microservice + SeaTable
|
||
- Python-Script → Python 3 + boto3 (Bedrock Frankfurt) + openpyxl wenn Excel
|
||
- Static-Website → HTML5 + CSS3 + Vanilla JS, kein Backend
|
||
|
||
**Du führst aus:**
|
||
1. Erstelle Ordnerstruktur passend zum Stack
|
||
2. Erstelle `docker-compose.yml` mit Traefik-Labels für `[projekt].c-stone-dev.com`
|
||
3. Erstelle `.env.example` (alle Keys als Platzhalter, NIE echte Werte)
|
||
4. Erstelle `.gitignore` (muss enthalten: `.env`, `.env.*`, `*.pem`, `node_modules/`, `__pycache__/`, `.DS_Store`)
|
||
5. Erstelle `.nextcloudignore` (muss enthalten: `node_modules/`, `__pycache__/`, `.env`, `*.db`, `venv/`)
|
||
6. Entwirf Datenbankschema in `docs/schema.md` (bei SaaS-Apps)
|
||
7. Notiere Architekturentscheidungen in `knowledge-base.md` des Projekts
|
||
8. Initialer Commit: `git add -A && git commit -m "chore: Projektstruktur und Architektur"`
|
||
|
||
**Exit-Kriterien:**
|
||
- [ ] Ordnerstruktur angelegt
|
||
- [ ] docker-compose.yml vorhanden mit Traefik-Labels
|
||
- [ ] .gitignore und .nextcloudignore vorhanden und vollständig
|
||
- [ ] .env.example vorhanden (keine echten Werte)
|
||
- [ ] Architektur in knowledge-base.md dokumentiert
|
||
- [ ] Commit "chore: Projektstruktur" auf GitHub
|
||
|
||
---
|
||
|
||
### PHASE 3 — Entwicklung (Iterativ)
|
||
|
||
**Tool-Wahl (du empfiehlst dem Nutzer aktiv das richtige Tool):**
|
||
|
||
| Aufgabe | Tool | Modell |
|
||
|---|---|---|
|
||
| Tab-Autocomplete, einzelne Zeilen | Continue.dev | qwen2.5-coder:14b |
|
||
| Einzelne Funktion, Snippet (≤ 2 Dateien) | Continue.dev | devstral:24b / qwen3:30b |
|
||
| Ordnerstruktur, Boilerplate (≥ 3 Dateien) | Cline | devstral:24b (lokal) |
|
||
| Feature über mehrere Dateien | Cline | Qwen3 235B (Bedrock) |
|
||
| Tests schreiben + ausführen + fixen | Cline | Devstral 123B (Bedrock) |
|
||
| Refactoring über gesamte Codebase | Cline | Qwen3 235B (Bedrock) |
|
||
| SSH Hetzner, Docker, Playwright, RAG-Query | Claude Code | Claude Sonnet 4.6 |
|
||
|
||
**Du führst aus (pro Feature-Zyklus):**
|
||
1. Feature-Branch anlegen: `git checkout -b feature/[beschreibung]`
|
||
2. Empfehle dem Nutzer das passende Tool für diese Aufgabe
|
||
3. Nach Implementierung: Lokal testen
|
||
4. Atomic Commit mit Conventional-Commit-Message (`feat:` / `fix:` / `refactor:` / `test:` / `security:` / `docs:` / `chore:`)
|
||
5. Nach 3–4h: `/sync` aufrufen
|
||
6. Bei Blockade: `/unstick` aufrufen
|
||
|
||
**Sicherheitsregel:** NIEMALS echte Credentials in Dateien · NIEMALS .env committen · IMMER .gitignore prüfen
|
||
|
||
**Exit-Kriterien:**
|
||
- [ ] Alle Features aus Task Board implementiert
|
||
- [ ] Code läuft lokal in Docker ohne Fehler
|
||
- [ ] Keine ERROR-Logs in `docker logs`
|
||
- [ ] Alle Commits auf GitHub gepusht
|
||
|
||
---
|
||
|
||
### PHASE 4 — QA & Testing
|
||
|
||
1. `pytest tests/ -v` — 0 Fehler
|
||
2. `docker compose build --no-cache && docker compose up -d`
|
||
3. Playwright E2E: Happy Path, Screenshots 1440px + 375px
|
||
4. Swagger unter `http://localhost:8000/docs` erreichbar?
|
||
5. DSGVO: Logs anonym? AWS Region = `eu-central-1`?
|
||
6. `/audit`
|
||
|
||
**Exit-Kriterien:** pytest grün · Docker "Up" · Playwright grün · /audit OK · DSGVO geprüft
|
||
|
||
---
|
||
|
||
### PHASE 5 — Security Gate (PFLICHT, nicht überspringbar)
|
||
|
||
1. Secrets-Scan: `git grep -rn "AWS_ACCESS\|AWS_SECRET\|PASSWORD\|SECRET_KEY\|TOKEN\|api_key" --include="*.py" --include="*.js" --include="*.ts" -- ':!.env.example'`
|
||
2. Staged-Files: `git diff --cached --name-only | grep -i "\.env\|credentials\|secret\|key"`
|
||
3. .env in .nextcloudignore?
|
||
4. Auth: alle Endpunkte außer `/health` + `/docs` hinter `Depends(get_current_user)`?
|
||
5. slowapi auf kritischen Endpunkten?
|
||
6. `pip-audit` + `npm audit`
|
||
7. `grep -r "eu-central-1\|eu-north-1" backend/ --include="*.py"`
|
||
|
||
**Bei EINEM Fehler: KEIN Deployment.**
|
||
|
||
**Exit-Kriterien:** Secrets 0 · .env ausgeschlossen · Auth OK · keine kritischen CVEs · DSGVO-Region bestätigt
|
||
|
||
---
|
||
|
||
### PHASE 6 — Deployment auf Hetzner
|
||
|
||
1. Finaler Push + Tag
|
||
2. `ssh root@n8n.c-stone-dev.com`
|
||
3. Repo klonen/pullen, .env manuell anlegen
|
||
4. `docker compose build --no-cache && docker compose up -d`
|
||
5. `docker exec [PROJEKTNAME]-backend-1 alembic upgrade head`
|
||
6. 5 Minuten Logs beobachten
|
||
7. Playwright E2E gegen `https://[projekt].c-stone-dev.com`
|
||
|
||
**Exit-Kriterien:** alle services "Up" · HTTPS erreichbar · E2E grün · 5min Logs OK · Git-Tag gesetzt
|
||
|
||
---
|
||
|
||
### PHASE 7 — Dokumentation & Wissenstransfer
|
||
|
||
1. README.md aktualisieren
|
||
2. `cp README.md ~/cstone-rag/inbox/[PROJEKTNAME]-readme.md`
|
||
3. knowledge-base.md ≥ 3 Einträge
|
||
4. `/retro` + `/end-day`
|
||
5. Neues Projekt in C-Stone-Setup-Public.html eintragen
|
||
|
||
**Exit-Kriterien:** README vollständig · RAG befüllt · knowledge-base ≥ 3 · /retro ausgeführt
|
||
|
||
---
|
||
|
||
## VERHALTEN BEI PHASENÜBERGÄNGEN
|
||
|
||
Abschluss: `✅ PHASE [N] ABGESCHLOSSEN — Wechsle zu PHASE [N+1]: [Name] — Erste Aktion: [...]`
|
||
|
||
Nicht abgeschlossen: `⏸ PHASE [N] NOCH NICHT ABGESCHLOSSEN — Fehlend: [...] — Ich behebe jetzt: [...]`
|
||
|
||
Überspringen-Anfrage: `⚠️ Fehlende Checks: [...] — Bist du sicher? Antworte mit "ja, überspringen"`
|
||
|
||
---
|
||
|
||
## DSGVO-REGEL: GITHUB & EXTERNE DIENSTE (Nicht verhandelbar)
|
||
|
||
GitHub (MCP + CLI + gh) NUR für technische Inhalte — NIEMALS für:
|
||
- Kundennamen, E-Mail-Adressen, Telefonnummern realer Personen
|
||
- Inhalte aus Kundengesprächen oder Beratungssessions
|
||
- Daten aus SeaTable (CRM, Leads, Kontakte)
|
||
|
||
**Begründung:** GitHub läuft auf US-Servern (Microsoft) — DSGVO Art. 44 ff.
|
||
|
||
**Prüfpflicht:** Vor jedem GitHub-Befehl auf Personenbezug prüfen. Bei Unsicherheit:
|
||
`⛔ DSGVO-CHECK: "[Text]" — Formulierung anpassen oder nur lokal speichern.`
|
||
|
||
**Bedrock-Region:** Nur eu-central-1 (Frankfurt) oder eu-north-1 (Stockholm). Niemals US-Regionen.
|