Reformix — CLAUDE.md

Punto de entrada para cualquier agente IA (Claude Code, Cursor, Copilot) o desarrollador humano nuevo en el proyecto. Lee esto antes de tocar nada.

Qué es Reformix

SaaS B2B para reformistas en España. El cliente final del reformista deja sus datos en una landing, sube fotos de su cocina o baño, recibe en menos de 2 minutos una llamada de un agente IA desde un número fijo de su provincia, y al colgar recibe por WhatsApp un render IA del espacio reformado + presupuesto orientativo desglosado con el branding del reformista. El reformista recibe el lead pre-cualificado completo en su panel.

Visión 18 meses: Fase 1 SaaS B2B → Fase 2 marketplace B2C con valorador "Precio Justo".

Documentos canónicos (la fuente de la verdad)

Antes de implementar nada, lee estos en este orden:

specs.md — Requisitos formales (55 RF + 30 RNF en notación EARS, con criterios de aceptación binarios)
copy/COPY-GUIDE.md — TODO el copy del producto. Cero lorem ipsum permitido en ningún sitio
design/design-system.md — Tokens visuales, identidad verbal, componentes
docs/dev-strategy.md — Orden de implementación, pipeline assets, testing, milestones
funnel.md — Diagrama del funnel punta a punta
negocio/ — Modelo de negocio, plan financiero, riesgos, compliance legal
devdocs/plan.md — Plan vivo de implementación
devdocs/progress.md — Estado actual del proyecto (qué está hecho, qué no)
devdocs/decisions.md — Decisiones técnicas tomadas y por qué

Comandos (cuando el código exista)

# Setup (una sola vez)
pnpm install
cp .env.example .env.local   # rellenar las claves
pnpm db:migrate              # migraciones Postgres con Drizzle Kit

# Desarrollo
pnpm dev                     # Next.js dev server en :3000

# Build
pnpm build                   # build de producción
pnpm start                   # corre el build en local

# Testing
pnpm test                    # vitest (unit + integration)
pnpm test:e2e                # Playwright (flujos críticos)
pnpm test:watch              # vitest watch mode

# Quality
pnpm lint                    # ESLint + autofix donde sea posible
pnpm typecheck               # tsc --noEmit
pnpm format                  # Prettier sobre todo

# Database
pnpm db:generate             # genera migration desde schema
pnpm db:migrate              # aplica migrations
pnpm db:studio               # Drizzle Studio (DB GUI)

Si alguno de estos comandos no existe o no funciona, no improvises. Reporta el problema y arregla el setup antes de seguir.

Stack técnico (decidido, no cuestionar sin evidencia)

Capa	Servicio	Por qué
Framework	Next.js 14 (App Router + Server Actions + API Routes)	Un único proyecto y deploy
Lenguaje	TypeScript strict
UI	Tailwind + shadcn/ui
Tokens visuales	`design/design-tokens.css` + `design/tailwind.config.ext.js`
Tipografías	Instrument Serif (display) + Inter (body) + JetBrains Mono	Via `next/font/google`
Agente de voz	Retell.ai + ElevenLabs (voces premium ES)
Telefonía	Zadarma (números fijos provinciales España)
WhatsApp	Evolution API (primario) o WhatsApp Business API (respaldo)
Render IA	Nano Banana 2 / Image 2 (Google Gemini) + Replicate SDXL fallback
IA texto + vision	GPT-4o (OpenAI)
DB	Postgres + Drizzle ORM
Storage	S3 (Cloudflare R2 recomendado)
Email	SMTP (genérico)
Deploy	Vercel
Analytics	PostHog
Forms	react-hook-form + zod
Testing	Vitest (unit + integration) + Playwright (e2e)

Convenciones de código

TypeScript strict. Sin any salvo en límites con SDK externos sin tipos.
Server Components por defecto. Client Components solo cuando hace falta interactividad ('use client').
API Routes en app/api/.../route.ts. Server Actions para mutaciones desde formularios server-rendered.
Naming:
- Componentes: PascalCase (LeadDetailCard)
- Hooks: camelCase con prefijo use (useLeadStatus)
- Funciones: camelCase
- Tipos: PascalCase, sin prefijo I
- Constantes top-level: SCREAMING_SNAKE_CASE
- Archivos componentes: PascalCase.tsx
- Archivos utilidades: kebab-case.ts
Comentarios: solo cuando el porqué no es obvio. Nada de comentarios que describen qué hace el código.
Imports: usar paths absolutos con alias @/ (configurado en tsconfig.json).
Tests: colocados en tests/ espejando app/ y lib/, no junto al código.

