❌ O Conceito de "Wrong Primitive"
Wrong primitive é quando você usa o mecanismo errado para o trabalho. O sistema parece funcionar na superfície — mas falha silenciosamente quando mais importa. É o tipo de erro mais difícil de diagnosticar porque o sintoma está distante da causa.
Exemplos de wrong primitives clássicos
Skill para formatar código — o agente às vezes formata, às vezes não. O correto é uma Regra no CLAUDE.md: "sempre formate o código com Prettier antes de apresentar". Regra é determinística. Skill não é.
Regra para análise exploratória — análise exploratória é contextual, requer julgamento, adapta ao dataset. Uma regra genérica ("sempre analise assim") limita o agente. O correto é um Skill com progressive disclosure.
Skill para gerar relatório diário — relatório diário é uma automação recorrente em horário fixo. O correto é um Script Python agendado via cron, completamente fora do LLM. Sem depender de sessão, sem variabilidade.
⚠️ Por que é tão difícil de diagnosticar
O wrong primitive funciona na maioria dos casos. O problema aparece nos 20% de edge cases — e só quando já está em produção. Um skill que deveria ser um hook vai funcionar 90% das vezes. Nos 10% restantes, vai falhar sem aviso e sem log. A causa: o LLM decidiu não invocar o skill porque o contexto era ligeiramente diferente.
⚖️ Quando Usar Skill vs Regra vs Hook vs Script Python
Cada primitivo tem um domínio claro. A tabela comparativa abaixo é o mapa mental que você vai usar para todas as decisões de arquitetura do seu Agentic OS.
Tabela comparativa dos 4 primitivos
| Primitivo | Natureza | Quando usar | Não usar quando |
|---|---|---|---|
| Skill | Sugestão ao LLM, contextual, pode não disparar | Comportamentos que requerem julgamento e adaptação ao contexto | O comportamento precisa acontecer sempre, sem exceção |
| Regra | Instrução persistente no CLAUDE.md, sempre ativa | Comportamentos invariantes que se aplicam a toda sessão | O comportamento é específico de um contexto ou tarefa |
| Hook | Código shell executado deterministicamente em eventos | Ações que devem ocorrer em eventos específicos do sistema (pré/pós commit, pré-resposta) | A ação requer raciocínio ou adaptação contextual |
| Script Python | Automação fora do LLM, determinística, agendável | Processamento de dados, automações recorrentes, pipelines sem necessidade de LLM | O resultado precisa de linguagem natural ou adaptação |
💡 A pergunta que elimina 30% dos skills desnecessários
Antes de criar qualquer skill, pergunte: "isso é determinístico?"
- → Se sim (mesma entrada = mesma saída sempre) → Hook ou Script Python
- → Se não (resultado varia com contexto) → Skill ou Regra
- → Se sim, mas precisa de contexto de sessão → Regra no CLAUDE.md
🔄 Reverse Meta Prompting
Reverse meta prompting é a técnica de usar o agente para melhorar seus próprios skills. Depois de uma sessão onde algo não funcionou bem, você não apenas corrige manualmente — você instrui o agente a auto-criticar e propor a melhoria.
O prompt de reverse meta prompting
# Após uma sessão problemática:
"Reflita sobre como essa sessão foi. O skill [audit-source] foi usado,
mas ele não capturou o problema de encoding que encontramos.
Por favor:
1. Critique o skill atual contra o que ele falhou hoje
2. Proponha uma edição concreta ao skill que previniria essa falha
3. Me mostre o diff entre o skill atual e a versão proposta
4. Explique por que essa mudança melhora a cobertura"
O agente vai analisar sua própria performance, identificar lacunas na cobertura do skill, e propor adições específicas — como adicionar "## Quando arquivo tem problemas de encoding:" à seção de progressive disclosure.
💡 1% de melhoria por dia
Melhore o skill 1% por dia. Em 30 dias, você terá um skill iron-clad. Não tente refatorar o skill completo de uma vez — pequenas melhorias incrementais depois de cada sessão onde algo falhou. O skill fica mais robusto organicamente, cobrindo edge cases reais, não hipotéticos.
🧪 O Teste "Run It Cold"
O teste cold é simples e brutal: abra uma nova sessão sem qualquer contexto pré-carregado, envie o prompt que deveria disparar o skill, e observe se o skill é acionado corretamente. Se não disparar — a descrição precisa de mais triggers.
Por que o cold test é fundamental
Contexto de desenvolvimento
Você está na mesma sessão onde criou o skill. O agente tem contexto da criação. Vai disparar o skill com mais facilidade. O teste parece funcionar — mas é um ambiente artificial.
Contexto de produção (cold)
Sessão nova, sem contexto. O agente decide baseado apenas na descrição do skill e no prompt do usuário. Se a descrição for fraca, o skill não dispara. Esse é o cenário real.
Feche todas as sessões abertas
Garanta que não há contexto residual de sessões anteriores que possa influenciar o teste.
Envie o prompt que deveria disparar o skill
Use variações naturais da instrução — como um usuário real escreveria, não como você descreveu no skill.
Observe o comportamento sem intervenção
Não ajude o agente. Se ele não disparou o skill, a descrição precisa melhorar. Se disparou, registre quais prompts funcionaram.
Itere na descrição do skill
Adicione os prompts que falharam como exemplos na descrição do skill. "Exemplos que devem disparar este skill: [lista de prompts reais que falharam]"
⚡ Skill como Sugestão vs Hook como Regra Determinística
A distinção entre skill e hook é a mais crítica para comportamentos que precisam acontecer sempre. Um skill pode ser ignorado. Um hook não pode. Para segurança, compliance, e formatação obrigatória — hooks são a resposta correta.
Skill — sugestão probabilística
- →O LLM decide se invoca baseado no contexto
- →Pode ser ignorado se o contexto for ambíguo
- →Não tem garantia de execução
- →Ideal: comportamentos adaptativos e contextuais
- →Ex: "quando analisar dados, siga este checklist"
Hook — garantia determinística
- →Código shell executado no evento configurado
- →Não depende de decisão do LLM
- →Sempre executa, sem exceção
- →Ideal: validações, formatação, logging obrigatórios
- →Ex: validação de schema antes de cada commit
Casos de uso reais de hooks em Engenharia de Dados
- • Pre-commit hook: Verificar se o script Python passa no linter antes de commitar para o repositório
- • Pre-tool hook: Registrar em log toda vez que Claude Code escreve em um arquivo de dados
- • Post-response hook: Notificar o Slack quando uma auditoria é concluída
- • Pre-response hook: Verificar se a resposta contém PII antes de apresentar ao usuário
🔍 Auditando Seu Stack Atual
Todo stack acumula wrong primitives com o tempo. A auditoria periódica — idealmente mensal — é o que mantém o sistema saudável. Um stack auditado regularmente é mais confiável, mais rápido, e mais fácil de expandir.
O processo de auditoria em 5 etapas
Inventário completo
Liste todos os skills, regras, hooks e scripts. Para cada um: nome, o que faz, quando foi criado, quando foi usado pela última vez.
Pergunta de primitivo para cada item
"Este é o primitivo correto?" Se não — identifique qual deveria ser e por quê.
Identificar itens obsoletos
Skills que não foram usados nos últimos 30 dias são candidatos à remoção. Pergunte: ainda é necessário? Se não — delete.
Migrar wrong primitives
Para cada wrong primitive identificado: criar o primitivo correto, migrar o comportamento, validar com cold test, deletar o original.
Documentar as decisões
Registre o que foi removido e por quê. Facilita o próximo ciclo de auditoria e evita recriar o que foi deliberadamente deletado.
💡 Saúde do stack como métrica
Trate a saúde do stack como uma métrica real: número de skills, taxa de disparo correto (estimada via cold tests), número de wrong primitives identificados, e tempo desde a última auditoria. Um stack saudável tem: menos de 10 skills, >85% de taxa de disparo correto, e foi auditado nos últimos 30 dias.
✅ Resumo do Módulo
Próximo Módulo:
3.6 — 🏢 Enterprise vs PME — Migrações, SOC 2 e Big Data real: o que muda quando o cliente é enterprise