markus/c-stone-invoice-check
1
0
Fork 0
Code Issues Pull requests Projects 1 Releases Packages Wiki Activity Actions
c-stone-invoice-check/clowdex-download/.claude/CLAUDE.md

13 KiB
Raw Blame History

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.