Estructura del proyecto

Ver detalle completo en docs/dev-strategy.md §3. Resumen:

reformix/
├── app/             # Next.js App Router (marketing, app, api)
├── lib/             # Server-side (ai, voice, telephony, whatsapp, budget, db, ...)
├── components/      # Componentes React compartidos (ui, marketing, funnel, panel)
├── design/          # Design system (tokens, config)
├── copy/            # Copy guide
├── docs/            # Documentación técnica
├── devdocs/         # Plan vivo + progreso + decisiones
├── negocio/         # Documentación de negocio
├── public/          # Assets estáticos
├── raw/             # Assets fuente (git-ignored)
└── tests/           # Unit + integration + e2e

Reglas operativas para el agente IA

Siempre

Lee el documento canónico relevante antes de implementar. Si vas a tocar el form B2C, lee §RF-B en specs.md y §"Landing B2C" en COPY-GUIDE.md.
Usa copy de COPY-GUIDE.md literal. No reescribas. Si necesitas un texto que no existe, añádelo primero al copy guide, luego úsalo.
Usa tokens del design system. No hardcodees colores, espaciados o tipografías. Si falta un token, propón añadirlo en design-system.md primero.
Tests primero (TDD) para el motor de presupuesto, extracción de entidades, parsers críticos.
Salida mínima: evita console.log verboso. Los tests deben fallar con mensajes accionables, pasar en silencio.
Commit frecuente cada milestone (≥ 1/día de trabajo activo). Mensaje en imperativo conciso: Add lead capture form, no added lead form.
Update devdocs/progress.md cada vez que cierres un milestone.

Nunca

No inventes requisitos. Si no está en specs.md, pregunta antes de implementar. Si es una mejora obvia, añádela primero a specs.md y luego implementa.
No metas dependencias nuevas sin justificación documentada. Si añades una librería, justifica en devdocs/decisions.md.
No uses ningún proveedor de IA que no esté en el stack decidido sin abrir una decisión explícita.
No hardcodees secretos. Todo via process.env.* con tipo derivado de zod schema.
No optimices prematuramente. Performance budget en specs.md (FCP < 2s, llamada < 2 min, pipeline < 60s). Si vas dentro de presupuesto, no toques.
No instales paquetes globales ni modifiques config del editor de otros.
No commits con tests rojos (salvo en branch personal con flag --no-verify documentado en el mensaje).

Cuando dudes

Si el specs no es claro → escribe la duda en devdocs/decisions.md como "pending" y pregunta.
Si el copy no encaja → propón nueva versión en COPY-GUIDE.md y pide validación.
Si el design system no cubre un caso → propón añadir token a design-system.md.
Si el plan no contempla algo → updateA devdocs/plan.md y notifica.

Compliance imprescindible (no negociable)

HTTPS forzado siempre.
Consentimiento LSSI-CE separado del RGPD en el form del cliente final (RF-LEG-01).
Aviso de grabación al inicio de la llamada del agente (RF-C-12, RNF-LEG-02).
Consulta Lista Robinson antes de cada llamada saliente (RF-C-03, RNF-LEG-03).
Identificación como IA en la llamada (AI Act, RNF-LEG-05).
Horario permitido lun-vie 9-21, sáb 9-14, no domingos (RNF-LEG-06).
Retención grabaciones máximo 12 meses (RNF-LEG-04).

Cuando el contexto se llene (reset de sesión)

Mata la sesión actual.
Inicia nueva sesión.
Lee CLAUDE.md (este archivo) → devdocs/plan.md → devdocs/progress.md → devdocs/decisions.md.
Lee el documento canónico de la superficie en la que estabas trabajando.
Continúa donde lo dejaste sin perder el hilo.

Contacto / responsables

Área	Owner	Backup
Producto + Coordinación + Voz	Carlos	Simon
Backend + IA + WhatsApp	Simon	Carlos
Motor de presupuesto + Dominio	Goyo	Carlos
UI/UX + Creativos	Antonio	Simon

8.8 KiB Raw Blame History