📁 Camada Base: Fontes Brutas
A base da pirâmide sustenta tudo que existe acima. Se a base está podre, a pirâmide inteira desmorona — não importa quão bem você construiu as camadas superiores. O primeiro passo em qualquer projeto é entender o que existe aqui.
📁 O que vive na Base da Pirâmide
Formatos de Arquivo
- • CSV — simples mas perigoso (delimitadores, encoding)
- • XLSX — dados + formatação + macros misturados
- • PDF — dados "para ver", não "para processar"
- • JSON/XML — APIs e sistemas web
- • Parquet — colunar, eficiente, moderno
Fontes de Sistema
- • ERP — SAP, Oracle, TOTVS, dados de décadas
- • CRM — Salesforce, HubSpot, dados de vendas
- • E-commerce — Shopify, WooCommerce, pedidos
- • Marketing — Google Analytics, Meta Ads
- • Financeiro — exportações contábeis, bancos
⚠️ O Inventário é Obrigatório
Antes de qualquer processamento, você precisa saber: quais fontes existem, quem é o dono de cada uma, com que frequência são atualizadas, e qual é a confiabilidade histórica. Sem inventário, você descobre a metade das fontes no meio do projeto.
💡 Regra da Base
Trate cada fonte bruta como suspeita até que você prove o contrário. Nunca assuma que um arquivo CSV está correto só porque alguém disse que está. Audite sempre antes de processar.
🔍 Camada 2: Auditoria
Antes de limpar qualquer coisa, você precisa entender o que está limpando. Auditoria é o diagnóstico médico dos dados — sem diagnóstico, você opera no escuro e trata a doença errada.
🔍 O Checklist de Auditoria
🛠️ Ferramentas de Auditoria
- DuckDB SQL —
SELECT COUNT(*), COUNT(DISTINCT id)para auditar direto - pandas —
df.describe(),df.isnull().sum(),df.dtypes - ydata-profiling — relatório completo de auditoria em uma linha de código
- Claude Code — pedir análise exploratória automatizada com decisões documentadas
⚠️ Quando a Auditoria Falha
Pular auditoria e ir direto para limpeza é como um médico que opera sem diagnóstico. Você vai remover coisas que não deveria e deixar problemas que não viu. A auditoria documentada também serve como contrato: "no início do projeto, os dados estavam assim."
📋 Camada 3: Snippets
Snippets são amostras representativas dos dados — tipicamente 100 linhas cuidadosamente selecionadas de cada tabela. São o "cartão de visita" dos dados para sistemas de IA. Em vez de jogar 1 milhão de linhas no contexto, você fornece 100 bem escolhidas.
📋 O que são Snippets Bons vs Ruins
✗ Snippet Ruim (100 linhas aleatórias)
Amostra aleatória pode sobre-representar o caso comum e não mostrar os edge cases. Um agente que vê 100 clientes ativos pode não saber que existe um status "suspenso" que aparece em 2% dos casos — mas é crítico.
✓ Snippet Bom (100 linhas curadas)
Representa todos os valores únicos de colunas categóricas, inclui casos extremos de colunas numéricas, cobre diferentes períodos de tempo, mostra exemplos de nulos onde existem.
💡 A Regra dos Snippets
100 linhas bem escolhidas > 1 milhão de linhas aleatórias para dar contexto a um agente. Curadoria supera volume quando o objetivo é contexto.
Um agente que viu um bom snippet de uma tabela de clientes entende os padrões, os casos especiais e os limites dos dados sem precisar processar tudo. Isso reduz custo de token e aumenta precisão.
Critérios para incluir no snippet
- • Pelo menos 1 exemplo de cada valor categórico
- • Exemplos com nulos nas colunas que têm nulos
- • Min e max de colunas numéricas
- • Registros mais antigos e mais recentes
Como usar snippets
- • Incluir no prompt de sistema do agente
- • Usar para validar se o agente entendeu o schema
- • Atualizar quando o schema mudar
- • Combinar com descrição de cada coluna
📊 Camada 4: Resumos
Resumos são tabelas pré-calculadas que agregam os dados brutos em métricas úteis. São o resultado da modelagem dimensional — onde tabelas fato registram o que aconteceu e tabelas dimensão fornecem o contexto.
📊 Tabelas Fato vs Tabelas Dimensão
Tabela Fato — O Que Aconteceu
Registra eventos com métricas mensuráveis.
- • fato_vendas (pedido_id, cliente_id, produto_id, valor, data)
- • fato_acesso (sessao_id, usuario_id, pagina_id, tempo, data)
- • fato_producao (turno_id, maquina_id, quantidade, refugo, data)
Tabela Dimensão — O Contexto
Fornece atributos descritivos para os fatos.
- • dim_cliente (cliente_id, nome, regiao, segmento, dt_cadastro)
- • dim_produto (produto_id, nome, categoria, preco, fornecedor)
- • dim_tempo (data_id, dia, mes, trimestre, ano, dia_semana)
💡 O Poder dos Resumos Pré-calculados
Em vez de um agente calcular "receita total por região no último trimestre" varando 10M de linhas toda vez, você materializa essa tabela:
resumo_receita_trimestral (regiao, trimestre, receita_total, n_pedidos, ticket_medio)
O agente consulta uma tabela com 100 linhas em vez de 10 milhões. 100x mais rápido, 100x mais barato.
📈 O Que Materializar
- Sempre: métricas consultadas diariamente (receita, volume, usuários ativos)
- Considere: agrupamentos frequentes (por região, produto, período)
- Opcional: análises ad-hoc que acontecem raramente — deixe o agente calcular na hora
🧠 Topo: Briefs, Agentes e Decisões
O topo da pirâmide é onde os dados se tornam inteligência. Briefs combinam dados resumidos com contexto de negócio para criar o input perfeito para agentes tomarem decisões de qualidade.
📄 O que é um Brief Bem Estruturado
Um brief eficiente tem 4 componentes:
✗ Brief Ruim
"Analise as vendas do mês e diga o que está errado."
Sem dados, sem contexto, sem comparativo, pergunta vaga. O agente vai inventar contexto.
✓ Brief Bom
"Abril/2026: R$1,2M em vendas (-8% vs março, -3% vs abril/2025). Região Sul -15%. Produto X +22%. Análise: o que explica a queda no Sul e se o crescimento do Produto X pode compensar?"
💡 Briefs São Consequência da Pirâmide
Briefs bons só existem quando os resumos (Camada 4) estão bem estruturados. Você não pode escrever "R$1,2M em vendas" no brief se a camada de resumos não tiver calculado essa métrica de forma confiável e atualizada.
🔗 Como Cada Camada Alimenta a Próxima
A pirâmide é um fluxo. Cada camada é input obrigatório da próxima. Quando uma camada falha, o sistema pode continuar funcionando — mas entregando resultados errados. Esse é o perigo das falhas silenciosas.
O que quebra quando cada camada falha:
Base falha → tudo falha
Fonte corrompida ou atualização parada. O sistema trabalha com dados de ontem (ou do mês passado) achando que são de hoje.
Auditoria falha → problemas não detectados
Duplicatas não detectadas inflam métricas. Nulos não tratados geram zeros falsos em cálculos de média.
Snippets ruins → agente com modelo mental errado
Agente nunca viu o valor "suspenso" no status, então gera SQL que ignora clientes suspensos em análises de churn.
Resumos errados → decisões erradas
Tabela de resumo mensal calculou receita sem considerar devoluções. Todos os relatórios do mês mostram R$200k a mais do que o real.
🚨 Falha Silenciosa é Pior que Falha Barulhenta
Um sistema que quebra e para pode ser corrigido rapidamente. Um sistema que quebra e continua entregando resultados errados pode causar danos durante semanas. Por isso monitoramento em cada camada não é opcional — é a proteção contra o desastre silencioso.
✅ Resumo do Módulo 1.3
Próximo Módulo:
1.4 — Discreto vs Contínuo: As Lentes de Análise. A distinção que muda o tipo de auditoria e o tipo de pergunta que você consegue responder.