📦 Eixo Volume
O primeiro eixo mede a magnitude do dataset. Antes de qualquer análise, você precisa saber com o que está lidando: quantas linhas, colunas, quanto espaço ocupa, quantas tabelas existem. Essa informação determina qual ferramenta usar e quanto tempo vai levar o processamento.
📦 O que medir no Eixo Volume
- •Linhas: COUNT(*) ou len(df) — a unidade básica de escala
- •Colunas: len(df.columns) — complexidade do schema
- •Tamanho em disco: df.memory_usage(deep=True).sum() / 1024**2 MB
- •Número de tabelas: total de arquivos ou tabelas relacionadas no projeto
💡 Dica Prática
Antes de carregar o arquivo inteiro, use pd.read_csv('arquivo.csv', nrows=5) para ver o schema e depois wc -l arquivo.csv no terminal para contar linhas sem carregar nada na memória.
🗂️ Eixo Schema
O Schema é a radiografia estrutural do dataset. Nomes das colunas, tipos de dados declarados vs observados, e percentual de nulos. Um Schema bem auditado revela problemas antes que eles causem falhas em produção.
🗂️ Checklist de Schema
- •Tipos declarados vs observados: coluna "valor" com dtype=object quando deveria ser float64
- •% de nulos por coluna: df.isnull().mean() * 100 — qualquer coluna crítica acima de 5% é alerta
- •Nomes das colunas: espaços, acentos, caracteres especiais quebram queries SQL
- •Colunas duplicadas: mesmo dado em dois campos com nomes diferentes
Thresholds de nulos por tipo de coluna
🔬 Eixo Snippet
O Snippet é a inspeção visual estratégica — 100 linhas escolhidas com critério para revelar o que nenhuma estatística agregada revela: padrões anômalos, formatações inconsistentes, valores claramente errados que passam despercebidos quando você olha só para médias e contagens.
✓ Como amostrar corretamente
- ✓30 linhas do topo (df.head(30))
- ✓40 linhas aleatórias do meio
- ✓15 maiores valores (df.nlargest)
- ✓15 menores valores (df.nsmallest)
✗ O que evitar
- ✗df.sample(100) puro sem critério
- ✗Olhar só as primeiras 5 linhas
- ✗Confiar só em describe() e info()
- ✗Não salvar o snippet para referência futura
💡 Dica Prática
Salve o snippet em snippets/stripe_snippet_100.csv. Quando o engenheiro ou o agente precisar referenciar anomalias detectadas, o arquivo está lá — sem precisar reprocessar o dataset inteiro.
📊 Eixo Distribuição
A Distribuição revela como os dados se comportam estatisticamente. Não basta saber que existe uma coluna "receita" — você precisa saber se vai de $0 a $50.000, se tem outliers de $1M, e quais são as 10 categorias mais frequentes de clientes.
📊 Análise de Distribuição por Tipo
Colunas numéricas:
min, p5, p25, mediana, p75, p95, max — os percentis revelam a forma da distribuição. Uma grande diferença entre mediana e média indica outliers.
Colunas categóricas:
value_counts() com as top 10 categorias e suas frequências. Detecta dominância (90% dos registros numa categoria) e categorias raras que podem ser erros de digitação.
Colunas de data:
min e max (range do período), distribuição mensal (buscar sazonalidade), detecção de datas futuras ou impossíveis (ex: 1900-01-01 é valor default de migração).
🏢 Walkthrough BrightPath Advisory
A BrightPath Advisory é uma consultoria financeira com 5 fontes de dados bagunçadas. Veja como os 4 eixos se aplicam a cada uma — e o que foi encontrado que não seria detectado sem o framework.
Stripe Payments — 18.000 registros
Fonte: export CSV da API do Stripe
Anomalia encontrada: Coluna "description" contém JSON embutido como string — ex: {"invoice_id":"inv_123","client":"Acme Corp","service":"Consultoria"}. Informações críticas de negócio presas dentro de uma string que o pandas lê como texto opaco.
HubSpot Contacts — 12.000 contatos
Fonte: export CSV do CRM
Anomalia encontrada: Headers customizados ("Contact: First Name" em vez de "first_name"), 47% de nulos na coluna "source" (obrigatória no SLA), e mistura de status em inglês e português na coluna "lifecycle_stage".
Time Tracker — 3 abas Excel
Fonte: planilha Excel com 1 aba por consultor
Anomalia encontrada: Cada aba usa um formato de data diferente — Consultor A usa DD/MM/YYYY, Consultor B usa YYYY-MM-DD, Consultor C usa "15 jan 2025" como texto. Impossível juntar sem normalização.
QuickBooks P&L — Arquivos inconsistentes
Fonte: exports mensais do QuickBooks
Anomalia encontrada: Cada mês tem uma estrutura ligeiramente diferente — colunas adicionadas/removidas conforme o contador ajustou o template. Janeiro tem 18 colunas, julho tem 22. Não é possível fazer UNION sem mapear as diferenças primeiro.
Founder Master Tracker — Planilha mestre
Fonte: Google Sheets do fundador
Anomalia encontrada: Mistura de datetime (com hora) e date (só data) na coluna "contract_date". Algumas linhas têm "2025-01-15 14:30:00", outras têm "2025-01-15", outras têm "15/01/2025". Três formatos, uma coluna.
📌 Conclusão do Walkthrough
Em menos de 1 hora de auditoria com os 4 eixos, identificamos: 1 JSON embutido, 1 campo obrigatório com 47% de nulos, 3 formatos de data incompatíveis, 1 schema mutante por mês, e 1 mistura de tipos na coluna de data principal. Sem o framework, cada um desses problemas seria descoberto apenas quando o pipeline quebrasse.
💬 O Prompt Exato para Claude Code
Com o prompt certo, você delega a auditoria completa ao Claude Code e recebe um relatório estruturado dos 4 eixos em minutos. O segredo está nos detalhes de instrução — especialmente a proibição de modificar os dados raw.
💬 Prompt Exato — Copie e Use
# Prompt para auditoria de 4 eixos
Leia o CLAUDE.md e me diga quais são as 5 fontes do projeto BrightPath e o que é incomum em cada uma.
Depois rode um audit pass completo no arquivo raw Stripe payments usando o framework de 4 eixos:
- 1. Volume: total de linhas, colunas e tamanho em MB
- 2. Schema: tipos de dados, % de nulos por coluna, nomes problemáticos
- 3. Snippet: amostra estratificada de 100 linhas (30 topo, 40 aleatório, 30 bordas)
- 4. Distribuição: min/mediana/max dos numéricos, top 10 categorias dos strings
Salve o relatório em audit/stripe_audit.md e o snippet em snippets/stripe_100.csv.
IMPORTANTE: Não modifique nada no diretório raw/. Apenas leia e analise.
O que o prompt faz certo
- ✓Referencia o CLAUDE.md para contexto do projeto
- ✓Especifica a fonte alvo explicitamente
- ✓Declara os 4 eixos com detalhe de cada um
- ✓Define onde salvar cada artefato
- ✓Proíbe modificação dos dados raw
O que o prompt genérico faz errado
- ✗"Analise os dados do Stripe" — sem especificar o quê
- ✗Sem instrução de onde salvar o resultado
- ✗Sem proteção explícita dos dados raw
- ✗Framework implícito — o agente inventa o formato
✅ Resumo do Módulo
Próximo Módulo:
2.2 — A Regra das 100 Linhas: como amostrar para revelar 80% dos problemas