Cómo funciona Claude

Verificar Vercel READY después de cada push antes de avisar a Gregory

Después de cada git push: (1) list_deployments → obtener ID del deploy más reciente, (2) get_deployment → verificar state: READY, (3) si ERROR → leer logs, corregir, nuevo push, volver a verificar. NUNCA decir "listo" hasta confirmar READY. Esto pasó múltiples veces y Gregory se cansó.

Actualizar SYSTEM.md en el mismo commit cuando cambie algo significativo

SYSTEM.md es la fuente de verdad del estado del sistema. Actualizar cuando: nueva tabla en Supabase, nuevo env var, nuevo componente construido, decisión arquitectónica, cambio de estado (pending → active). El cambio a SYSTEM.md va en el MISMO commit que el código. Sin esto la próxima sesión empieza sin contexto real.

Escribir en memoria después de CADA tarea — la info está, solo hay que buscarla

Después de cada tarea que pide Gregory: (1) escribir en tabla memory qué se hizo + contexto + tags, (2) antes de preguntar algo, buscar en memoria primero, (3) si no está → preguntar a Gregory → guardar la respuesta. La memoria NO se lee completa — se busca cuando necesario. Regla definida por Gregory el 2026-06-29.

Actualizar AGENTS.md en el mismo commit cuando se toca un agente

Cada vez que se crea, modifica o elimina un agente en src/pipeline/ o src/queue/: (1) leer AGENTS.md antes, (2) al terminar actualizar sección del agente: modelo, tokens/req, costo/req, (3) el cambio va en el MISMO commit. Si el agente no loguea input_tokens/output_tokens/thinking_tokens en metadata → es un bug. Incidente 23/06/2026: sales-closer usó Pro, gastó $9, dashboard mostraba $3.29.

Todo cambio que hago queda visible en el CRM — sin que Gregory lo pida

Si toco un .md (SYSTEM.md, CLAUDE.md, AGENTS.md, cualquiera), la base de datos, o archivos de configuración: escribo una entrada en tabla memory con lo que cambié y por qué. El CRM /memory es la ventana que Gregory tiene para entender todo lo que estoy haciendo. Esta regla existe porque el CRM es la única manera que Gregory tiene de entenderme todo el tiempo. Regla definida 2026-06-29.

No commitear código roto — cada commit debe funcionar

Nunca commitear trabajo en progreso ni código que no pasa el build. Cada commit representa un estado funcional del sistema. Si Vercel da ERROR → corregir antes de avisar. Si el pipeline en Oracle falla → corregir antes de avisar. Un commit = una unidad de trabajo completa y verificada.

Spec antes de codear para cualquier tarea que tome más de 5 minutos

Para cualquier tarea que tome más de 5 minutos: (1) escribir spec en .md en el repo (qué se construye, qué NO, cómo funciona), (2) Gregory lo aprueba — puede pedir cambios, (3) recién entonces codear exactamente lo que dice el spec. Menos de 5 minutos = micro ajuste, sin spec necesario. Si algo surge durante el desarrollo que no está en el spec → pausar y preguntar a Gregory. El .md de spec queda en el repo como documentación permanente.

Todo lo construido tiene su .md — buscar antes de preguntar, crear si no existe

Antes de preguntar a Gregory algo sobre cómo funciona una parte del sistema, buscar primero: (1) SYSTEM.md — estado general, (2) .md del módulo (AGENTS.md, RESTAURANT_FLOW.md, etc.), (3) tabla memory — search(). Si ninguno lo tiene → preguntar a Gregory → crear el .md con la respuesta. Todo feature, módulo o decisión importante tiene su .md en el repo. Si necesito info y la busco y no existe → ese es el momento de preguntar. Esta es la regla de conocimiento: todo existe documentado o no debería existir sin documentarse.

Reglas de oro: siempre actualizar CLAUDE.md Y Supabase (category=rule) juntos

Cuando Gregory pide agregar o modificar una regla de oro, hacer DOS cosas sin que lo pida: 1) Actualizar CLAUDE.md con la nueva regla. 2) INSERT o UPDATE en tabla memory con category='rule', importance='high' para que aparezca en /rules y en el filtro Reglas de oro del CRM. No alcanza con solo actualizar el .md — la regla tiene que vivir en Supabase para ser visible en el CRM.

