claudient 0.1.0

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

@@ -0,0 +1,175 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../new-project-bootstrap.md).
+
+# Flujo de Trabajo de Bootstrap de Nuevo Proyecto
+
+Cómo arrancar un nuevo proyecto con Claude Code — estructurado, con opinión y listo para construir desde el primer día.
+
+---
+
+## Cuándo usar este flujo de trabajo
+- Comenzar una nueva aplicación desde cero
+- Configurar un nuevo servicio en un sistema existente
+- Crear un nuevo repositorio para un proyecto personal o un encargo de cliente
+
+---
+
+## Paso 1 — Define qué estás construyendo
+
+Antes de tocar cualquier código o configuración, responde estas preguntas claramente.
+
+**Prompt para Claude:**
+```
+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.
+```
+
+No procedas hasta que el alcance esté confirmado por escrito.
+
+---
+
+## Paso 2 — Elige el stack
+
+**Prompt para Claude:**
+```
+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.
+```
+
+Bloquea el stack antes de escribir cualquier código. Registra las decisiones en `docs/adr/` si no son obvias.
+
+---
+
+## Paso 3 — Bootstrap de la estructura del proyecto
+
+**Prompt para Claude:**
+```
+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.
+```
+
+Verifica que funcione antes de continuar.
+
+---
+
+## Paso 4 — Configura CLAUDE.md
+
+**Prompt para Claude:**
+```
+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.
+```
+
+---
+
+## Paso 5 — Configura el entorno de desarrollo
+
+**Prompt para Claude:**
+```
+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)
+```
+
+---
+
+## Paso 6 — Configura el CI
+
+**Prompt para Claude:**
+```
+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.
+```
+
+Verifica que el CI pase en el commit inicial antes de avanzar al desarrollo de funcionalidades.
+
+---
+
+## Paso 7 — Planificación de la primera funcionalidad
+
+Una vez que el esqueleto está funcionando y el CI está en verde:
+
+**Prompt para Claude:**
+```
+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.
+```
+
+Ver `workflows/feature-development.md`.
+
+---
+
+## Lista de verificación del bootstrap
+
+- [ ] Alcance definido y confirmado por escrito
+- [ ] Stack decidido con razonamiento documentado
+- [ ] Estructura del proyecto creada y funcionando ("hello world" funciona)
+- [ ] CLAUDE.md escrito y con commit
+- [ ] Docker Compose / dependencias locales funcionando
+- [ ] .env.example con commit con todas las variables requeridas
+- [ ] Pruebas configuradas y al menos una pasando
+- [ ] Pipeline de CI en verde en el primer push
+- [ ] `docs/adr/` creado con las decisiones arquitectónicas iniciales
+
+---
+
+> **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/refactor-safely.md

@@ -0,0 +1,150 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../refactor-safely.md).
+
+# Flujo de Trabajo de Refactoring Seguro
+
+Cómo refactorizar código con Claude Code sin romper el comportamiento — usando las pruebas como red de seguridad en todo momento.
+
+---
+
+## Cuándo usar este flujo de trabajo
+- Extraer funciones de un método grande
+- Renombrar y reorganizar módulos
+- Reemplazar un patrón con uno mejor en múltiples archivos
+- Reducir la duplicación en el codebase
+- Mejorar la estructura de un módulo sin cambiar su comportamiento externo
+
+---
+
+## La regla de oro
+
+**Nunca refactorices y cambies el comportamiento en el mismo commit.** Un refactoring preserva el comportamiento externo. Si las pruebas fallan, o cambiaste el comportamiento o las pruebas estaban probando detalles de implementación (también es un problema).
+
+---
+
+## Paso 1 — Establece una línea base de pruebas
+
+Antes de cambiar cualquier cosa, confirma que tienes cobertura de pruebas adecuada.
+
+**Prompt para Claude:**
+```
+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.
+```
+
+**Haz commit de las adiciones de pruebas antes de refactorizar.** Esto deja claro qué pruebas existían antes vs. las que se agregaron como parte del refactoring.
+
+---
+
+## Paso 2 — Define el alcance del refactoring
+
+**Prompt para Claude:**
+```
+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.
+```
+
+---
+
+## Paso 3 — Refactoriza en incrementos pequeños y verificables
+
+Divide el refactoring en pasos lo suficientemente pequeños como para que las pruebas puedan verificar cada uno.
+
+**Para cada incremento:**
+```
+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
+```
+
+**Después de cada incremento:**
+```bash
+# Ejecuta las pruebas — deben estar en verde antes del siguiente paso
+npm test  # o pytest, go test, etc.
+```
+
+Si las pruebas fallan después de un cambio puramente estructural: detente, entiende por qué, corrige antes de continuar. Una prueba que falla después de un refactoring significa que o el refactoring cambió el comportamiento o la prueba estaba probando la implementación (ambos son problemas a corregir ahora).
+
+---
+
+## Paso 4 — Verifica que el comportamiento externo no cambió
+
+Después de todos los incrementos:
+
+**Prompt para Claude:**
+```
+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.
+```
+
+---
+
+## Paso 5 — Limpieza
+
+**Prompt para Claude:**
+```
+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.
+```
+
+---
+
+## Paso 6 — Commit con un mensaje claro
+
+Estructura los commits del refactoring para contar una historia clara:
+
+```
+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.
+```
+
+Nunca mezcles un commit de refactoring con un commit de funcionalidad o corrección de bug. Mantenlos separados.
+
+---
+
+## Anti-patrones de refactoring
+
+- **"Ya que estoy aquí..."** — hacer un refactoring y una funcionalidad al mismo tiempo. Detente. Termina el refactoring primero.
+- **Refactorizar sin pruebas** — romperás algo y no lo sabrás
+- **Refactoring big-bang** — cambiar todo a la vez. Hazlo de forma incremental.
+- **Renombrar como último paso** — renombra primero (mecánico, bajo riesgo), luego reestructura
+- **Saltarse la línea base** — asumir que las pruebas son adecuadas sin verificar primero
+
+---
+
+> **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/feature-development.md

