🏗️ Visão Avançada

Skill sprawl é quando você acumula dezenas de skills sem critério, cada uma fazendo algo ligeiramente diferente. O resultado: o LLM não sabe qual usar, dispara a errada, ou ignora skills que deveriam ser acionadas.

Menos skills melhora a precisão do disparo, reduz o ruído no contexto e torna o sistema mais previsível. Um Agentic OS com 5 skills bem definidas supera um com 20 mal definidas.

Skill sprawl, área de superfície, sobreposição funcional, canibalização de triggers, cobertura com mínimo de skills.

Progressive disclosure é a técnica de organizar um skill em seções internas (## Quando analisando receita:, ## Quando inspecionando schema:) para que um único skill cubra múltiplos casos sem explodir em tamanho.

Permite consolidar 3-4 skills sobrepostos em 1, mantendo clareza contextual. O LLM lê apenas a seção relevante para o momento, reduzindo confusão.

Seções com ##, contexto condicional, skill unificado, cobertura sem redundância, headers semânticos.

Um skill com nome genérico (analysis) compete com muitos outros. Um skill com nome único (audit-source) e descrição cheia de triggers ("Use quando o usuário pedir para inspecionar, auditar, verificar, checar...") dispara com precisão cirúrgica.

A descrição do skill é o que o LLM usa para decidir se aciona ou não. Quanto mais rica em sinônimos e exemplos de uso, maior a taxa de disparo correto.

Trigger words, sinônimos, exemplos concretos de uso, nome memorável, descrição como contrato de disparo.

O processo de identificar skills com funcionalidade sobreposta (audit-csv, audit-excel, audit-source) e uni-los em um único skill com seções internas que distinguem o comportamento por tipo de entrada.

Se você tem dois skills com nomes parecidos, as funcionalidades provavelmente se sobrepõem. Consolidar elimina ambiguidade, reduz o número de skills para gerenciar e melhora a manutenção.

Mapeamento de sobreposição, union de skills, seções condicionais, antes/depois da consolidação.

Antes de um skill ir para produção, você o testa com sub-agentes em paralelo: múltiplas instâncias recebem prompts diferentes para verificar se o skill dispara nos momentos certos e se mantém em silêncio quando não deve.

Um skill que dispara na hora errada é pior que não ter skill. O teste paralelo expõe falsos positivos e negativos antes que causem dano em produção.

Run cold test, sub-agentes paralelos, matriz de disparo, falso positivo, falso negativo, cobertura de casos limite.

O processo lean-down completo: inventário → mapeamento de sobreposição → consolidação → reescrita com progressive disclosure → adição de 3 regras CLAUDE.md para cobrir casos que não precisam de skill → teste e validação.

Menos é mais. Mesma cobertura com um terço da área de superfície. O resultado final é um Agentic OS mais rápido, preciso e fácil de manter.

Inventário de skills, mapa de sobreposição, consolidação, 3 regras essenciais, ciclo de refinamento, lean operating system.

O primeiro critério para decidir se um sistema vale a pena é simples: essa pergunta vai ser feita mais de uma vez? Se for uma análise única para um board report, um script basta. Se for recorrente, um sistema começa a fazer sentido.

A maioria dos sistemas prematuros nasce de respostas erradas a essa pergunta. Saber identificar o que é one-off vs recorrente poupa semanas de trabalho desnecessário.

One-off vs recorrente, valor da automação, custo de oportunidade, threshold de recorrência.

Um sistema rígido que não consegue evoluir com o negócio vira dívida técnica rapidamente. Se a lógica que o sistema implementa muda frequentemente, talvez um script manual seja mais adequado até o modelo estabilizar.

Construir um sistema antes de entender os requisitos definitivos é o caminho mais rápido para refazer tudo em 3 meses. A evolução do negócio deve guiar a decisão de automatizar.

Estabilidade de requisitos, ciclo de vida do sistema, dívida técnica, custo de mudança, YAGNI (you ain't gonna need it).

Quando múltiplas pessoas (ou múltiplos agentes) precisam da mesma funcionalidade, o custo de construir um sistema se distribui e o ROI aumenta. Um sistema para uso solo raramente justifica sua complexidade.

Escala de uso é o multiplicador de valor de qualquer sistema. Entender quem vai usar, com que frequência, justifica ou derruba a decisão de construir.

Número de usuários, frequência de uso, ROI de sistema, custo fixo vs custo marginal, justificativa de automação.

Um sistema construído antes do momento certo aumenta a complexidade sem entregar valor proporcional. A equação é brutal: maior complexidade → menos velocidade de mudança → menor valor entregue.

Startups morrem por over-engineering tanto quanto por falta de produto. Entender o custo real de cada sistema premature é essencial para sobreviver na fase inicial.

Over-engineering, complexidade acidental, velocity de desenvolvimento, custo de manutenção, morte por mil sistemas.

Um script Python de 50 linhas que resolve o problema certo, agora, é mais valioso do que um sistema de 5000 linhas que resolve um problema hipotético futuro. Scripts são descartáveis por design — e isso é uma vantagem.

Existe um estigma cultural de que scripts são "solução de amador". Na realidade, 80% dos problemas de dados em empresas podem ser resolvidos com scripts bem escritos e não precisam de sistemas.

Script vs sistema, solução descartável, time-to-value, pragmatismo técnico, 80% dos casos.

A árvore de decisão completa: resposta única → script / resposta recorrente por 1 pessoa → skill ou regra / recorrente por muitos → sistema / precisa de UI → sistema com frontend / precisa de histórico → banco de dados.

Ter um framework explícito de decisão evita que cada novo pedido vire um projeto de engenharia. 20% das perguntas são únicas, 80% são recorrentes — saber separar é a habilidade mais valiosa do engenheiro.

Decision tree, primitivo correto, escalada de complexidade, 20/80 das perguntas, mínimo viável de automação.

Um Data Dictionary é um documento que descreve cada campo de um dataset: nome, tipo, formato, tamanho, descrição e exemplos. É o vocabulário compartilhado entre engenheiros, analistas e agentes de IA sobre o que cada dado significa.

Com empresas maiores e times de TI próprios, você terá um data dictionary — garantido. Em alguns casos, por lei, para fins de compliance. Saber criá-lo e consumi-lo é habilidade obrigatória.

Metadados, compliance, vocabulário de dados, contratos de schema, documentação viva, LGPD e data governance.

Um data dictionary mínimo viável tem 6 colunas: Field Name (nome do campo), Data Type (tipo: string, integer, date), Format (formato: YYYY-MM-DD, R$0.00), Field Size (tamanho máximo), Description (o que o campo representa) e Example (um valor real do campo).

Cada campo ausente no dicionário é uma fonte de ambiguidade para o agente. Quanto mais completo o dicionário, mais precisa a auditoria e mais confiável o Text-to-SQL gerado.

Field Name, Data Type, Format, Field Size, Description, Example, completude do dicionário.

A maioria das PMEs não tem data dictionary. A abordagem correta: pedir formalmente como parte do onboarding do projeto, e quando não existir, criá-lo com Claude Code como primeiro entregável — não como trabalho extra, mas como pré-requisito.

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. Criar o dicionário junto ao cliente é o primeiro passo para colocar a casa em ordem.

Onboarding de dados, entregável de dicionário, descoberta de dados, perguntas de negócio, pré-requisito de IA.

Com o data dictionary no contexto, Claude Code consegue verificar se cada campo do dataset real corresponde ao que o dicionário promete: tipo correto, formato válido, tamanho dentro do limite, ausência de nulos onde não deveria haver.

Um agente sem dicionário audita no escuro. Um agente com dicionário audita com o mapa completo — e entrega relatórios de qualidade que um analista júnior levaria dias para produzir.

Auditoria guiada por dicionário, validação de schema, relatório de qualidade, discrepâncias, compliance de dados.

Quando o dicionário não existe, você alimenta 100 linhas representativas do dataset ao Claude Code com um prompt específico: "Analise este dataset e crie um data dictionary com: nome do campo, tipo inferido, formato, % de nulos, e uma descrição do que o campo parece representar."

Criar do zero manualmente levaria horas. Com Claude Code, é uma tarefa de minutos. O resultado é um dicionário inicial que o cliente pode revisar e validar, acelerando o processo de onboarding em 10x.

Inferência de schema, prompt de criação de dicionário, validação com cliente, dicionário como artefato de projeto.

O data dictionary não é apenas documentação — é um contrato formal entre o engenheiro que descreve os dados e o agente que os consome. Qualquer campo não documentado é ambiguidade explícita e risco de erro silencioso.

Ao tratar o dicionário como contrato, você cria um ponto de verdade único para todos: engenheiros, analistas, agentes de IA e auditores. Mudanças no schema passam a ser mudanças no contrato — visíveis e rastreáveis.

Contrato de dados, ponto de verdade único, rastreabilidade de mudanças, ambiguidade zero, governance.

Text-to-SQL é a capacidade de um agente de IA transformar uma pergunta em linguagem natural em uma query SQL válida. O usuário pergunta "qual foi minha receita no Q3?" e o agente escreve e executa o SQL que responde isso.

É a interface mais natural entre executivos não-técnicos e dados estruturados. Mas é inútil sobre dados sujos: o agente vai responder com convicção sobre mentiras, sem saber que está errado.

Linguagem natural, SQL gerado, pré-requisito de dados limpos, respostas confiantes sobre dados errados, GIGO (garbage in, garbage out).

A arquitetura completa: usuário faz pergunta em linguagem natural → agente gera SQL → DuckDB executa a query no arquivo de dados local → resultado limpo (geralmente 5-20 linhas) → agente formula resposta em linguagem natural.

Entender cada camada permite depurar quando algo falha. O SQL gerado pode ser inspecionado, corrigido e reutilizado. A separação entre geração de SQL e execução dá controle total sobre o que está sendo feito.

Pipeline Text-to-SQL, DuckDB, execução local, inspeção de SQL, camadas separadas, auditabilidade.

Você não joga 18.000 linhas no contexto. Você pede ao agente para escrever o SQL, e o DuckDB retorna as 5 linhas que importam. O contexto recebe o resultado compacto — não o dataset bruto. Isso é eficiência de contexto.

Contexto é caro e limitado. Jogar dados brutos no contexto degrada a qualidade das respostas, aumenta o custo por query e inviabiliza datasets grandes. SQL é o filtro que mantém o contexto limpo.

Eficiência de contexto, SQL como filtro, dados comprimidos, custo de tokens, window de contexto, escala de dados.

Antes de qualquer Text-to-SQL, você executa o prompt de auditoria completo nos dados. Só após validar que os dados estão limpos, consistentes e documentados no data dictionary, você libera o agente para responder perguntas.

Text-to-SQL sobre dados sujos = respostas confiantes sobre mentiras. O agente não vai saber que o dado está errado. Vai responder com convicção. A auditoria prévia é a única proteção contra isso.

Auditoria prévia, gate de qualidade, dados limpos como pré-requisito, pipeline de validação, confiança calibrada.

Exemplo real: "Load all four CSVs into DuckDB engagement.duckdb. Run a query that returns the top 5 clients by revenue." O agente escreve o SQL, o DuckDB executa, o resultado de 5 linhas volta para o contexto. Tudo em segundos, sem jogar nada no contexto.

Ver exemplos reais desmistifica o Text-to-SQL. Ele não é mágica — é uma pipeline bem definida. Entender o exemplo permite replicar para qualquer pergunta de negócio.

Exemplo concreto, pipeline real, prompt para DuckDB, resultado compacto, replicabilidade, perguntas de negócio.

Text-to-SQL tem limites: não funciona bem com dados não-estruturados, falha em queries de múltiplos joins complexos, e não é adequado quando a pergunta requer raciocínio que vai além do SQL. Nesses casos, outras arquiteturas (RAG, pipelines Python, etc.) são mais adequadas.

Conhecer os limites evita usar a ferramenta errada. Text-to-SQL é poderoso dentro do seu domínio, mas fora dele, você precisa de outra abordagem — e saber quando escalar é tão importante quanto saber quando usar.

Limites de SQL, dados não-estruturados, complexidade de joins, RAG, escalada de arquitetura, reconhecimento de limite.

Wrong primitive é quando você usa um skill para algo que deveria ser um hook, ou uma regra para algo que precisaria de um script. O sistema parece funcionar — até que falha silenciosamente em produção, e você não sabe por quê.

É o erro mais difícil de diagnosticar porque o sintoma (comportamento inesperado) está distante da causa (primitivo errado). Aprender a reconhecer wrong primitives economiza horas de debugging.

Wrong primitive, falha silenciosa, diagnóstico de causa raiz, comportamento esperado vs observado, primitivos de stack.

Skill: sugestão ao LLM, flexível, contextual, pode não disparar. Regra (CLAUDE.md): instrução persistente, sempre ativa, para comportamentos invariantes. Hook: código shell executado deterministicamente em eventos do sistema. Script Python: automação fora do LLM, determinística, para processamento de dados.

Cada primitivo tem trade-offs claros. Escolher errado não apenas não resolve — às vezes piora o problema. Ter um mapa mental dos 4 primitivos elimina 80% das decisões de arquitetura.

Skill como sugestão, regra como lei, hook como gatilho determinístico, script como pipeline, tabela comparativa, trade-offs.

Depois de uma sessão onde o agente não performou bem, você instrui: "Reflita sobre como essa sessão foi. Critique o skill contra o que ele errou, proponha uma edição concreta ao skill e me mostre a diferença." O agente melhora seu próprio skill.

Melhore o skill 1% por dia. Em 30 dias, você terá um skill iron-clad. Reverse meta prompting é o mecanismo de melhoria contínua mais poderoso disponível — e é grátis.

Meta prompting, auto-critique, melhoria incremental, diff de skill, ciclo de feedback, 1% ao dia.

Run it cold: abrir uma nova sessão sem contexto pré-carregado e enviar o prompt que deveria disparar o skill. Se o skill dispara corretamente sem dicas extras — passou. Se não dispara, a descrição do skill precisa de mais trigger words.

Na produção, o LLM não tem o contexto da sessão de desenvolvimento. O teste cold simula exatamente as condições reais, revelando falsos negativos antes que causem problemas.

Cold start, sessão limpa, condições de produção, falso negativo, threshold de disparo, validação de trigger.

Um skill é uma sugestão — o LLM pode ignorá-lo se julgar irrelevante. Um hook é código shell que roda deterministicamente no evento configurado — não tem como ignorar. Para comportamentos críticos, use hook. Para comportamentos contextuais, use skill.

Pergunta antes de criar qualquer skill: isso é determinístico? Se sim, um hook ou script Python é mais confiável do que uma sugestão a um LLM. Esta pergunta elimina 30% dos skills desnecessários.

Sugestão vs comando, determinístico vs probabilístico, hook events, confiabilidade, cenários críticos.

O processo de auditoria do stack existente: listar todos os skills, regras, hooks e scripts → para cada um, perguntar "este é o primitivo correto?" → identificar wrong primitives → migrar para o primitivo adequado.

Todo stack acumula wrong primitives com o tempo. A auditoria periódica é o que mantém o sistema performático. Um stack auditado regularmente é mais confiável e mais fácil de expandir.

Auditoria de stack, inventário de primitivos, migração de primitivo, manutenção preventiva, saúde do sistema.

Startup: Google Sheets, CSVs, sem estrutura, simplicidade máxima. PME com funding: cresceu de 100 para 1000 funcionários, os dados refletem o caos do crescimento — inconsistências, sistemas diferentes em cada departamento. Enterprise: Oracle, SAP, equipes de TI, compliance, dados regulatórios.

A abordagem de engenharia muda radicalmente em cada estágio. Tratar um enterprise como startup resulta em caos. Tratar uma startup como enterprise paralisa o negócio com over-engineering.

Maturidade de dados, estágio da empresa, sistemas por estágio, caos de crescimento, enterprise-grade.

Migrações de sistemas legados são os projetos mais complexos e arriscados de dados. Oracle e SAP têm esquemas proprietários, décadas de customizações, e dados que refletem regras de negócio não documentadas. Migrar é arqueologia e engenharia ao mesmo tempo.

A maioria das empresas enterprise tem pelo menos um sistema legado que "não pode parar". Saber navegar migrações sem quebrar operações críticas é uma habilidade de nível sênior altamente valorizada.

Sistema legado, migração incremental, shadow mode, rollback plan, mapeamento de schema, regras de negócio implícitas.

SOC 2 é um framework de auditoria de segurança que certifica como uma empresa gerencia dados de clientes. Empresas que foram de não-compliance para SOC 2 terão dados drasticamente diferentes antes e depois. Essa transição aparece nos dados de forma clara.

Clientes enterprise B2B geralmente exigem SOC 2 dos fornecedores. Entender o que SOC 2 implica para dados (logging, access control, audit trails) prepara o engenheiro para trabalhar nesse ambiente.

SOC 2, audit trail, access control, logging de dados, compliance enterprise, certificação de segurança.

Apache Spark é um framework de processamento distribuído para volumes que não cabem em memória de uma única máquina. Para a Coca-Cola com 10 bilhões de linhas, Spark é obrigatório. Para 99% dos projetos, DuckDB resolve com muito menos custo e complexidade.

Mergulhe em Apache Spark apenas se o volume exigir. É intimidador, finicky, e caro de operar. Saber reconhecer quando Spark é necessário evita o erro de usá-lo prematuramente — ou de não usá-lo quando é o único que resolve.

Processamento distribuído, volume threshold, Spark vs DuckDB, custo operacional, escala real de Big Data.

NoSQL surgiu quando chatbots e apps web precisavam de schemas que evoluíam sem aviso. É o YOLO de dados — cresce conforme os dados crescem. SQL domina quando o schema é estável e você precisa de joins, transações e consistência. A maioria dos projetos de dados analíticos usa SQL.

Muitas empresas usam NoSQL (MongoDB, DynamoDB) para aplicações transacionais e SQL para analytics. O engenheiro de dados geralmente lida com os dois — e precisa saber quando um dado deve migrar de NoSQL para SQL.

Schema flexível vs rígido, MongoDB, DynamoDB, PostgreSQL, analytics vs OLTP, migração de NoSQL para SQL.

Seu primeiro projeto enterprise: reuniões de alinhamento antes de tocar em qualquer dado, acesso a sistemas controlado por tickets, documentação obrigatória de tudo, aprovações em múltiplos níveis, e dados de uma qualidade muito melhor do que em startups — porque tem time dedicado.

O choque cultural de quem vem de startups é real. Processos que parecem burocracia excessiva existem por razões legítimas de segurança e compliance. Entender isso acelera a adaptação e evita atritos desnecessários.

Onboarding enterprise, controle de acesso, approval workflows, documentação mandatória, cultura de processos, choque cultural.