📜 El LLM y el cerebro (CLAUDE.md)
La «inteligencia» del coach no está en un código mágico: está en un prompt: un archivo de texto llamado CLAUDE.md que describe quién eres e cómo debe hablar el coach. Es el cerebro que se carga al comienzo de cada turno. Cambia su contenido y cambiarás el coach.
🟢 ¿Nuevo por aquí?
- LLM — «Large Language Model», el modelo de IA del tipo que funciona detrás de ChatGPT/Claude. No tiene acceso a tu vida: solo sabe lo que escribes en el prompt. Por eso el
CLAUDE.mdexiste — es donde le cuentas tus datos. - Prompt del sistema — el texto fijo que acompaña a TODOS los mensajes, antes de tu pregunta. Define el rol ("eres un coach de salud"), las reglas y el contexto. En el fondo, el coach es un LLM con un prompt muy bien redactado.
O CLAUDE.md viene como modelo (template) en el repositorio, con espacios para que los completes. Seis bloques componen el cerebro: perfil, metas, análisis, ADN, restricciones y estilo. Abajo, un fragmento ilustrativo (no son valores reales; nunca guardes en el control de versiones el archivo con tus datos):
📄 CLAUDE.md — el cerebro del coach (fragmento ilustrativo)
# Perfil
Nome, idade, sexo, altura, peso atual e composição.
# Metas
- Baixar ApoB; ganhar massa magra; dormir melhor.
# Exames (bloods)
- ApoB, LDL-C, Lp(a), hs-CRP, HOMA-IR, Vitamina D...
- (os SEUS valores reais ficam aqui — NÃO versionar)
# Genética (SNPs)
- CYP1A2: metabolizador rápido de cafeína
- MTHFR: metilação reduzida -> preferir folato metilado
- VDR: resposta à vitamina D abaixo da média
# Restrições
- Sem amendoim. Álcool ocasional.
- NUNCA mexer em medicação; encaminhar ao médico.
# Estilo do coach
- Direto, mecanismo-aware: cita o "porquê" no MEU corpo.
- Não diagnostica. Marca o que for clínico para o médico.💡 Por qué esto importa
El LLM es genérico de fábrica. Lo que lo hace el tuyo coach es el CLAUDE.md + los datos de la base de datos. El mismo modelo, un prompt diferente, un consejo completamente diferente: la especificidad es lo que hace la magia: «specific beats generic».
Conceptos clave
El modelo de IA; solo sabe lo que está en el prompt.
El cerebro: perfil, metas, exámenes, ADN, reglas, estilo.
Viene con campos vacíos; tú completas los tuyos.
Mismo modelo, tu prompt = tu consejo.
📸 Session snapshot
O CLAUDE.md es estable (quién eres). Pero el coach también necesita el ahora: cómo despertaste, qué comiste hoy, tu presión. Eso viene de session snapshot — una imagen compacta creada por el state.py y se lee en cada turno, directamente de la base de datos.
El snapshot reúne seis cosas: peso (tendencia), intake de hoy, presión (BP), la recovery de ayer, o patrón de sueño de 7 días y las objetivos. Por eso el coach nunca "adivina": lee el estado actual antes de razonar. A continuación, un ejemplo ilustrativo de lo que ve el agente:
📸 SESSION SNAPSHOT (se lee en cada turno — números ilustrativos)
peso 82.1 kg (tendência ▼ -0.4 / 7d)
intake hoje 1180 kcal · 96 g proteína
BP último 118 / 76
recovery 71% (verde) · HRV 64 · RHR 52 [ontem]
sono 7d média 7h05 · ontem 7h20
metas ApoB ↓ · massa magra ↑📊 Cómo leer: en cada turno, el state.py (verde) lee la base de datos Y la memoria (cian), arma el snapshot junto con el CLAUDE.md y solo entonces el LLM razona. La línea discontinua es la respuesta de vuelta. El coach siempre parte del estado actual, nunca de cero.
Conceptos clave
Retrato compacto del "ahora", leído en cada turno.
El script que genera el snapshot de la base de datos.
Peso, intake, BP, recovery, sueño 7d, metas.
El coach nunca adivina; primero lee el estado.
🧲 Memoria semántica
El snapshot muestra el ahora. Pero lo más valioso del coach es recordar hace semanas — «la última vez que tomaste vino tarde, la recuperación bajó a 48%». Esto no es una búsqueda por palabra exacta; es una búsqueda por significado. Este es el papel de la memoria semántica (mem.py recall).
🟢 ¿Nuevo por aquí?
- Embedding — transformar un texto en un vector de números que captura tu significado. Las frases parecidas se convierten en vectores cercanos. Así, "ayer tomé una copa de vino" queda cerca de "bebí alcohol por la noche", aunque no tengan palabras en común. En HealthOS, los embeddings vienen de OpenAI.
- pgvector — una extensión de Postgres (la base de datos de Supabase) que guarda esos vectores y encuentra los más próximos de una búsqueda. Es lo que permite «recuérdame mensajes parecidos a este» en milisegundos.
El flujo es simple: cada mensaje se convierte en un embedding y se guarda. Cuando haces una pregunta nueva, la pregunta también se convierte en un embedding, y el pgvector trae los recuerdos más cercanos en significado. Así es como el coach «surfea» tu historial y detecta patrones.
📊 Cómo leer: de izquierda a derecha, el texto se convierte en número (embedding), el número se guarda y se compara en pgvector, y el recall trae el recuerdo más parecido en significado. El coach no necesita que uses las mismas palabras de antes.
Conceptos clave
El texto se convierte en un vector que captura el significado.
Extensión de Postgres que encuentra vectores cercanos.
Trae el recuerdo con un sentido parecido, no con la misma palabra.
Es cómo el coach ve semanas, no solo el último mensaje.
📚 RAG de consejos
Viste un consejo de un experto o influencer («el ayuno de 16 h derrite la grasa»). El comando /advice lo hace el coach reconciliar este consejo con los tus números — y devuelve una respuesta citada, indicando dónde encaja el consejo en tu caso y dónde no. La regla de oro: tu dato siempre gana.
🟢 ¿Nuevo por aquí?
RAG (generación aumentada por recuperación) — «generación aumentada por recuperación». En vez de que el LLM responda solo con lo que «recuerda», primero búsqueda material relevante (aquí: el consejo externo + tus análisis y objetivos) y genera la respuesta basada en ese material, citando la fuente. Resultado: menos invenciones y más respaldo en lo que es tuyo y en lo que se dijo.
✗ Consejo aislado (sin RAG)
- ✗"Ayuno de 16h para todos" — sin revisar tu HOMA-IR ni tu sueño.
- ✗Repite lo que dijo el influencer, sin fuentes y sin tu contexto.
- ✗Desaparece en la próxima conversación; no se convierte en un patrón tuyo.
✓ /advice (con RAG)
- ✓"La idea tiene sentido para la resistencia a la insulina; TU HOMA-IR ya está bien, así que la mejora es pequeña."
- ✓Cita el consejo Y tus marcadores; muestra de dónde sacó cada parte.
- ✓¿Conflicto entre el consejo y tus datos? Tus datos son lo primero.
⚖️ Quién desempata
Un consejo de internet es un promedio; tus análisis hablan de ti. Cuando no coinciden, el /advice tiene instrucciones de priorizar el tu número y deja claro dónde no se aplica el consejo. Sigue sin ser consejo médico: es material para llevar a tu profesional de salud.
Conceptos clave
Busca material y luego genera el contenido citando la fuente.
El comando que concilia el consejo contigo.
Muestra de dónde viene cada parte de la respuesta.
En caso de conflicto, tu número es el que manda.
🚩 Risk flags en la práctica
Cada marcador de sangre y cada SNP de ADN del panel se mapea a una risk flag — una regla que conecta el "porqué" en tu cuerpo con una acción: un suplemento en el stack, un objetivo o una alerta. Eso es lo que transforma análisis sin usar en un consejo consciente de los mecanismos. Sigue el recorrido regla → acción en el diagrama.
📊 Cómo leer: las entradas cian (SNP + marcador) se combinan en la flag (verde). La flag se bifurca en dos acciones: ajustar el stack de suplementos (verde) o emitir una alerta para el médico (rojo). Ninguna entrada por sí sola se convierte en acción — lo que cuenta es la combinación.
Conceptos clave
Regla que vincula el ADN + examen con una acción.
Cada marcador/SNP apunta a una flag, un objetivo o un suplemento.
Las flags dan forma al conjunto de suplementos.
El clínico, no el coach, decide qué es clínico.
⚠️ Límites — dónde se detiene la IA
Cuanto mejor se vuelve la IA, más peligroso es olvidar lo que no es. El coach es una herramienta para registrar y razonar —no es un médico. Dos límites técnicos y una regla de oro cierran este módulo.
⚠️ Los dos límites técnicos
- •Alucinación — el LLM puede inventar un número, un mecanismo o una cita con total confianza. Suena convincente incluso cuando está equivocado.
- •Contexto perdido — si algo no está en el snapshot ni en el recall de ese turno, el coach simplemente no lo sabe. Razonará sobre lo que se cargó, no sobre todo.
- •Las muestras de ADN enviadas por correo se degradan; el panel de la clínica y el de Ancestry pueden no coincidir.
🩺 La regla de oro
Trata cada sugerencia del coach como una pregunta para llevar al médico, nunca como una orden que debas seguir. Se instruye explícitamente al coach para que no diagnosticar e a no modificar la medicación — señala preocupaciones clínicas y deriva a un profesional clínico. Dónde ayuda la IA: organizar, recordar, cruzar datos y proponer hipótesis. Dónde se detiene: cualquier decisión clínica.
✅ Autoevaluación (opcional): el coach sugiere empezar un suplemento nuevo. ¿Cuál es la actitud correcta?
Conceptos clave
Puede estar seguro y equivocarse al mismo tiempo.
Solo sabe lo que se cargó en ese turno.
No medica; deriva al clínico.
Toda sugerencia va al médico.
🔐 Seguridad
Los datos de salud son sensibles, y el cerebro del coach (el tuyo CLAUDE.md completados) es el más sensible de todos. HealthOS es bloqueado por defecto: base de datos privada, acceso solo desde el servidor, RLS sin políticas y secretos fuera de git.
🟢 ¿Nuevo por aquí?
- RLS (Row-Level Security) — «seguridad a nivel de fila»: función de Postgres que decide quién puede leer cada fila. En HealthOS permanece activada sin ninguna política — es decir, la clave pública (anon) no puede leer nada. Bloqueado por defecto.
- Clave service-role — la clave administrativa de Supabase que lo esquiva la RLS. Solo la usa el servidor y vive en
~/.env, nunca en el navegador ni en git. Es lo que le da al coach acceso a tus datos; filtrarla lo expone todo.
✓ Qué garantiza el diseño
- ✓Proyecto Supabase privado, en tu cuenta.
- ✓RLS activada, sin políticas: la clave anon no puede leer nada.
- ✓service-role solo en el servidor; secretos en
~/.env, fuera de git.
✗ Lo que nunca debes versionar
- ✗Tu
CLAUDE.mdcompletado (perfil + exámenes reales). - ✗La clave
SUPABASE_SERVICE_ROLE_KEYy las demás claves. - ✗El archivo
~/.envy los valores reales de la semilla.
🔑 Dos claves, dos mundos
A anon es pública e inofensiva (sin políticas de RLS, no lee nada). La service-role es el rey: lo abre todo, así que se queda solo en el servidor, en el ~/.env. Nada sale de tu proyecto, salvo las llamadas al LLM y a embeddings que decidas hacer.
Conceptos clave
Activada sin políticas: nadie de fuera puede leer.
Clave maestra, solo en el servidor, en el ~/.env.
La base de datos es tuya, en tu cuenta.
CLAUDE.md completado + secretos nunca versionados.
📋 Resumen del módulo
Siguiente:
Ruta 2 — Paso a paso: de cero a tener el coach en funcionamiento — cuentas, base de datos de Supabase, el agente y el bot, wearable y programación.