carlos/reformix-hackaton
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1a1caaf0df3a351cc9293f7fc52f893968447240
reformix-hackaton/CLAUDE.md

12 KiB
Raw Blame History

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".

Estado actual del código (27-may-2026)

La planificación (specs, negocio, copy, design) está completa. El código está empezado pero es mínimo: solo el front de marketing, sin backend ni pipeline IA.

Superficie Estado Dónde
Landing B2C App Next.js 16 en desarrollo (Hero, ReformaSlider, Features, Pricing, ContactForm, Footer) mvp/b2c/
Landing B2B Prototipo estático en un único HTML mvp/b2b/landing_reformix.html
Backend, telefonía, voz, WhatsApp, render IA, motor de presupuesto, panel, DB Sin empezar —

Todo lo descrito más abajo como "stack técnico" es el objetivo de la fase F2. Salvo el front de mvp/b2c, nada de eso existe todavía en el repo. No asumas que un servicio está integrado: compruébalo.

Alcance que construimos ahora

Decisión de equipo (mayo 2026): este sprint cubre F1 + F2 de specs.md y nada más. Todo el trabajo de producto sigue en mvp/b2c.

Sí construimos:

  • Landing B2C (mvp/b2c) — superficie B de specs.
  • Funnel B2C completo end-to-end (mvp/b2c) — superficies C + D: captura del lead → subida de fotos → llamada del agente de voz (Retell/Zadarma) → render IA → presupuesto desglosado → entrega por WhatsApp → panel del reformista. Es la demo del 11-jun-2026.
  • Landing B2B — superficie A, solo la landing, puliendo mvp/b2b/landing_reformix.html. Sin backend de signup/trial funcional por ahora.

Definido en specs.md pero NO se construye ahora:

  • Fase 1.5: configurador multi-tenant real, validación pre-envío del reformista, refinamiento por lenguaje natural, 3 versiones B/M/P, cálculo automático de m².
  • Fase 2 (producto): marketplace B2C, valorador "Precio Justo", sello certificado.
  • Doble nomenclatura (feature B2B post-hackathon).

En el MVP el reformista es "Reformas Ejemplo" hardcoded (multi-tenant real va a F1.5). Si un requisito de specs.md está marcado F1.5 o Fase 2, no lo implementes sin abrir la conversación.

Documentos canónicos (la fuente de la verdad)

Antes de implementar nada, lee estos en este orden:

  1. specs.md — Requisitos formales (55 RF + 30 RNF en notación EARS, con criterios de aceptación binarios)
  2. copy/COPY-GUIDE.md — TODO el copy del producto. Cero lorem ipsum permitido en ningún sitio
  3. design/design-system.md — Tokens visuales, identidad verbal, componentes
  4. docs/funnel.md — Diagrama del funnel punta a punta
  5. negocio/ — Modelo de negocio, plan financiero, riesgos, compliance legal
  6. docs/ — Investigación de competencia, insights de entrevistas, ideas iniciales

Comandos

Hoy (landing B2C — mvp/b2c/)

Lo único que funciona ahora mismo. Usa npm (hay package-lock.json), no pnpm.

cd mvp/b2c
npm install        # instala dependencias
npm run dev        # Next.js dev server en :3000
npm run build      # build de producción
npm run start      # corre el build
npm run lint       # ESLint

Objetivo (cuando exista el backend de la fase F2)

Aún no funcionan. Es el set previsto cuando se monte el backend (Drizzle, Vitest, Playwright). No los ejecutes esperando que existan.

pnpm install
cp .env.example .env.local   # rellenar las claves
pnpm db:migrate              # migraciones Postgres con Drizzle Kit
pnpm dev                     # dev server
pnpm build / pnpm start      # build de producción / correrla
pnpm test / pnpm test:e2e    # Vitest (unit+integration) / Playwright (e2e)
pnpm lint / pnpm typecheck / pnpm format
pnpm db:generate / pnpm db:migrate / pnpm db:studio

