claudient 0.1.0

package/workflows/de/debugging-session.md

@@ -0,0 +1,146 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../debugging-session.md).
+
+# Debugging-Sitzungs-Workflow
+
+Systematischer Workflow zur Diagnose und Behebung von Bugs mit Claude Code — ohne Symptome zu jagen.
+
+---
+
+## Wann diesen Workflow verwenden
+- Ein Bug, der nicht sofort aus dem Code ersichtlich ist
+- Ein fehlschlagender Test, dessen Ursache unklar ist
+- Produktionsfehler, der lokal nicht reproduziert werden kann
+- Intermittierende Fehler
+
+---
+
+## Schritt 1 — Zuerst eine Feedback-Schleife aufbauen
+
+Vor der Untersuchung einen zuverlässigen Weg zur Reproduktion des Bugs erstellen. Diesen Schritt nicht überspringen.
+
+**Claude fragen:**
+```
+I have a bug: [describe the symptom exactly — error message, unexpected behavior, what you expected]
+
+Before we investigate, help me build a reliable way to reproduce it.
+
+Options to consider:
+- A failing test that captures the bug
+- A curl command or script that triggers it
+- A minimal code snippet that demonstrates it
+- Steps to reproduce via the UI
+
+Which is most appropriate here, and write it now.
+```
+
+**Nicht fortfahren, bis eine zuverlässige Reproduktion vorhanden ist.** Debuggen ohne Reproduktion ist Raten.
+
+---
+
+## Schritt 2 — Den Wirkungsbereich isolieren
+
+Verstehen, wo der Bug überhaupt liegen kann, bevor Code gelesen wird.
+
+**Claude fragen:**
+```
+Here is the reproduction: [paste the reproduction from Step 1]
+
+Without looking at code yet, answer:
+1. What is the earliest point in the call stack where this could go wrong?
+2. What external systems are involved (DB, cache, third-party API, queue)?
+3. What changed recently that could have introduced this? (check git log)
+4. What is the smallest unit of code that, if wrong, would cause this symptom?
+
+List the files most likely to contain the bug, ranked by probability.
+```
+
+---
+
+## Schritt 3 — Hypothesen generieren
+
+**Claude fragen:**
+```
+Based on the reproduction and the candidate files, generate 3–5 falsifiable hypotheses.
+
+For each hypothesis:
+- State it as a specific claim: "The bug occurs because [X] when [Y]"
+- Describe how to test it: what would we observe if this hypothesis is true?
+- Describe how to disprove it: what would we observe if it's false?
+
+Do not start testing yet. List all hypotheses first.
+```
+
+Die Hypothesen überprüfen. Eigene Ideen hinzufügen, die Claude verpasst hat. Nach Wahrscheinlichkeit ordnen.
+
+---
+
+## Schritt 4 — Hypothesen testen, beginnend mit der wahrscheinlichsten
+
+**Für jede Hypothese:**
+```
+Test hypothesis [N]: "[paste the hypothesis]"
+
+Add the minimal instrumentation needed to confirm or rule this out:
+- A log statement at the right point
+- A debug assertion
+- A targeted test with a specific input
+
+Do not add instrumentation for other hypotheses yet.
+```
+
+Nach jedem Test:
+- Wenn bestätigt: zu Schritt 5 übergehen
+- Wenn widerlegt: zur nächsten Hypothese übergehen
+- Wenn nicht eindeutig: Hypothese verfeinern und erneut testen
+
+---
+
+## Schritt 5 — Korrigieren und verifizieren
+
+Sobald die Grundursache bestätigt ist:
+
+**Claude fragen:**
+```
+Root cause confirmed: [describe what you found]
+
+Now:
+1. Apply the minimal fix — change only what's needed to fix this specific bug
+2. Do not refactor surrounding code
+3. Update the reproduction from Step 1 to be a regression test
+4. Run the full test suite — confirm nothing else broke
+
+Explain in one sentence why this fix works.
+```
+
+---
+
+## Schritt 6 — Post-Mortem (für schwerwiegende Bugs)
+
+Für Bugs, die Benutzerauswirkungen, Datenverlust verursacht haben oder mehr als 2 Stunden zum Auffinden benötigten:
+
+**Claude fragen:**
+```
+Write a brief post-mortem for this bug:
+
+1. What was the bug? (one sentence)
+2. What was the root cause?
+3. How long did it take to find and why?
+4. What would have caught this earlier? (missing test, missing monitoring, code review gap)
+5. What should we add/change to prevent this class of bug?
+
+Keep it under 200 words. No blame, no fluff.
+```
+
+---
+
+## Zu vermeidende Anti-Muster
+
+- **Das Symptom beheben, nicht die Ursache** — wenn nicht verstanden wird warum, wurde es nicht behoben
+- **Mehrere Dinge gleichzeitig ändern** — es wird nicht bekannt sein, welche Änderung es behoben hat
+- **Debuggen ohne Reproduktion** — es wird geraten
+- **Überall Instrumentierung hinzufügen** — spezifische Hypothesen gezielt ansprechen
+- **Den Regressionstest überspringen** — der Bug kommt zurück
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. [uitbreiden.com](https://uitbreiden.com/)

package/workflows/de/feature-development.md

@@ -0,0 +1,155 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../feature-development.md).
+
+# Feature-Entwicklungs-Workflow
+
+End-to-End-Workflow für die Umsetzung eines Features von der Idee bis zum gemergten PR mit Claude Code.
+
+---
+
+## Wann diesen Workflow verwenden
+- Ein neues Feature bauen, das mehr als eine Datei berührt
+- Eine Spezifikation oder ein Ticket implementieren, das vor dem Coden zerlegt werden muss
+- Jedes Feature, bei dem ein strukturierter, überprüfbarer Prozess gewünscht wird
+
+---
+
+## Schritt 1 — Umfang definieren und validieren
+
+Bevor Code geschrieben wird, genau festlegen, was gebaut wird.
+
+**Claude fragen:**
+```
+I need to build: [describe the feature in one paragraph]
+
+Read the relevant files first:
+- [list key files: routes, models, services]
+- CLAUDE.md and CONTEXT.md if present
+
+Then tell me:
+1. What files will need to change?
+2. What new files will be created?
+3. What are the edge cases I should handle?
+4. What decisions do I need to make before we start?
+5. Are there any risks or dependencies I'm missing?
+
+Do not write code yet.
+```
+
+**Worauf in der Antwort achten:**
+- Dateien, die noch nicht bedacht wurden
+- Edge Cases, die zu Bugs führen würden, wenn sie nicht beachtet werden
+- Entscheidungen, die nach ihrer Treffen in CLAUDE.md einfließen sollten
+
+---
+
+## Schritt 2 — Die Implementierung planen
+
+Sobald der Umfang klar ist, einen sequenzierten Plan erstellen.
+
+**Claude fragen:**
+```
+Based on the scope we just defined, create a numbered implementation plan.
+
+Each step must be:
+- A concrete, bounded action (not "implement auth" — "add JWT validation middleware to src/middleware/auth.ts")
+- Completable in a single session
+- Independently testable
+
+Include which files change in each step. Note dependencies between steps.
+```
+
+Den Plan überprüfen. Wenn ein Schritt zu groß ist, Claude bitten, ihn weiter aufzuteilen. Den Plan festlegen, bevor Code berührt wird.
+
+---
+
+## Schritt 3 — Schritt für Schritt implementieren
+
+Einen Plan-Schritt nach dem anderen ausführen. Nicht überspringen.
+
+**Für jeden Schritt:**
+```
+Implement step [N]: [paste the step description]
+
+Rules:
+- Only change what's needed for this step
+- Write or update tests for this step's behavior
+- Do not refactor code outside the scope of this step
+- Tell me when this step is complete and what to verify
+```
+
+**Nach jedem Schritt:**
+- Tests ausführen: grün bestätigen, bevor zum nächsten Schritt übergegangen wird
+- Eigenes Diff überprüfen: ist das das Beabsichtigte?
+- Wenn ein Schritt neue Komplexität aufdeckt, den Plan aktualisieren, bevor fortgefahren wird
+
+---
+
+## Schritt 4 — Integrationsprüfung
+
+Sobald alle Schritte abgeschlossen sind, das vollständige Feature end-to-end verifizieren.
+
+**Claude fragen:**
+```
+All implementation steps are complete. Now:
+
+1. Run the full test suite — report any failures
+2. Check that all edge cases from Step 1 are handled — list each one and confirm
+3. Check for any TODOs or incomplete error handling introduced during implementation
+4. Verify the feature works with [specific test scenario relevant to this feature]
+```
+
+Alle gefundenen Probleme beheben, bevor fortgefahren wird.
+
+---
+
+## Schritt 5 — Selbstüberprüfung
+
+Vor dem Erstellen eines PRs die eigenen Änderungen überprüfen.
+
+**Claude fragen:**
+```
+Review the changes on this branch against main.
+
+Focus on:
+1. CRITICAL issues (bugs, security, data loss risks)
+2. Missing tests for changed behavior
+3. Convention violations vs this project's CLAUDE.md
+4. Anything that would confuse a reader in 6 months
+
+Format: CRITICAL / SUGGESTED / NITPICK
+```
+
+Alle CRITICAL-Probleme beheben. Bei SUGGESTED-Elementen nach eigenem Urteil vorgehen.
+
+---
+
+## Schritt 6 — PR-Beschreibung
+
+**Claude fragen:**
+```
+Write a PR description for these changes.
+
+Include:
+- What this PR does (one paragraph)
+- Why it's needed (the problem it solves)
+- How to test it (specific steps a reviewer can follow)
+- Any decisions made and why (reference CLAUDE.md or ADRs if relevant)
+- Screenshots or output if applicable
+
+Do not include a list of files changed — the diff covers that.
+```
+
+---
+
+## Checkliste vor dem Mergen
+
+- [ ] Alle Tests bestehen
+- [ ] Selbstüberprüfung abgeschlossen, keine CRITICAL-Probleme
+- [ ] Edge Cases aus Schritt 1 sind alle behandelt
+- [ ] PR-Beschreibung geschrieben
+- [ ] CLAUDE.md aktualisiert, wenn neue Entscheidungen getroffen wurden
+- [ ] CONTEXT.md aktualisiert, wenn neue Domain-Begriffe eingeführt wurden
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. [uitbreiden.com](https://uitbreiden.com/)

package/workflows/de/new-project-bootstrap.md

@@ -0,0 +1,175 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../new-project-bootstrap.md).
+
+# Neues Projekt Bootstrap Workflow
+
+So wird ein neues Projekt mit Claude Code aufgesetzt — strukturiert, meinungsfreudig und bereit zum Bauen vom ersten Tag an.
+
+---
+
+## Wann diesen Workflow verwenden
+- Eine neue Anwendung von Grund auf starten
+- Einen neuen Service in einem bestehenden System einrichten
+- Ein neues Repository für ein Nebenprojekt oder ein Kundenprojekt erstellen
+
+---
+
+## Schritt 1 — Definieren, was gebaut wird
+
+Bevor Code oder Konfiguration berührt wird, diese Fragen klar beantworten.
+
+**Claude fragen:**
+```
+I am starting a new project. Help me define it clearly before we write any code.
+
+What I want to build: [describe in 2–3 sentences]
+
+Ask me the following questions one at a time and wait for my answer before asking the next:
+1. Who are the users and what is the primary thing they do?
+2. What is the expected scale at launch? (users, requests/sec, data volume)
+3. What are the hard constraints? (budget, timeline, team size, existing tech stack)
+4. What does "done" look like for v1?
+5. What is explicitly out of scope for v1?
+
+After I answer all five, summarize what we're building and confirm with me before proceeding.
+```
+
+Nicht fortfahren, bis der Umfang schriftlich bestätigt ist.
+
+---
+
+## Schritt 2 — Den Stack auswählen
+
+**Claude fragen:**
+```
+Based on what we're building:
+- [paste summary from Step 1]
+
+Recommend a specific stack. For each component (backend, frontend, database, auth, deployment), recommend:
+- Your recommended choice and why it fits our constraints
+- What we'd be giving up vs the next-best alternative
+- No more than 2 options per component — I need a decision, not a menu
+
+Be opinionated. I will push back if I disagree.
+```
+
+Den Stack festlegen, bevor Code geschrieben wird. Entscheidungen in `docs/adr/` aufzeichnen, wenn sie nicht offensichtlich sind.
+
+---
+
+## Schritt 3 — Die Projektstruktur bootstrappen
+
+**Claude fragen:**
+```
+Set up the initial project structure for: [stack from Step 2]
+
+Create:
+1. The directory structure (show as a tree before creating anything)
+2. Package/dependency files with pinned versions
+3. Configuration files (TypeScript, ESLint, Prettier, etc.)
+4. .gitignore appropriate for this stack
+5. A minimal working "hello world" that proves the stack runs
+
+Do not add features yet. The goal is a running skeleton.
+```
+
+Verifizieren, dass es läuft, bevor fortgefahren wird.
+
+---
+
+## Schritt 4 — CLAUDE.md einrichten
+
+**Claude fragen:**
+```
+Create a CLAUDE.md for this project.
+
+Include:
+1. What this project is (one paragraph)
+2. Stack summary (language, framework, key libraries, DB)
+3. Directory structure with purpose of each directory
+4. Coding conventions specific to this stack
+5. Commands to run (dev server, tests, build, lint)
+6. Decisions already made (from Steps 1–3) that should not be revisited
+7. What NOT to do in this project
+
+Make it dense and useful — not a tutorial. A senior developer should be able to start contributing after reading it.
+```
+
+---
+
+## Schritt 5 — Entwicklungsumgebung einrichten
+
+**Claude fragen:**
+```
+Set up the development environment:
+
+1. Docker Compose file for local dependencies (database, cache, queues)
+2. Environment variable template (.env.example with all required vars, no real values)
+3. Database migrations setup (initial schema if applicable)
+4. Test setup (test runner config, example test, CI-ready)
+5. A Makefile or scripts/ directory with common commands:
+   - make dev (start local environment)
+   - make test (run tests)
+   - make build (production build)
+   - make lint (lint and format check)
+```
+
+---
+
+## Schritt 6 — CI einrichten
+
+**Claude fragen:**
+```
+Set up a GitHub Actions CI pipeline:
+
+On every PR:
+- Install dependencies (with cache)
+- Run lint
+- Run tests
+- Build (if applicable)
+
+Use the github-actions skill for best practices:
+- Pin action versions
+- Explicit permissions
+- Dependency caching
+- Fail fast on test failures
+
+The pipeline must pass on the current skeleton before we add features.
+```
+
+Sicherstellen, dass CI beim ersten Commit besteht, bevor Feature-Entwicklung beginnt.
+
+---
+
+## Schritt 7 — Erstes Feature planen
+
+Sobald das Skeleton läuft und CI grün ist:
+
+**Claude fragen:**
+```
+The project is bootstrapped. Now plan the first feature:
+
+Feature: [describe the first user-facing capability]
+
+Use the feature-development workflow to plan and implement it.
+Start with Step 1 of that workflow.
+```
+
+Siehe `workflows/feature-development.md`.
+
+---
+
+## Bootstrap-Checkliste
+
+- [ ] Umfang definiert und schriftlich bestätigt
+- [ ] Stack mit dokumentierter Begründung entschieden
+- [ ] Projektstruktur erstellt und läuft ("hello world" funktioniert)
+- [ ] CLAUDE.md geschrieben und committet
+- [ ] Docker Compose / lokale Abhängigkeiten laufen
+- [ ] .env.example mit allen erforderlichen Vars committet
+- [ ] Tests konfiguriert und mindestens einer bestehend
+- [ ] CI-Pipeline grün beim ersten Push
+- [ ] `docs/adr/` mit anfänglichen Architekturentscheidungen erstellt
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. [uitbreiden.com](https://uitbreiden.com/)

package/workflows/de/refactor-safely.md

@@ -0,0 +1,150 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../refactor-safely.md).
+
+# Sicher Refactoren Workflow
+
+So wird Code mit Claude Code refactoriert, ohne Verhalten zu brechen — mit Tests als Sicherheitsnetz während des gesamten Prozesses.
+
+---
+
+## Wann diesen Workflow verwenden
+- Funktionen aus einer großen Methode extrahieren
+- Module umbenennen und neu organisieren
+- Ein Muster durch ein besseres über mehrere Dateien ersetzen
+- Duplikate in der gesamten Codebase reduzieren
+- Die Struktur eines Moduls verbessern, ohne sein externes Verhalten zu ändern
+
+---
+
+## Die goldene Regel
+
+**Niemals in demselben Commit refactoren und Verhalten ändern.** Ein Refactor bewahrt das externe Verhalten. Wenn Tests fehlschlagen, wurde entweder das Verhalten geändert oder die Tests testeten Implementierungsdetails (beides ist ein Problem).
+
+---
+
+## Schritt 1 — Eine Test-Baseline etablieren
+
+Bevor irgendetwas geändert wird, eine angemessene Testabdeckung sicherstellen.
+
+**Claude fragen:**
+```
+I want to refactor: [describe what you're refactoring and why]
+
+First, assess the current test coverage:
+1. Read the relevant files: [list files]
+2. What behaviors are currently tested?
+3. What behaviors are NOT tested that could break during refactoring?
+4. Write any missing tests now, before we touch production code
+
+Do not change production code yet. Tests only.
+```
+
+**Die Test-Ergänzungen committen, bevor refactoriert wird.** So ist klar, welche Tests vor dem Refactor existierten und welche als Teil des Refactors hinzugefügt wurden.
+
+---
+
+## Schritt 2 — Den Refactor-Umfang definieren
+
+**Claude fragen:**
+```
+Here is what I want to refactor: [describe the goal]
+
+Read the relevant files: [list files]
+
+Define the scope:
+1. What will change structurally? (function signatures, file locations, module boundaries)
+2. What will NOT change? (external behavior, API contracts, database schema)
+3. What are the riskiest parts of this refactor?
+4. What is the smallest first step that makes progress without risk?
+
+Do not start the refactor yet.
+```
+
+---
+
+## Schritt 3 — In kleinen, testbaren Schritten refactoren
+
+Den Refactor in Schritte aufteilen, die klein genug sind, damit Tests jeden einzelnen verifizieren können.
+
+**Für jeden Schritt:**
+```
+Refactor step [N]: [describe the specific structural change]
+
+Rules:
+- Change only what's needed for this step
+- Do not change any behavior
+- After this change, all existing tests must still pass
+- Tell me what to verify after this step
+```
+
+**Nach jedem Schritt:**
+```bash
+# Tests ausführen — müssen grün sein, bevor nächster Schritt beginnt
+npm test  # oder pytest, go test, etc.
+```
+
+Wenn Tests nach einer rein strukturellen Änderung fehlschlagen: stoppen, verstehen warum, beheben, bevor fortgefahren wird. Ein fehlschlagender Test nach einem Refactor bedeutet entweder, dass der Refactor Verhalten geändert hat oder der Test testete Implementierung (beides sind Probleme, die jetzt zu beheben sind).
+
+---
+
+## Schritt 4 — Externes Verhalten als unverändert verifizieren
+
+Nach allen Schritten:
+
+**Claude fragen:**
+```
+The refactor is structurally complete. Verify that external behavior is unchanged:
+
+1. Run the full test suite
+2. Check that all public APIs/interfaces are identical to before (same inputs, same outputs)
+3. Check that database queries produce identical results
+4. Check that error cases still produce the same errors
+5. If there are integration tests or end-to-end tests, run them
+
+Report any behavioral differences — even small ones.
+```
+
+---
+
+## Schritt 5 — Aufräumen
+
+**Claude fragen:**
+```
+Before committing, clean up:
+
+1. Remove any debugging code or temporary comments added during refactoring
+2. Remove any dead code that the refactor made unreachable
+3. Update any documentation or comments that referenced the old structure
+4. Check that import paths are clean (no unused imports)
+
+Do not introduce new logic in this step.
+```
+
+---
+
+## Schritt 6 — Mit einer klaren Nachricht committen
+
+Die Refactor-Commits so strukturieren, dass sie eine klare Geschichte erzählen:
+
+```
+refactor: extract payment processing into PaymentService
+
+Moves payment logic out of OrderController into a dedicated service.
+No behavior change — all existing tests pass.
+Motivation: OrderController was 600 lines; this makes both units testable in isolation.
+```
+
+Einen Refactor-Commit niemals mit einem Feature- oder Bugfix-Commit mischen. Getrennt halten.
+
+---
+
+## Refactoring-Anti-Muster
+
+- **"Wo ich schon dabei bin..."** — gleichzeitig refactoren und ein Feature hinzufügen. Aufhören. Erst den Refactor fertigstellen.
+- **Refactoren ohne Tests** — etwas wird gebrochen und es wird nicht bemerkt
+- **Big-Bang-Refactor** — alles auf einmal ändern. Inkrementell vorgehen.
+- **Umbenennen als letzten Schritt** — zuerst umbenennen (mechanisch, geringes Risiko), dann umstrukturieren
+- **Die Baseline überspringen** — annehmen, dass Tests ausreichend sind, ohne es zu prüfen
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. [uitbreiden.com](https://uitbreiden.com/)