📜 O LLM e o cérebro (CLAUDE.md)
A "inteligência" do coach não está num código mágico — está num prompt: um arquivo de texto chamado CLAUDE.md que descreve quem é você e como o coach deve falar. É o cérebro carregado no começo de cada turno. Troque o conteúdo dele e você troca o coach.
🟢 Novo aqui?
- LLM — "Large Language Model", o modelo de IA do tipo que roda atrás do ChatGPT/Claude. Ele não tem acesso à sua vida: só sabe o que você escreve no prompt. Por isso o
CLAUDE.mdexiste — é onde você conta a ele os seus dados. - Prompt do sistema — o texto fixo que vai junto de TODA mensagem, antes da sua pergunta. Define o papel ("você é um coach de saúde"), as regras e o contexto. O coach é, no fundo, um LLM com um prompt muito bem escrito.
O CLAUDE.md vem como modelo (template) no repositório, com lacunas para você preencher. Seis blocos compõem o cérebro: perfil, metas, exames, DNA, restrições e estilo. Abaixo, um trecho ilustrativo (não são valores reais — você nunca versiona o seu preenchido):
📄 CLAUDE.md — o cérebro do coach (trecho 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 que isso importa
O LLM é genérico de fábrica. O que o torna o seu coach é o CLAUDE.md + os dados do banco. Mesmo modelo, prompt diferente, conselho completamente diferente: é a especificidade que faz a mágica — "specific beats generic".
Conceitos-chave
O modelo de IA; só sabe o que está no prompt.
O cérebro: perfil, metas, exames, DNA, regras, estilo.
Vem com lacunas; você preenche o seu.
Mesmo modelo, prompt seu = conselho seu.
📸 Session snapshot
O CLAUDE.md é estável (quem você é). Mas o coach também precisa do agora: como você acordou, o que comeu hoje, sua pressão. Isso vem do session snapshot — um retrato compacto montado pelo state.py e lido a cada turno, direto do banco.
O snapshot junta seis coisas: peso (tendência), intake de hoje, pressão (BP), a recovery de ontem, o padrão de sono de 7 dias e as metas. Por isso o coach nunca "adivinha": ele lê o estado atual antes de raciocinar. Abaixo, um exemplo ilustrativo do que o agente vê:
📸 SESSION SNAPSHOT (lido a 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 ↑📊 Como ler: a cada turno o state.py (verde) lê o banco E a memória (ciano), monta o snapshot junto do CLAUDE.md, e só então o LLM raciocina. A linha tracejada é a resposta voltando. O coach sempre parte do estado atual, nunca do nada.
Conceitos-chave
Retrato compacto do "agora", lido a cada turno.
O script que monta o snapshot do banco.
Peso, intake, BP, recovery, sono 7d, metas.
O coach nunca adivinha; lê o estado primeiro.
🧲 Memória semântica
O snapshot mostra o agora. Mas o ouro do coach é lembrar de semanas atrás — "da última vez que você bebeu vinho tarde, a recovery caiu pra 48%". Isso não é busca por palavra exata; é busca por significado. Esse é o papel da memória semântica (mem.py recall).
🟢 Novo aqui?
- Embedding — transformar um texto num vetor de números que captura o seu significado. Frases parecidas viram vetores próximos. Assim "tomei uma taça de vinho ontem" fica perto de "bebi álcool à noite", mesmo sem palavra em comum. No HealthOS, os embeddings vêm da OpenAI.
- pgvector — uma extensão do Postgres (o banco do Supabase) que guarda esses vetores e acha os mais próximos de uma busca. É o que permite "me lembre de mensagens parecidas com esta" em milissegundos.
O fluxo é simples: toda mensagem vira um embedding e é guardada. Quando você pergunta algo novo, a pergunta também vira embedding, e o pgvector traz as memórias mais próximas em significado. É assim que o coach "surfa" o seu histórico e enxerga padrões.
📊 Como ler: da esquerda pra direita — texto vira número (embedding), o número é guardado e comparado no pgvector, e o recall traz a memória mais parecida em significado. O coach não precisa que você use as mesmas palavras de antes.
Conceitos-chave
Texto vira vetor que captura o significado.
Extensão do Postgres que acha vetores próximos.
Traz a memória parecida em sentido, não em palavra.
É como o coach enxerga semanas, não só a última msg.
📚 RAG de conselhos
Você viu uma dica de um expert ou influencer ("jejum de 16h derrete gordura"). O comando /advice faz o coach reconciliar essa dica com os seus números — e devolve uma resposta citada, dizendo onde a dica encaixa em você e onde não. A regra de ouro: o seu dado sempre vence.
🟢 Novo aqui?
RAG (Retrieval-Augmented Generation) — "geração aumentada por recuperação". Em vez de o LLM responder só com o que "lembra", ele primeiro busca material relevante (aqui: a dica externa + os seus exames/metas) e gera a resposta em cima desse material, citando a fonte. Resultado: menos invenção, mais ancoragem no que é seu e no que foi dito.
✗ Dica solta (sem RAG)
- ✗"Jejum de 16h pra todo mundo" — sem olhar a sua HOMA-IR nem o seu sono.
- ✗Repete o que o influencer disse, sem fonte e sem o seu contexto.
- ✗Some na próxima conversa; não vira padrão seu.
✓ /advice (com RAG)
- ✓"A ideia faz sentido pra resistência à insulina; a SUA HOMA-IR já está boa, então o ganho é pequeno."
- ✓Cita a dica E os seus marcadores; mostra de onde tirou cada parte.
- ✓Conflito entre dica e seus dados? Os seus dados vencem.
⚖️ Quem ganha o desempate
Uma dica de internet é uma média; os seus exames são você. Quando os dois discordam, o /advice é instruído a priorizar o seu número e a dizer claramente onde a dica não se aplica. Continua não sendo conselho médico — é material para levar ao seu clínico.
Conceitos-chave
Busca material, depois gera citando a fonte.
O comando que reconcilia a dica com você.
Mostra de onde veio cada parte da resposta.
No conflito, o seu número manda.
🚩 Risk flags na prática
Cada marcador de sangue e cada SNP de DNA do painel mapeia para uma risk flag — uma regra que liga o "porquê" no seu corpo a uma ação: um suplemento no stack, um alvo, ou um alerta. É isso que transforma exames parados num conselho mecanismo-aware. Siga o caminho regra → ação no diagrama.
📊 Como ler: as entradas ciano (SNP + marcador) se combinam na flag (verde). A flag bifurca em duas ações: ajustar o stack de suplemento (verde) ou levantar um alerta para o médico (vermelho). Nenhuma entrada sozinha vira ação — é a combinação que conta.
Conceitos-chave
Regra que liga DNA + exame a uma ação.
Cada marcador/SNP aponta para flag, alvo ou suplemento.
As flags moldam o conjunto de suplementos.
O clínico, não o coach, decide o que é clínico.
⚠️ Limites — onde a IA para
Quanto melhor a IA fica, mais perigoso é esquecer o que ela não é. O coach é uma ferramenta de registro e raciocínio — não um médico. Dois limites técnicos e uma regra de ouro fecham este módulo.
⚠️ Os dois limites técnicos
- •Alucinação — o LLM pode inventar um número, um mecanismo ou uma citação com total confiança. Ele soa certo mesmo quando está errado.
- •Contexto perdido — se algo não estiver no snapshot nem no recall daquele turno, o coach simplesmente não sabe. Ele raciocina sobre o que foi carregado, não sobre tudo.
- •Amostras de DNA enviadas pelo correio degradam — o painel da clínica e o do Ancestry podem não bater.
🩺 A regra de ouro
Trate toda sugestão do coach como uma pergunta para levar ao médico, nunca como uma ordem para seguir. O coach é explicitamente instruído a não diagnosticar e a não mexer em medicação — ele sinaliza preocupações clínicas e encaminha para um clínico. Onde a IA ajuda: organizar, lembrar, cruzar e propor hipóteses. Onde ela para: qualquer decisão clínica.
✅ Auto-checagem (opcional): o coach sugere começar um suplemento novo. Qual é a atitude certa?
Conceitos-chave
Pode estar confiante e errado ao mesmo tempo.
Só sabe o que foi carregado naquele turno.
Não medica; encaminha ao clínico.
Toda sugestão vai ao médico.
🔐 Segurança
Dado de saúde é sensível, e o cérebro do coach (o seu CLAUDE.md preenchido) é o mais sensível de todos. O HealthOS é trancado por padrão: banco privado, acesso só pelo servidor, RLS sem políticas e segredos fora do git.
🟢 Novo aqui?
- RLS (Row-Level Security) — "segurança em nível de linha": recurso do Postgres que decide quem pode ler cada linha. No HealthOS ela fica ligada sem nenhuma política — ou seja, a chave pública (anon) não lê nada. Trava por omissão.
- Chave service-role — a chave administrativa do Supabase que contorna a RLS. Só o servidor a usa, e ela vive no
~/.env, nunca no navegador nem no git. É ela que dá ao coach acesso aos seus dados; vazá-la abre tudo.
✓ O que o desenho garante
- ✓Projeto Supabase privado, na sua conta.
- ✓RLS ligada, sem políticas: a chave anon não lê nada.
- ✓service-role só no servidor; segredos em
~/.env, fora do git.
✗ O que nunca versionar
- ✗O seu
CLAUDE.mdpreenchido (perfil + exames reais). - ✗A chave
SUPABASE_SERVICE_ROLE_KEYe as outras chaves. - ✗O arquivo
~/.enve os valores reais do seed.
🔑 Duas chaves, dois mundos
A anon é pública e inofensiva (com RLS sem políticas, lê nada). A service-role é o rei: abre tudo, então fica só no servidor, no ~/.env. Nada sai do seu projeto além das chamadas de LLM e embedding que você escolhe fazer.
Conceitos-chave
Ligada sem políticas: ninguém de fora lê.
Chave-rei, só no servidor, no ~/.env.
O banco é seu, na sua conta.
CLAUDE.md preenchido + segredos nunca versionados.
📋 Resumo do módulo
Próximo:
Trilha 2 — Passo a passo: do zero ao coach no ar — contas, banco Supabase, o agente e o bot, wearable e agendamento.