claudient 0.1.0

package/workflows/debugging-session.md

@@ -0,0 +1,144 @@
+# Debugging Session Workflow
+
+Systematic workflow for diagnosing and fixing bugs with Claude Code — without chasing symptoms.
+
+---
+
+## When to use this workflow
+- A bug that isn't immediately obvious from reading the code
+- A failing test where the cause isn't clear
+- Production error you can't reproduce locally
+- Intermittent failures
+
+---
+
+## Step 1 — Build a feedback loop first
+
+Before investigating, create a way to reliably reproduce the bug. Do not skip this.
+
+**Prompt Claude:**
+```
+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.
+```
+
+**Do not proceed until you have a reliable reproduction.** Debugging without a reproduction is guessing.
+
+---
+
+## Step 2 — Isolate the blast radius
+
+Understand where the bug can possibly live before reading any code.
+
+**Prompt Claude:**
+```
+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.
+```
+
+---
+
+## Step 3 — Generate hypotheses
+
+**Prompt Claude:**
+```
+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.
+```
+
+Review the hypotheses. Add any you thought of that Claude missed. Rank them by probability.
+
+---
+
+## Step 4 — Test hypotheses, highest probability first
+
+**For each hypothesis:**
+```
+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.
+```
+
+After each test:
+- If confirmed: move to Step 5
+- If ruled out: move to the next hypothesis
+- If inconclusive: refine the hypothesis and re-test
+
+---
+
+## Step 5 — Fix and verify
+
+Once the root cause is confirmed:
+
+**Prompt Claude:**
+```
+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.
+```
+
+---
+
+## Step 6 — Post-mortem (for serious bugs)
+
+For bugs that caused user impact, data loss, or took more than 2 hours to find:
+
+**Prompt Claude:**
+```
+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.
+```
+
+---
+
+## Anti-patterns to avoid
+
+- **Fixing the symptom, not the cause** — if you don't understand why, you haven't fixed it
+- **Changing multiple things at once** — you won't know which change fixed it
+- **Debugging without a reproduction** — you're guessing
+- **Adding instrumentation everywhere** — target specific hypotheses
+- **Skipping the regression test** — the bug will come back
+
+---
+
+> **Work with us:** Claudient is backed by [Uitbreiden](https://uitbreiden.com/) — we build AI products and B2B solutions with developer communities. [uitbreiden.com](https://uitbreiden.com/)

package/workflows/es/code-review.md

@@ -0,0 +1,153 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../code-review.md).
+
+# Flujo de Trabajo de Revisión de Código
+
+Cómo ejecutar una revisión de código estructurada y automatizada usando Claude Code antes o junto con la revisión humana.
+
+---
+
+## Cuándo usar este flujo de trabajo
+- Auto-revisión de tus propios cambios antes de hacer push
+- Pre-filtrado de un PR antes de solicitar revisión humana
+- Revisión de código generado por IA antes de aceptarlo
+- Revisión de incorporación: entender qué cambió en un PR desconocido
+
+---
+
+## Paso 1 — Preparar el contexto
+
+Dale a Claude todo lo que necesita para revisar de forma significativa.
+
+**Prompt para Claude:**
+```
+I need you to review the following changes.
+
+Project context:
+- Stack: [language, framework, key libraries]
+- Testing approach: [unit/integration, mocking policy]
+- Key conventions: [paste relevant CLAUDE.md sections]
+
+Changed files:
+[paste git diff output OR list files and ask Claude to read them]
+
+This PR: [one sentence on what it's supposed to do]
+```
+
+---
+
+## Paso 2 — Revisión de corrección
+
+**Prompt para Claude:**
+```
+Review these changes for correctness only.
+
+Check:
+1. Does the code do what the PR description says it does?
+2. Are there edge cases not handled? (null inputs, empty collections, concurrent access, large inputs)
+3. Are there off-by-one errors, wrong comparisons, or logic inversions?
+4. Are error paths handled — can this panic, throw, or silently fail?
+5. Are there race conditions if this code runs concurrently?
+
+Format: [FILE:LINE] — [issue description] — [suggested fix]
+Only report real issues. Do not nitpick style.
+```
+
+---
+
+## Paso 3 — Revisión de seguridad
+
+**Prompt para Claude:**
+```
+Review these changes for security issues.
+
+Check:
+1. Is any user input used in SQL, shell commands, file paths, or HTML without sanitization?
+2. Are there missing authentication or authorization checks?
+3. Are secrets, tokens, or credentials exposed in logs, errors, or responses?
+4. Are there insecure direct object references (IDOR)?
+5. Are there missing rate limits on sensitive endpoints?
+
+Severity: CRITICAL / HIGH / MEDIUM / LOW
+Format: [SEVERITY] [FILE:LINE] — [vulnerability] — [fix]
+```
+
+---
+
+## Paso 4 — Verificación de cobertura de pruebas
+
+**Prompt para Claude:**
+```
+Review the test coverage for these changes.
+
+Check:
+1. Is every new function or method covered by at least one test?
+2. Is the happy path tested?
+3. Is at least one error/edge case tested?
+4. Do the tests actually assert meaningful behavior, or just that the function runs?
+5. Are there behaviors changed by this PR that existing tests don't cover?
+
+List: [what is tested] and [what is missing]
+```
+
+---
+
+## Paso 5 — Revisión de mantenibilidad
+
+**Prompt para Claude:**
+```
+Review these changes for maintainability.
+
+Check:
+1. Will a developer unfamiliar with this code understand it in 6 months?
+2. Are function names and variable names clear and accurate?
+3. Is there duplicated logic that should be extracted?
+4. Are there magic numbers or strings that should be named constants?
+5. Does this introduce unnecessary coupling between modules?
+
+Only flag real maintainability issues — not style preferences.
+```
+
+---
+
+## Paso 6 — Consolidar hallazgos
+
+**Prompt para Claude:**
+```
+Consolidate all findings from the review into a final report.
+
+Format:
+## CRITICAL (must fix before merge)
+[list]
+
+## HIGH (strongly recommended)
+[list]
+
+## SUGGESTED (worth doing)
+[list]
+
+## NITPICK (optional)
+[list]
+
+## VERDICT
+[ ] Approved — no blockers
+[ ] Approved with suggestions — merge after addressing CRITICAL
+[ ] Changes requested — must address before merge
+```
+
+---
+
+## Usar el agente Revisor de Código
+
+Para PRs más grandes, delega al agente Revisor de Código en lugar de ejecutarlo de forma inline:
+
+```
+Spawn a Code Reviewer agent (Sonnet 4.6) to review [list of files].
+Give it the project context from CLAUDE.md and the PR description.
+Have it return a structured CRITICAL/SUGGESTED/NITPICK report.
+```
+
+Ver `agents/core/code-reviewer.md` para la definición completa del agente.
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. [uitbreiden.com](https://uitbreiden.com/)

package/workflows/es/debugging-session.md

@@ -0,0 +1,146 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../debugging-session.md).
+
+# Flujo de Trabajo de Sesión de Depuración
+
+Flujo de trabajo sistemático para diagnosticar y corregir bugs con Claude Code — sin perseguir síntomas.
+
+---
+
+## Cuándo usar este flujo de trabajo
+- Un bug que no es inmediatamente obvio al leer el código
+- Una prueba fallida donde la causa no está clara
+- Error de producción que no puedes reproducir localmente
+- Fallos intermitentes
+
+---
+
+## Paso 1 — Construye un ciclo de retroalimentación primero
+
+Antes de investigar, crea una forma de reproducir el bug de forma fiable. No te saltes esto.
+
+**Prompt para Claude:**
+```
+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.
+```
+
+**No procedas hasta tener una reproducción fiable.** Depurar sin una reproducción es adivinar.
+
+---
+
+## Paso 2 — Aísla el radio de explosión
+
+Entiende dónde puede estar el bug antes de leer cualquier código.
+
+**Prompt para Claude:**
+```
+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.
+```
+
+---
+
+## Paso 3 — Genera hipótesis
+
+**Prompt para Claude:**
+```
+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.
+```
+
+Revisa las hipótesis. Agrega cualquiera que hayas pensado y que Claude haya omitido. Ordénalas por probabilidad.
+
+---
+
+## Paso 4 — Prueba las hipótesis, empezando por la de mayor probabilidad
+
+**Para cada hipótesis:**
+```
+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.
+```
+
+Después de cada prueba:
+- Si se confirma: pasa al Paso 5
+- Si se descarta: pasa a la siguiente hipótesis
+- Si es inconclusa: refina la hipótesis y vuelve a probar
+
+---
+
+## Paso 5 — Corrige y verifica
+
+Una vez confirmada la causa raíz:
+
+**Prompt para Claude:**
+```
+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.
+```
+
+---
+
+## Paso 6 — Post-mortem (para bugs graves)
+
+Para bugs que causaron impacto en usuarios, pérdida de datos, o tardaron más de 2 horas en encontrarse:
+
+**Prompt para Claude:**
+```
+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.
+```
+
+---
+
+## Anti-patrones a evitar
+
+- **Corregir el síntoma, no la causa** — si no entiendes el por qué, no lo has corregido
+- **Cambiar múltiples cosas a la vez** — no sabrás qué cambio lo corrigió
+- **Depurar sin una reproducción** — estás adivinando
+- **Agregar instrumentación en todas partes** — apunta a hipótesis específicas
+- **Saltarse la prueba de regresión** — el bug volverá
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. [uitbreiden.com](https://uitbreiden.com/)

package/workflows/es/feature-development.md

@@ -0,0 +1,155 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../feature-development.md).
+
+# Flujo de Trabajo de Desarrollo de Funcionalidades
+
+Flujo de trabajo de extremo a extremo para llevar una funcionalidad desde la idea hasta el PR fusionado usando Claude Code.
+
+---
+
+## Cuándo usar este flujo de trabajo
+- Construir una nueva funcionalidad que toca más de un archivo
+- Implementar una especificación o ticket que necesita ser desglosado antes de codificar
+- Cualquier funcionalidad donde quieras un proceso estructurado y revisable
+
+---
+
+## Paso 1 — Definir y validar el alcance
+
+Antes de escribir código, establece exactamente qué estás construyendo.
+
+**Prompt para Claude:**
+```
+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.
+```
+
+**Qué buscar en la respuesta:**
+- Archivos que no habías considerado
+- Casos límite que causarían bugs si se pasan por alto
+- Decisiones que deberían ir en CLAUDE.md una vez tomadas
+
+---
+
+## Paso 2 — Planificar la implementación
+
+Una vez que el alcance es claro, obtén un plan secuenciado.
+
+**Prompt para Claude:**
+```
+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.
+```
+
+Revisa el plan. Si un paso es demasiado grande, pide a Claude que lo desglose más. Bloquea el plan antes de tocar el código.
+
+---
+
+## Paso 3 — Implementar paso a paso
+
+Ejecuta un paso del plan a la vez. No te saltes pasos.
+
+**Para cada paso:**
+```
+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
+```
+
+**Después de cada paso:**
+- Ejecuta las pruebas: confirma que están en verde antes de pasar al siguiente paso
+- Revisa el diff tú mismo: ¿es esto lo que pretendías?
+- Si un paso revela nueva complejidad, actualiza el plan antes de continuar
+
+---
+
+## Paso 4 — Verificación de integración
+
+Una vez que todos los pasos estén completos, verifica que la funcionalidad completa funcione de extremo a extremo.
+
+**Prompt para Claude:**
+```
+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]
+```
+
+Soluciona cualquier problema encontrado antes de continuar.
+
+---
+
+## Paso 5 — Auto-revisión
+
+Antes de crear un PR, revisa tus propios cambios.
+
+**Prompt para Claude:**
+```
+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
+```
+
+Corrige todos los problemas CRITICAL. Usa el juicio en los elementos SUGGESTED.
+
+---
+
+## Paso 6 — Descripción del PR
+
+**Prompt para Claude:**
+```
+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.
+```
+
+---
+
+## Lista de verificación antes de hacer merge
+
+- [ ] Todas las pruebas pasan
+- [ ] Auto-revisión completa, sin problemas CRITICAL
+- [ ] Todos los casos límite del Paso 1 están manejados
+- [ ] Descripción del PR escrita
+- [ ] CLAUDE.md actualizado si se tomaron nuevas decisiones
+- [ ] CONTEXT.md actualizado si se introdujeron nuevos términos del dominio
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. [uitbreiden.com](https://uitbreiden.com/)