Si un comando 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 (App Router + Server Actions + API Routes) Un único proyecto y deploy. El front actual de mvp/b2c corre sobre Next.js 16 + React 19
Lenguaje TypeScript strict
UI Tailwind + shadcn/ui (objetivo) Hoy mvp/b2c usa Tailwind v4 (@theme en globals.css) sin shadcn
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)

Implementado hoy: solo Next.js + Tailwind en mvp/b2c. Todo lo demás (Retell, Zadarma, Evolution API, Nano Banana, GPT-4o, Postgres/Drizzle, S3, PostHog, Vitest, Playwright) es objetivo de F2 y aún no está integrado.

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

Layout real del repositorio hoy:

reformix-hackaton/
├── mvp/
│   ├── b2c/                 # App Next.js 16 — landing del cliente final (código activo)
│   │   └── src/
│   │       ├── app/         # App Router: layout.tsx, page.tsx, globals.css
│   │       └── components/  # Un dir por componente: Hero/, ReformaSlider/, Features/, Pricing/, ContactForm/, Footer/, Navbar/
│   └── b2b/                 # landing_reformix.html — prototipo estático de la landing B2B
├── specs.md                 # Requisitos formales (EARS)
├── copy/                    # Copy guide
├── design/                  # Design system (tokens .css/.json, config Tailwind)
├── docs/                    # Funnel, investigación de competencia, insights, ideas
├── negocio/                 # Modelo de negocio, financiero, legal, operaciones, riesgos (+ datos/)
└── README.md / CLAUDE.md

La estructura objetivo del backend F2 (lib/ai, lib/voice, lib/telephony, lib/budget, tests/...) aún no existe. Se creará dentro de mvp/b2c o en un workspace dedicado cuando arranque la fase F2.

Reglas operativas para el agente IA

Siempre

  1. 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.
  2. Usa copy de COPY-GUIDE.md literal. No reescribas. Si necesitas un texto que no existe, añádelo primero al copy guide, luego úsalo.
  3. 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.
  4. Tests primero (TDD) para el motor de presupuesto, extracción de entidades, parsers críticos.
  5. Salida mínima: evita console.log verboso. Los tests deben fallar con mensajes accionables, pasar en silencio.
  6. Commit frecuente cada milestone (≥ 1/día de trabajo activo). Mensaje en imperativo conciso: Add lead capture form, no added lead form.
  7. Documenta el avance al cerrar cada milestone (commit descriptivo + aviso al equipo).

Nunca

  1. 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.
  2. No metas dependencias nuevas sin justificación documentada. Si añades una librería, justifica el porqué en el mensaje de commit (y en specs.md si afecta al stack).
  3. No uses ningún proveedor de IA que no esté en el stack decidido sin abrir una decisión explícita.
  4. No hardcodees secretos. Todo via process.env.* con tipo derivado de zod schema.
  5. No optimices prematuramente. Performance budget en specs.md (FCP < 2s, llamada < 2 min, pipeline < 60s). Si vas dentro de presupuesto, no toques.
  6. No instales paquetes globales ni modifiques config del editor de otros.
  7. 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 → anótalo en specs.md como duda pendiente y pregunta antes de implementar.
  • Si el copy no encaja → propón nueva versión en copy/COPY-GUIDE.md y pide validación.
  • Si el design system no cubre un caso → propón añadir token a design/design-system.md.
  • Si el plan no contempla algo → coméntalo con el equipo y refleja el acuerdo en specs.md.

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)

  1. Mata la sesión actual.
  2. Inicia nueva sesión.
  3. Lee CLAUDE.md (este archivo) → la sección "Estado actual del código" → specs.md.
  4. Lee el documento canónico de la superficie en la que estabas trabajando.
  5. 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
Reference in New Issue View Git Blame Copy Permalink