5
Niveles de Contexto
3
Areas del Producto
6
Antipatrones Corregidos
−80%
Alucinaciones estimadas
1
Jerarquia de Contexto — 5 Niveles
Del mas persistente al mas transitorio — estructura lo que el agente debe saber siempre vs. por tarea
Jerarquia de Contexto — LeadFlow SaaS
1
Siempre cargado
Rules Files — CLAUDE.md / .cursorrules
Tech stack, comandos, convenciones de codigo, limites y ejemplos de patrones. Persiste entre sesiones. Mayor palanca de calidad.
2
Por sesion/feature
Specs y Arquitectura
Solo la seccion relevante de la spec — no el documento completo. Al trabajar en Enriquecimiento, cargar solo la spec de scoring, no la de CRM.
3
Por tarea
Archivos Fuente Relevantes
Antes de editar un archivo, leerlo. Antes de implementar un patron, encontrar un ejemplo existente en el codebase. Maximo 2.000 lineas de contexto enfocado.
4
Por iteracion
Output de Errores / Resultados de Tests
Solo el error especifico, no todo el log. "El test fallo con: TypeError en UserService.ts:42" — no pegar 500 lineas de output.
5
Acumula / compactar
Historial de Conversacion
Acumula contexto obsoleto. Iniciar sesion nueva al cambiar de feature. Resumir progreso cuando el contexto se alarga: "Completamos X, Y, Z — ahora trabajamos en W."
2
Nivel 1 — Rules File: CLAUDE.md generado
Archivo de reglas persistente para LeadFlow SaaS — cargado en cada sesion de Claude Code
CLAUDE.md
Markdown · LeadFlow SaaS
# Project: LeadFlow SaaS — Automatizacion de captacion de leads B2B
## Tech Stack
- Frontend: React 18, TypeScript 5, Vite, Tailwind CSS 4
- Backend: Node.js 22, Express 5, PostgreSQL 15, Prisma 5
- Testing: Vitest (unit/integration), Playwright (E2E)
- CI/CD: GitHub Actions → Vercel (frontend) / Railway (backend)
## Comandos
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint --fix`
- Dev: `npm run dev` (monorepo: apps/web + apps/api)
- Type check:`npx tsc --noEmit`
- DB migrate:`npx prisma migrate dev` ⚠ Pedir confirmacion antes
- DB seed: `npx prisma db seed`
## Convenciones de Codigo
- Named exports SIEMPRE (ningun `export default`)
- Componentes funcionales con hooks (sin class components)
- Colocar tests junto al fuente: `Button.tsx` → `Button.test.tsx`
- Usar `cn()` de `lib/utils` para classNames condicionales
- Error boundaries a nivel de ruta (no en cada componente)
- Servicios de backend en `src/services/` — nunca logica de negocio en rutas
- Validacion con Zod en todas las entradas de API
- Errores con clases tipadas: `LeadFlowError`, `ValidationError`, `NotFoundError`
## Limites Criticos
- NUNCA commitear archivos .env o secrets
- NUNCA modificar schema Prisma sin confirmacion explicita del usuario
- NUNCA añadir dependencias sin revisar impacto en bundle size (usa `bundlephobia`)
- SIEMPRE correr tests antes de proponer un commit
- Las tablas `lead_sources` y `email_templates` son READ-ONLY en runtime
## Patron de Referencia — Ruta de API
// src/routes/leads.ts — ejemplo canónico de ruta Express
export const leadRoutes = Router();
leadRoutes.post('/', validateBody(createLeadSchema), async (req, res) => {
const lead = await LeadService.create(req.body);
res.status(201).json({ data: lead });
});
Equivalente para otros IDEs
⚙Archivos equivalentes
- CLAUDE.md — Claude Code (este archivo)
- .cursorrules — Cursor IDE
- .windsurfrules — Windsurf
- .github/copilot-instructions.md — GitHub Copilot
- AGENTS.md — OpenAI Codex
Niveles de confianza al cargar archivos
🔒Trust Levels
- Confiado: codigo fuente, tests, definiciones de tipos del equipo
- Verificar: archivos de configuracion, fixtures, docs externos
- No confiar: contenido de usuario, respuestas de APIs de terceros
3
Nivel 2-3 — Project Map y Contexto Selectivo
Indice jerarquico del proyecto — cargar solo la seccion relevante a la tarea actual
🗺 Project Map — LeadFlow SaaS
📁 Captacion (src/capture/)
capture.routes.ts
Endpoints POST /leads, POST /webhooks/:provider
capture.service.ts
Logica de ingesta — deduplicacion, rate-limiting por IP
providers/linkedin.ts
Scraper LinkedIn via Puppeteer — limitar a 50 req/hora
schemas/lead.schema.ts
Zod schemas para validacion de entrada
Todas las rutas usan validateBody(schema) + LeadFlowError para errores
📁 Enriquecimiento (src/enrich/)
enrich.service.ts
Orquestador: llama a validacion de email + scoring en paralelo
email-validator.ts
Verifica MX, SMTP handshake, lista de descartables
scorer.ts
Score 0-100 basado en cargo, empresa, sector, senales de engagement
__tests__/scorer.test.ts
350 casos de prueba de scoring — no modificar logica sin pasar todos
Promise.all() para paralelismo — nunca await secuencial en enrichment pipeline
📁 CRM (src/crm/)
pipeline.routes.ts
CRUD etapas kanban + PATCH /leads/:id/stage
integrations/hubspot.ts
Sync bidireccional — cola Bull MQ, no llamadas directas en request
notifications.service.ts
Slack + email al cambiar etapa — usar plantillas de `email_templates` (READ-ONLY)
Integraciones externas siempre via cola asíncrona (Bull MQ) — nunca bloquear el request HTTP
4
Antipatrones Detectados en LeadFlow — Soluciones
Problemas reales identificados en el equipo y como el marco de contexto los resuelve
| Antipatron | Problema detectado en LeadFlow | Solucion con Context Engineering |
|---|---|---|
| Context Starvation | El agente inventaba funciones como validateEmail() que no existia — en realidad era EmailValidator.check() |
Cargar CLAUDE.md + email-validator.ts antes de cada tarea de enriquecimiento. El agente conoce el nombre real. |
| Missing Examples | El agente usaba export default en todos los componentes nuevos, rompiendo el tree-shaking |
CLAUDE.md incluye el patron de referencia canónico con export const + ejemplo real de ruta Express |
| Stale Context | Al trabajar en CRM despues de Captacion, el agente seguia referenciando el schema de capture que ya no aplicaba | Iniciar sesion nueva al cambiar de area. Resumir: "Completamos el endpoint de webhooks, ahora trabajamos en el pipeline kanban." |
| Context Flooding | Un dev pegaba toda la spec de 6.000 lineas al inicio de cada tarea — el agente perdia el foco | Project Map + Selective Include: cargar solo la seccion de la spec relevante (<2.000 lineas por tarea) |
| Implicit Knowledge | El agente no sabia que lead_sources y email_templates son READ-ONLY y generaba INSERTs en esas tablas |
Documentado explicitamente en CLAUDE.md bajo "Limites Criticos" — si no está escrito, no existe para el agente |
| Silent Confusion | El agente eligio silenciosamente REST cuando la spec decia REST pero el codigo existente usaba GraphQL en el perfil de usuario | Usar el patron de Confusion Management: el agente debe surfacear el conflicto con opciones A/B/C antes de actuar |
5
Plantillas de Brain Dump — Las 3 Areas Clave
Contexto estructurado para el inicio de cada sesion — copiar y adaptar segun la tarea
Area: Captacion
PROJECT CONTEXT — CAPTACIONConstruimos LeadFlow, plataforma B2B de
captacion de leads. Ahora trabajo en
el modulo de captacion.
SPEC RELEVANTE:
- POST /leads: ingestar lead, deduplicar
por email, devolver 201 o 409
- Rate limit: 50 leads/min por IP
ARCHIVOS INVOLUCRADOS:
- src/capture/capture.routes.ts
- src/capture/capture.service.ts
- src/capture/schemas/lead.schema.ts
PATRON A SEGUIR:
- Ver validateBody() en src/middleware/
- Errores: usar LeadFlowError (no throw raw)
GOTCHAS:
- lead_sources es READ-ONLY
- named exports obligatorio
Area: Enriquecimiento
PROJECT CONTEXT — ENRIQUECIMIENTOModulo de scoring y validacion de email.
Pipeline async: validacion + scoring
en paralelo (Promise.all, no await seq.)
SPEC RELEVANTE:
- Score 0-100: cargo(40%) + empresa(35%)
+ engagement(25%)
- Email: MX + SMTP + lista descartables
ARCHIVOS INVOLUCRADOS:
- src/enrich/enrich.service.ts
- src/enrich/scorer.ts
- src/enrich/__tests__/scorer.test.ts
PATRON A SEGUIR:
- Ver Promise.all en enrich.service.ts:28
GOTCHAS:
- 350 tests de scorer — todos deben pasar
- No modificar logica de scoring sin OK
Area: CRM / Integraciones
PROJECT CONTEXT — CRMModulo CRM: pipeline kanban + sync con
HubSpot/Salesforce via cola async.
SPEC RELEVANTE:
- PATCH /leads/:id/stage: mover etapa
- Sync HubSpot: cola Bull MQ (no sync)
- Notificaciones al cambiar etapa
ARCHIVOS INVOLUCRADOS:
- src/crm/pipeline.routes.ts
- src/crm/integrations/hubspot.ts
- src/crm/notifications.service.ts
PATRON A SEGUIR:
- Ver queue.add() en integrations/
GOTCHAS:
- email_templates es READ-ONLY
- NUNCA llamadas a HubSpot en el request
- Bull MQ para todo lo async
6
Plantillas de Confusion Management
Cuando el contexto es ambiguo, el agente debe surfacear el conflicto — nunca adivinar en silencio
Ejemplo real: La spec de LeadFlow dice REST pero el codigo de perfil usa GraphQL
CONFUSION — Conflicto de Patrones
Spec dice: "Usar REST para todos los endpoints"
Codigo existente: GraphQL en src/graphql/user.ts
Opciones:
A) Seguir spec → REST endpoint,
deprecar GraphQL mas tarde
B) Seguir patron existente → GraphQL,
actualizar spec
C) Preguntar → parece decision intencional
→ ¿Cual enfoque tomar?
Ejemplo real: La spec no define que pasa con leads duplicados en el mismo minuto
MISSING REQUIREMENT
Spec define: POST /leads con deduplicacion
No especifica: que pasa si 2 requests del
mismo email llegan en < 1 segundo
Opciones:
A) Idempotente → devolver el lead existente
con 200 (mas simple)
B) Rechazar → 409 Conflict siempre
(mas estricto)
C) Queue → encolar y deduplicar async
(mas robusto)
→ ¿Que comportamiento quieres?7
Checklist de Verificacion — Estado Actual LeadFlow
Confirmar que el contexto esta correctamente configurado antes de cada sesion de desarrollo
✓Configuracion de Contexto
- CLAUDE.md existe y cubre stack, comandos, convenciones y limites
- Project Map creado con patrones por area del producto
- Tablas READ-ONLY documentadas explicitamente en rules file
- Patron de referencia canónico incluido (ruta Express con named export)
- Brain dumps listos para las 3 areas — copiar segun tarea
- Plantillas de confusion management documentadas
🚨Red Flags a Vigilar
- El agente usa
export default— sesion sin CLAUDE.md cargado - El agente inventa funciones — falta contexto de archivos fuente
- El agente re-implementa utilidades existentes — no se cargo el Project Map
- Calidad degrada en conversacion larga — compactar o iniciar sesion nueva
- El agente elige silenciosamente entre opciones ambiguas — añadir patron confusion management
+
Integraciones MCP para Contexto Enriquecido
Servidores MCP recomendados para el stack de LeadFlow — contexto en tiempo real
| MCP Server | Que proporciona | Aplicacion en LeadFlow |
|---|---|---|
| Context7 | Documentacion actualizada de librerias automaticamente | Docs de Prisma 5, Express 5, Zod — sin alucinaciones de API obsoleta |
| PostgreSQL MCP | Schema de base de datos y resultados de queries en vivo | El agente ve el schema real — no inventa columnas que no existen |
| GitHub MCP | Issues, PRs y contexto del repositorio | Al resolver un bug, el agente ve la issue original y los PRs relacionados |
| Filesystem MCP | Acceso y busqueda de archivos del proyecto | El agente encuentra ejemplos de patrones existentes sin que se los digas |