O que é um context document
O documento que ensina a IA a entender os seus dados.
- Entender o papel do context document
- Reconhecer um bom contexto vs um ruim
- Saber o que colocar nele
Imagine contratar alguém genial em SQL, mas que nunca ouviu falar da
sua empresa. Ela sabe juntar tabelas e somar colunas, só que não faz
ideia do que mrr significa, se
status = 2 quer dizer "ativo" ou "cancelado", nem quem
conta como cliente. Antes de dar qualquer resposta útil, ela precisa
que alguém explique o negócio. Um
context document serve justamente pra isso, escrita
uma vez e entregue à IA toda vez que ela consulta seus dados.
Ele mora na Camada Semântica, a camada que dá significado às tabelas, e é lido pelo agente de IA (via MCP) junto com o schema. Mas atenção: o context document não repete o que suas tabelas e colunas são. Isso já vive em outro lugar.
Onde mora cada coisa: Catálogo e context document
A descrição de tabelas e colunas (o que o dado é) você escreve direto no Catálogo da Nekt, campo a campo. O context document guarda o resto: como o seu negócio funciona. As regras que não aparecem em coluna nenhuma, como reconhecimento de receita, a definição de cliente ativo, os critérios de cada etapa do funil e as regras específicas que devem ser consideradas em cada análise.
| Coluna | Descrição |
|---|---|
id int |
Identificador único da assinatura |
status int
|
1 = ativa, 2 = cancelada, 3 = em atraso |
mrr decimal
|
Receita recorrente mensal, em BRL |
cliente_id int
|
Referência ao cliente dono da assinatura |
Consideramos cliente ativo toda assinatura com status pago e ao menos um pagamento confirmado. Trials cancelados que nunca pagaram não contam. A receita é reconhecida a partir da data de corte do financeiro.
assinaturas.statuspagamentos
Por que isso importa
Sem contexto, a IA precisa adivinhar. Ela vê uma coluna chamada
mrr e chuta que é receita mensal, vê
cliente_ativo e inventa o que "ativo" significa, encontra
status = 2
e cruza os dedos. Cada chute é uma chance de resposta errada, e para
chegar perto ela ainda gasta mais tokens explorando a tabela. Com
contexto, ela responde certo de primeira e mais barato, porque o
significado já veio mastigado.
Anatomia de um context document
Na Nekt, um context document combina duas coisas que trabalham juntas:
| Parte | O que é |
|---|---|
| Prosa | Explicações em linguagem simples, do jeito que você explicaria a regra a um analista novo no primeiro dia |
| Anotações | Ligações da prosa a recursos do workspace: tabelas, campos, camadas, queries, notebooks e fontes |
A mágica está nas anotações. Quando o agente lê o documento, cada anotação resolve para o nome e a descrição do recurso que ela aponta. Assim a prosa (o contexto de negócio) e o schema (o contexto técnico) chegam à IA no mesmo pacote, sem ela precisar sair caçando de qual tabela ou coluna você está falando.
Um bom context document na prática
Veja um exemplo curto do conceito "Cliente ativo". Repare como a prosa carrega a regra e as anotações apontam para os recursos concretos.
Consideramos cliente ativo toda assinatura com status pago e ao menos um pagamento confirmado. Trials cancelados que nunca pagaram não contam. A receita é reconhecida a partir da data de corte definida pelo financeiro.
Anotações que a prosa resolve
| Menção na prosa | Resolve para |
|---|---|
| "assinatura" |
gold.assinaturas · uma linha por assinatura
|
| "status pago" |
gold.assinaturas.status · 1 = ativa, 2 =
cancelada
|
A Nekt oferece templates prontos para os conceitos que quase toda empresa precisa descrever:
| Template | O que ele documenta |
|---|---|
| Receita e MRR | Como a receita é reconhecida, o cálculo de MRR e o tratamento de múltiplas moedas |
| Cliente ativo | Quais status contam como pagante e o que fica de fora |
| Etapas de funil | Os critérios de MQL, SAL e SQL |
| Uso de produto | Conversões de unidade e limites de cada plano |
| Regras transversais | Os gotchas que valem para toda análise: exclusões, soft deletes, moedas |
Descreva o que a métrica significa, não como ela foi implementada. O schema muda com o tempo, a definição permanece. Mantenha cada documento focado num único conceito e, em vez de repetir a mesma regra em vários lugares, cruze referências entre documentos. Um documento de "Receita" pode apontar para o de "Cliente ativo" em vez de recopiar a definição inteira.
Um SaaS tinha um agente que errava toda pergunta de negócio. Perguntavam "quantos clientes ativos temos" e ele contava linhas da tabela de clientes, incluindo trials cancelados e contas de teste. Depois de um context document "Cliente ativo" (com a regra "ativo = assinatura paga com uso nos últimos 30 dias" e anotações apontando para a tabela de assinaturas e o campo de status), o mesmo agente passou a acertar. Nada mudou no dado, só o significado passou a ser explícito.