Todo lo que existe en el sistema debe estar visible en el CRM

Si algo existe (datos, logs, config, estado de agentes, pagos, dominios, etc.) y NO está en el CRM, se sugiere creación de página o subpágina para mostrarlo. El CRM es el único lugar donde Gregory puede entender qué está pasando. Si no está en el CRM, no existe para él. Cuando Gregory aprueba la sugerencia, se crea sin que lo pida de nuevo.

Escribir en memory después de CADA prompt, no solo al terminar módulos

Cada respuesta a Gregory debe terminar con una entrada en la tabla memory documentando qué se hizo. Esto sirve como log operativo visible en el CRM. No alcanza con escribir al terminar un módulo grande — cada tarea pequeña también queda registrada.

Regla de oro: buscar en memoria con keywords específicos del tema, no genéricos

Antes de preguntar algo a Gregory sobre un tema X, buscar en memoria usando keywords específicos de ese tema. Si el tema es Cloudflare → buscar "cloudflare". Si el tema es pagos → buscar "mercadopago" o "stripe". Nunca buscar solo "context" o "pending" esperando encontrar todo. Error detectado el 2026-06-29 cuando pregunté por credenciales CF sin buscar por "cloudflare" específicamente.

Regla de oro: cuando me equivoco, crear regla de oro automáticamente sin que Gregory lo pida

Cada vez que cometo un error — de búsqueda, de implementación, de proceso — debo crear automáticamente una regla de oro para que no se repita. Hacer DOS cosas sin que Gregory lo pida: 1) actualizar CLAUDE.md con la regla, 2) INSERT en tabla memory con category=rule, importance=high. No esperar que Gregory me lo pida. El error es la señal para crear la regla.

Regla de oro: comandos Oracle siempre listos para copiar y pegar

Cuando Gregory necesita ejecutar algo en Oracle (actualizar .env, correr scripts, reiniciar PM2, etc.), siempre dar el comando completo listo para copiar y pegar en su terminal SSH. Nunca decir "entrá al archivo y cambiá X" — siempre dar el sed, echo, o script exacto que hace el cambio solo sin intervención manual.

Verificar SYSTEM.md en CADA prompt, no solo al terminar módulos

Al recibir cada prompt de Gregory, antes de responder: leer mentalmente el estado de SYSTEM.md y verificar si lo que se está por hacer/discutir está reflejado. Si hay algo desactualizado → actualizar ahora, no al final de la sesión. Además: cualquier cambio de código, variables o arquitectura → actualizar SYSTEM.md en el mismo commit. Esta regla evita perder el hilo entre sesiones. Creada 2026-06-30 por pedido explícito de Gregory.

REGLA DE ORO: al tocar un agente, actualizar AGENTS.md Y agents-data.ts — no solo uno

Corregida 02/07/2026. La regla vieja decía solo "actualizar AGENTS.md" — pero hay DOS archivos que documentan agentes: AGENTS.md (raíz, ficha técnica de costos/modelo/tokens) y crm/src/lib/agents-data.ts (lo que Gregory ve en /agents/[slug] del CRM — description, tasks, config). Durante el pivot a hamburguesas/lomiterías actualicé AGENTS.md para prospector/qualifier/web-generator/panel-generator/sales-closer pero no revisé agents-data.ts para prospector/qualifier/web-generator — Gregory tuvo que preguntarme explícitamente si lo había hecho. Encontré 3 entradas ya desactualizadas ahí (google-prospector: config todavía listaba CITIES/CATEGORIES como env vars cuando ya se habían movido a Supabase; qualifier: decía umbral de descarte <40 cuando el código real es <60, y no mencionaba el bonus HIGH_VALUE; web-generator: decía que el template se elige "según el score" cuando en realidad es por categoría/template_catalog). REGLA CORREGIDA: cada vez que se toca un agente, leer y actualizar AMBOS archivos en el mismo commit — AGENTS.md Y la entrada correspondiente en agents-data.ts. Ver CLAUDE.md sección "AGENTS.md Y agents-data.ts: actualizar SIEMPRE LOS DOS que se toque un agente" para el texto completo. Por qué importa: agents-data.ts es literalmente la única ventana que Gregory tiene al comportamiento real de cada agente desde el CRM — si queda desactualizado, Gregory toma decisiones con información falsa sin saberlo (regla de oro "todo lo que existe debe estar visible en el CRM").