@@ -0,0 +1,153 @@
+# Feature Development Workflow
+
+End-to-end workflow for taking a feature from idea to merged PR using Claude Code.
+
+---
+
+## When to use this workflow
+- Building a new feature that touches more than one file
+- Implementing a spec or ticket that needs breaking down before coding
+- Any feature where you want a structured, reviewable process
+
+---
+
+## Step 1 — Define and validate scope
+
+Before writing code, establish exactly what you're building.
+
+**Prompt 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.
+```
+
+**What to look for in the response:**
+- Files you hadn't considered
+- Edge cases that would cause bugs if missed
+- Decisions that should go in CLAUDE.md once made
+
+---
+
+## Step 2 — Plan the implementation
+
+Once scope is clear, get a sequenced plan.
+
+**Prompt 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.
+```
+
+Review the plan. If a step is too large, ask Claude to break it down further. Lock in the plan before touching code.
+
+---
+
+## Step 3 — Implement step by step
+
+Execute one plan step at a time. Do not skip ahead.
+
+**For each step:**
+```
+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
+```
+
+**After each step:**
+- Run tests: confirm green before moving to the next step
+- Review the diff yourself: is this what you intended?
+- If a step reveals new complexity, update the plan before continuing
+
+---
+
+## Step 4 — Integration check
+
+Once all steps are complete, verify the full feature works end-to-end.
+
+**Prompt 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]
+```
+
+Fix any issues found before proceeding.
+
+---
+
+## Step 5 — Self-review
+
+Before creating a PR, review your own changes.
+
+**Prompt 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
+```
+
+Fix all CRITICAL issues. Use judgment on SUGGESTED items.
+
+---
+
+## Step 6 — PR description
+
+**Prompt 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.
+```
+
+---
+
+## Checklist before merging
+
+- [ ] All tests pass
+- [ ] Self-review complete, no CRITICAL issues
+- [ ] Edge cases from Step 1 are all handled
+- [ ] PR description written
+- [ ] CLAUDE.md updated if any new decisions were made
+- [ ] CONTEXT.md updated if new domain terms were introduced
+
+---
+
+> **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/fr/code-review.md

@@ -0,0 +1,153 @@
+> 🇫🇷 This is the French translation. [English version](../code-review.md).
+
+# Workflow de Révision de Code
+
+Comment exécuter une révision de code structurée et automatisée avec Claude Code avant ou en parallèle de la révision humaine.
+
+---
+
+## Quand utiliser ce workflow
+- Auto-réviser vos propres changements avant de pousser
+- Pré-screening d'une PR avant de demander une révision humaine
+- Réviser du code généré par l'IA avant de l'accepter
+- Révision d'intégration : comprendre ce qui a changé dans une PR inconnue
+
+---
+
+## Étape 1 — Préparer le contexte
+
+Donnez à Claude tout ce dont il a besoin pour réviser de manière significative.
+
+**Prompt 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]
+```
+
+---
+
+## Étape 2 — Révision de correction
+
+**Prompt 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.
+```
+
+---
+
+## Étape 3 — Révision de sécurité
+
+**Prompt 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]
+```
+
+---
+
+## Étape 4 — Vérification de la couverture de test
+
+**Prompt 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]
+```
+
+---
+
+## Étape 5 — Révision de maintenabilité
+
+**Prompt 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.
+```
+
+---
+
+## Étape 6 — Consolider les résultats
+
+**Prompt 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
+```
+
+---
+
+## Utiliser l'agent Réviseur de Code
+
+Pour les PRs plus grandes, déléguer à l'agent Réviseur de Code plutôt que de l'exécuter en ligne :
+
+```
+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.
+```
+
+Voir `agents/core/code-reviewer.md` pour la définition complète de l'agent.
+
+---
+
+> **Travaillez avec nous :** Claudient est soutenu par [Uitbreiden](https://uitbreiden.com/) — nous construisons des produits IA et des solutions B2B avec des communautés de développeurs. [uitbreiden.com](https://uitbreiden.com/)