📖 O que é um Data Dictionary
Um Data Dictionary é o documento que descreve cada campo de um dataset com precisão. Não é documentação opcional — em empresas reguladas, é obrigatório por lei. E mesmo onde não é obrigatório, é o que separa dados que um agente consegue usar de dados que um agente vai usar errado.
Por que grandes empresas exigem
Com empresas maiores e times de TI próprios
Com empresas maiores e times de TI proper, você terá um data dictionary — garantido. Em alguns casos, por lei, para fins de compliance. O desafio não é criar do zero, mas entender, consumir e atualizar o que existe.
🗂️ Campos Essenciais do Data Dictionary
Um data dictionary mínimo viável tem 6 colunas. Cada uma elimina uma categoria específica de ambiguidade. Campos ausentes são perguntas que o agente vai responder de forma errada silenciosamente.
Exemplo real de Data Dictionary
| Field Name | Data Type | Format | Field Size | Description | Example |
|---|---|---|---|---|---|
| client_id | INTEGER | — | 10 | Identificador único do cliente no sistema | 10042 |
| client_name | STRING | — | 100 | Nome razão social da empresa cliente | Acme Corp Ltda |
| contract_start | DATE | YYYY-MM-DD | 10 | Data de início do contrato ativo | 2024-03-15 |
| mrr_brl | DECIMAL | R$0.00 | 12,2 | Receita recorrente mensal em reais (sem impostos) | 4500.00 |
| is_active | BOOLEAN | 0/1 | 1 | 1 = contrato ativo, 0 = cancelado ou expirado | 1 |
Field Name
Nome exato do campo no dataset. Snake_case ou camelCase — consistente com o schema real.
Data Type
INTEGER, STRING, DATE, DECIMAL, BOOLEAN. Sem ambiguidade — o tipo exato como o banco armazena.
Format
Para datas: YYYY-MM-DD. Para moeda: R$0.00. Para telefone: (00) 00000-0000. Elimina parsing errado.
🤝 Como Pedir o Data Dictionary ao Cliente
A maioria das PMEs não tem data dictionary. Quando você pede, a resposta típica é "o que é isso?". A abordagem correta: pedido formal como parte do onboarding, e quando não existir, criação conjunta como primeiro entregável.
Como abordar em cada contexto
Enterprise / Regulado
"Para iniciar o projeto, preciso do data dictionary dos sistemas que vamos integrar. Se estiver no Confluence ou SharePoint, acesso de leitura é suficiente. Sem isso, não consigo garantir a qualidade das análises."
PME / Sem documentação
"Vamos criar juntos. Me dá 100 linhas representativas de cada tabela e uma hora com quem conhece os dados. Em 2 horas temos um dicionário funcional que vai melhorar todo o projeto."
Startup / Dados caóticos
"Antes de qualquer análise, vamos fazer um reconhecimento dos dados. Vou usar Claude Code para inferir um dicionário inicial, você valida, e aí começamos."
⚠️ O sinal de alerta mais claro
Se o cliente não sabe que perguntas quer fazer dos dados, não merece usar IA ainda. IA é um luxo para quem tem a casa em ordem. O primeiro trabalho do engenheiro de dados é colocar a casa em ordem — e o data dictionary é a planta da casa.
🤖 Alimentando Claude Code com o Dicionário
Com o data dictionary no contexto, Claude Code transforma de um analisador genérico em um auditor especialista nos seus dados. Cada verificação passa a ser baseada no que os dados deveriam ser — não apenas no que são.
Prompt de auditoria guiada por dicionário
# Prompt para Claude Code
Aqui está o data dictionary do dataset customers.csv:
[cole o dicionário aqui]
Agora audite o arquivo customers.csv verificando:
1. Cada campo existe no dicionário? Algum campo extra não documentado?
2. Os tipos batem? Datas estão no formato YYYY-MM-DD?
3. % de nulos em campos obrigatórios (Field Size > 0, sem nulo previsto)?
4. Valores de is_active são apenas 0 ou 1?
5. mrr_brl tem valores negativos ou zero inesperados?
Gere um relatório de qualidade com: ✓ conformes, ⚠️ alertas, ✗ violações.
O que muda com o dicionário no contexto
Sem dicionário
Claude Code encontra um campo "status" com valores 0, 1, 2, 3. Não sabe o que significa. Relata como "valores numéricos variados".
Com dicionário
Claude Code sabe que "status" deveria ser BOOLEAN (0/1). Encontra valores 2 e 3 → relata como "violação de domínio: valores não previstos no dicionário". Isso é uma descoberta de nível sênior.
✍️ Criando um Data Dictionary do Zero com Claude Code
Quando o dicionário não existe, você não espera o cliente criar. Você usa Claude Code para inferir um dicionário inicial a partir dos dados — e apresenta ao cliente para validação. Em 30 minutos você tem um artefato que levaria dias para criar manualmente.
O prompt de criação de dicionário
# Prompt para Claude Code
Analise as primeiras 100 linhas do arquivo customers.csv e crie um
data dictionary com as seguintes colunas para cada campo:
| Field Name | Data Type | Format | Field Size | Description | Example | % Nulos |
Para Description, infira o significado do campo com base no nome
e nos valores observados. Quando incerto, indique "[A CONFIRMAR]".
Para campos que parecem ser IDs, datas, status ou categorias,
explique o domínio observado (ex: "valores observados: 0, 1, 2").
Gere o resultado em formato Markdown e também em CSV para importação.
Claude Code gera o dicionário inicial
Com 100 linhas representativas, o agente infere tipos, formatos, e descrições prováveis. Campos ambíguos são marcados com [A CONFIRMAR].
Cliente valida em 1 reunião
Você apresenta o dicionário gerado em uma planilha. O cliente confirma, corrige ou completa cada campo [A CONFIRMAR]. Reunião de 1 hora substitui semanas de idas e vindas.
Dicionário validado vira artefato do projeto
O arquivo final é entregue ao cliente, salvo no repositório do projeto, e referenciado em todos os prompts de auditoria. É o ponto de verdade único.
💡 Por que 100 linhas e não o dataset completo
100 linhas representativas são suficientes para inferir tipos e formatos. Jogar 18.000 linhas no contexto apenas para criar um dicionário desperdiça tokens e não melhora a qualidade do resultado. Use amostra representativa — inclua casos de borda se souber onde estão.
📋 Data Dictionary como Contrato
O data dictionary não é apenas documentação técnica. É um contrato formal entre todos os stakeholders: engenheiro, analista, agente de IA, e auditor. Cada campo documentado é uma promessa sobre o dado. Qualquer campo não documentado é ambiguidade explícita.
O que o contrato implica
- → Mudanças no schema devem ser acompanhadas de atualização do dicionário. Sem exceção. Schema v2 sem dicionário v2 é schema incompreensível.
- → Novos campos precisam de aprovação do dicionário antes de ir para produção. O dicionário é o gate de qualidade.
- → Campos deprecados permanecem no dicionário marcados como [DEPRECATED] com a data de remoção prevista.
- → O agente de IA opera apenas dentro dos limites do contrato. Se o agente encontra algo não documentado, ele sinalizacomo anomalia — não tenta interpretar.
✓ Com dicionário como contrato
- • Auditoria automatizada e confiável
- • Mudanças de schema rastreáveis
- • Onboarding de novos engenheiros em horas
- • Agente com contexto completo e preciso
- • Conformidade regulatória documentada
✗ Sem dicionário
- • Cada análise depende de quem "sabe" o que o campo significa
- • Mudanças de schema quebram análises sem aviso
- • Onboarding leva semanas
- • Agente infere e erra silenciosamente
- • Auditoria exige entrevistas manuais
✅ Resumo do Módulo
Próximo Módulo:
3.4 — 💬 Text-to-SQL — Agentes conversando com dados limpos sem jogar milhões de linhas no contexto