REGLA DE ORO: matar procesos de preview propios colgados directo, sin preguntar

Creada 03/07/2026 después de que Gregory tuvo que aprobar la misma acción trivial varias veces en la misma sesión (matar mi propio proceso Node huérfano en el puerto 3001, dejado por preview_stop que no siempre mata el proceso hijo real de npm run dev). REGLA: cuando reconozco el proceso colgado como propio (mismo preview_start de esta sesión o de una sesión reciente, verificable por el StartTime del proceso), lo mato directo con Stop-Process -Force sin usar AskUserQuestion. NO aplica a procesos que no reconozco como propios — ahí sigue valiendo la precaución normal de confirmar antes de matar algo desconocido (esto se mantiene igual que siempre). Ver CLAUDE.md sección "Procesos de preview huérfanos: matarlos directo, sin preguntar — REGLA DE ORO" para el texto completo.

REGLA: al agregar un rubro nuevo, revisar extractSiteData() en web-analyzer.js (teamNames asume Dr./Dra.)

Creada 03/07/2026 a pedido de Gregory. web-analyzer.js → extractSiteData() extrae teamNames con un regex hardcodeado a vocabulario de salud (Dr./Dra./Doctor/Doctora) — no aplica a hamburguesas/lomiterías ni a rubros futuros sin esa figura profesional. Cada vez que se agrega un rubro nuevo es obligatorio revisar si esto necesita otro patrón de nombre propio (ej. Chef, Sommelier, dueño/fundador) o si teamNames queda vacío a propósito para ese rubro — decidirlo explícitamente, no dejarlo pasar por default. Gregory lo va a corregir él mismo para hamburguesas ahora, pero esto tiene que quedar documentado para cuando agentes de management (Fase 6) u otras sesiones tomen esta decisión en el futuro sin el contexto completo. Documentado en 3 lugares: comentario ⚠️ OBLIGATORIO en el código (src/lib/web-analyzer.js, junto al regex), checklist obligatorio en templates/COMO_AGREGAR_UN_TEMPLATE.md (paso 4), y nota en AGENTS.md sección web-analyzer. Commit ff3b064. ACTUALIZACIÓN 03/07/2026: Gregory pidió arreglarlo de raíz en el momento en vez de dejarlo como paso manual documentado. Implementado: TEAM_NAME_PATTERNS en web-analyzer.js, keyed por content_type — dental usa el regex de Dr./Dra., restaurant no tiene patrón (teamNames vacío a propósito). web-generator.js pasa el content_type correcto en cada llamada. Funciona con cualquier cantidad de rubros simultáneos porque es un parámetro por llamada, no estado global. El paso "revisar esto al agregar un rubro" ahora solo aplica si se agrega un content_type genuinamente NUEVO (ni dental ni restaurant) — para dental/restaurant ya está resuelto. Commit 3943bdd.

Regla de oro: si falla la generación de contenido para un cliente, el prospecto nunca avanza de etapa

Gregory dictó esta regla el 04/07/2026 al revisar el hallazgo de la auditoría de web-generator.js: los catches de generateAiContent()/generateAiContentForRestaurant() devolvían defaults hardcodeados (DEFAULT_SERVICES, DEFAULT_FAQ, DEFAULT_RESTAURANT_AI) con costUsd:0 SIN loguear el error real, y el prospecto igual pasaba a status:"generated" como si tuviera copy personalizado. Cruzado con los 429 de cuota vistos en la auditoría del copywriter, esto sugiere que varias webs reales de fines de junio 2026 salieron con copy 100% genérico (mismos servicios/FAQ para todos los dentistas) sin ningún rastro de error en los logs. REGLA: en cualquier agente que genere contenido para un prospecto/cliente real, si la generación falla por cualquier motivo, el prospecto NO puede avanzar de status ni parecer "generado con éxito". Todo catch debe loguear el error real (nunca silencioso). Si falla, se queda en un estado que refleje el fallo (reintento o flag de error explícito), nunca avanza con contenido genérico/roto disfrazado de éxito. Aplica en cascada a agentes aguas abajo (QA, SEO, sender). Actualizado en CLAUDE.md en la sección "Reglas operativas — NO NEGOCIABLES", inmediatamente después de la regla de worktrees huérfanos. IMPLEMENTACIÓN PENDIENTE (no confundir con la regla en sí, que ya está escrita y vigente desde ahora): falta escribir el código real en web-generator.js (y evaluar copywriter.js/panel-generator.js/seo-specialist.js) para cumplir esta regla — logging real en los catches + un status/flag de fallo explícito que impida avanzar. Ver spec pendiente de aprobación de Gregory sobre el rediseño de web-generator (selector de template escalable + QA que preserva el copy_content + esta regla).

Regla de oro: si no usa IA, no es "agente" — es "herramienta", en toda la doc y el CRM

Gregory dictó esta regla el 04/07/2026 al ver que seo-specialist.js (SEO Injector) quedó 100% determinista tras eliminarle su única llamada a IA (era redundante, ver memoria "eliminación de IA redundante en SEO Specialist"). Dijo textual: "actúa en el CRM para decir herramienta, u otra palabra que no sea agente, si no usa IA no es agente." REGLA: un paso del pipeline se llama "agente" SOLO si llama a un modelo de IA. Si no (lógica determinista, solo APIs externas no-LLM, o solo Supabase), se lo llama "herramienta" en AGENTS.md, agents-data.ts y el CRM (/agents, /flows) — sin importar si tiene su propio cron/entrada en PIPELINE_STAGES. Es un criterio distinto y más estricto que el ya usado para web-analyzer ("no tiene cron propio") — este es puramente sobre uso de IA. Ya actualizado en CLAUDE.md como regla de oro. Ya aplicado a seo-specialist (SEO Injector) el mismo día: kind:"tool" en agents-data.ts, badge "🔧 Herramienta" en /agents y /agents/seo-specialist, nodo de /flows muestra "🔧 Herramienta" en vez de "Activo", AGENTS.md tiene el callout "⚠️ Esto es una herramienta, no un agente". PENDIENTE — NO aplicado todavía (barrido futuro, no pedido en esta sesión): qualifier.js (sin IA, reglas puras), google-prospector.js/yelp-prospector.js/ml-prospector.js (solo APIs externas no-LLM), domain-agent.js (Porkbun/Cloudflare), payment-agent.js (Mercado Pago), create-restaurant-account.js (solo Supabase) — todos calzan en el criterio "sin IA = herramienta" pero no se tocaron ahora porque Gregory pidió específicamente por SEO Injector. Aplicar el mismo tratamiento la próxima vez que se audite o se toque cualquiera de estos.

Gregory prefiere que yo ejecute directo en Oracle por SSH cuando sea posible, en vez de solo darle el comando

Gregory: "prefiero que lo hagas siempre que posible" (04/07/2026), tras confirmarme que puedo conectarme yo mismo por SSH con su key local (C:\Users\cande\Downloads\ssh-key-2026-06-21.key, usuario ubuntu@163.176.206.142). Antes solo le daba el comando listo para copiar/pegar (regla vieja de CLAUDE.md). Ahora, para acciones de bajo riesgo y ya autorizadas en el flujo de la conversación (deploys, git pull, restarts, backfills), debo intentar ejecutarlas yo directo por SSH en vez de limitarme a entregar el comando — sigue aplicando pedir confirmación antes de acciones nuevas/riesgosas que no se hayan discutido, pero una vez que el paso está aprobado en la conversación, ejecutarlo yo es lo preferido.

REGLA NUEVA: si el git pull en Oracle trae cambios en package.json, correr npm install ahí también, no alcanza con el pull

Agregada a CLAUDE.md (06/07/2026) tras encontrar que src/lib/openai.js/anthropic.js llevaban días en el repo sin que node_modules de Oracle tuviera el paquete openai instalado — researcher/copywriter/sales-closer fallaban en cada corrida real, en silencio, hasta que se detectó auditando logs. La regla de "verificar Vercel + Oracle después de cada push" ahora incluye: si package.json cambió, correr npm install en Oracle y verificar con un import de prueba antes de avisar que está listo.

Nueva regla de oro: cruzar incidentes de costo contra el dashboard real del proveedor, nunca confiar solo en system_logs

Ver CLAUDE.md sección "Ante un incidente de costo real, cruzar SIEMPRE contra el dashboard de facturación del proveedor". Causa: reporté a Gregory que los 182 logs con tokens_estimated:true ($3.29) eran "la reconstrucción del incidente del 23/06" sin cruzarlo contra Google Cloud Console. Gregory compartió capturas reales: $12.11 de costo total ese día, 1.004 requests a Gemini 2.5 Pro, 41.62% de éxito. Cero filas en system_logs (de cualquier stage) tienen metadata.model=gemini-2.5-pro ese día — el modelo real que causó el incidente es invisible en nuestra DB. La causa real, encontrada en los mensajes de error crudos: 429 "Your prepayment credits are depleted" contra gemini-2.5-pro:generateContent desde las 16:24 UTC hasta las 23:59 UTC (casi 8 horas de reintentos contra una cuenta con el prepago agotado, sin loguear nada más que console.error en cada intento). Los 182 "estimados" resultaron ser los logs reales de los primeros ~12 minutos (antes de agotar el prepago) con un placeholder de tokens (33000/1200 fijo) en vez del usageMetadata real — no una reconstrucción posterior.

Capa 1 — CLAUDE.md: reglas de trabajo (Git repo)

Contiene: reglas operativas no negociables, cómo trabajar en el proyecto, estándares de código, lo que nunca hacer. Se lee al inicio de cada sesión. Solo cambia cuando Gregory aprueba una nueva regla. Es la constitución del proyecto.

Capa 2 — SYSTEM.md: estado real del sistema (Git repo)

Contiene: qué está construido, arquitectura Oracle+Vercel, todas las tablas con campos, env vars completas, estado de cada componente (activo/pendiente/pausado), decisiones arquitectónicas, comandos para correr el pipeline. Se lee al inicio de cada sesión. Se actualiza en el mismo commit que el código.

Capa 3 — Tabla memory en Supabase: contexto dinámico

Contiene: decisiones de sesiones anteriores, tareas completadas, bugs encontrados, context important, warnings, reglas (esta misma entrada). Se escribe durante las sesiones. Se lee al inicio (high importance) y se busca cuando necesario. Es la memoria viva del proyecto — sobrevive compactaciones de contexto.

Capa 4 — .md por módulo: detalle profundo (Git repo)

Archivos: AGENTS.md (todos los agentes, modelos, costos), RESTAURANT_FLOW.md (flujo completo restaurante SaaS), SPEC.md (plan original). Se leen solo cuando se trabaja en ese módulo específico. Tienen más detalle técnico que SYSTEM.md.

Capa 5 — Memoria local Claude Code: recordatorios cross-proyecto

Ubicación: C:\\Users\\cande\\.claude\\projects\\...\\memory\\. Se carga automáticamente al abrir Claude Code. Contiene recordatorios que deben sobrevivir entre proyectos diferentes. Ejemplo actual: cuando Gregory mencione agentes C-level, recordarle integrar tabla memory ANTES de activarlos.

Capa 6 — Specs .md por feature/tarea: documentación permanente (Git repo)

Cualquier tarea >5 min genera un .md antes de codear (spec) y se actualiza al terminar (doc final). Ubicación: raíz del repo o carpeta /docs. Ejemplos actuales: RESTAURANT_FLOW.md, AGENTS.md, SPEC.md. Antes de construir algo → busco si ya existe su .md. Si no existe y la tarea toma más de 5 min → lo creo antes de empezar. Esta capa es la que cierra el ciclo: todo lo que sé de este proyecto puede encontrarse en alguno de estos archivos.