Como fazer o Claude auditar contas de anúncios com segurança em 12 plataformas

Confiar em modelos de linguagem com tarefas de produção é sempre um pouco assustador. Quando se trata de orçamentos de publicidade, o medo aumenta dez vezes. Um movimento errado de um agente na API da plataforma de anúncios, e o orçamento de um mês vai para o direcionamento errado em poucas horas. É por isso que a maioria das equipes ainda copia os exports manualmente e os alimenta em interfaces web de chatbots, obtendo conselhos vagos sem números concretos em troca.

Recentemente encontrei um repositório open-source claude-ads. O autor tentou construir um sistema de engenharia rigoroso sobre as capacidades de agente do Claude Code. A ideia é transformar o Claude em um assistente supervisionado de marketing de performance com proteções rígidas, segurança de tipos e verificações determinísticas.

Por Trás dos Panos

O projeto é uma coleção de skills e ferramentas CLI escritas em Python. Você pode trabalhar com ele através do Claude Code, Cursor, Windsurf, Gemini ou Codex. O foco principal aqui é em segurança de dados e previsibilidade.

O sistema suporta 12 plataformas de publicidade:

• Redes de busca e sociais: Google Ads, Meta Ads, YouTube Ads, LinkedIn Ads, TikTok Ads, Microsoft Advertising, Reddit Ads, Snapchat Ads, X Ads.
• E-commerce e retail media: Apple Ads, Amazon Ads, Pinterest Ads.

Em vez de dar ao modelo total liberdade através de chamadas de ferramentas descontroladas, o projeto divide o fluxo de trabalho em estágios isolados.

Segurança e Proteção Contra Cobranças Acidentais

A arquitetura do claude-ads é executada em modo somente leitura por padrão. Você pode executar auditorias, construir hipóteses, gerar cópias de anúncios e analisar métricas sem correr o risco de quebrar campanhas ativas.

Se a otimização precisar ser aplicada, o sistema exige passar por vários níveis de verificação:

• IDs de conta e objetos são explicitamente especificados.
• Um diff claro do estado antes e depois das alterações é gerado com avaliação da zona de impacto.
• Limites rígidos de orçamento são definidos que o agente fundamentalmente não pode exceder.
• Para cada solicitação de escrita, uma chave de idempotência e um plano de rollback das alterações são gerados.

Operações completas de exclusão de entidades são simplesmente removidas do código na versão dois. Credenciais de API não terminam no contexto do modelo, relatórios ou histórico git: são lidas exclusivamente de variáveis de ambiente ou do secrets store do sistema.

Arquitetura e Avaliação de Qualidade de Campanhas

Dentro do repositório, tudo é dividido em níveis claros de responsabilidade.

Um único processo condutor aceita comandos do usuário, define limites de escopo e distribui tarefas para workers isolados. Cada worker é responsável por uma peça específica de análise e produz JSON estrito de acordo com um schema. Se um dos workers necessários falhar com um erro, toda a execução é marcada como parcial. O sistema não vai mascarar a falha e apresentar um relatório incompleto como um resultado finalizado.

A saída canônica é versionada, JSON validado. A partir disso, a utilidade monta resumos em Markdown, páginas HTML ou PDFs via WeasyPrint.

O scoring de saúde da conta de anúncios é projetado de forma interessante. Cada verificação tem um status de pass, fail, unknown ou not_applicable. A completude dos dados coletados é avaliada separadamente do score de saúde geral:

• Se 80% ou mais das verificações são cobertas, um score completo é atribuído.
• Com 60% a 79% de cobertura, o score é considerado preliminar.
• Se os dados são menores que 60%, o scoring não é calculado de todo devido a evidências insuficientes.
• Features beta e features indisponíveis da plataforma são excluídas dos cálculos para evitar baixar a avaliação.

Como é Trabalhar com a Ferramenta

A instalação no Claude Code é feita através do gerenciador de plugins:

/plugin marketplace add AgriciDaniel/claude-ads
/plugin install claude-ads@ai-marketing-hub-claude-ads

Se você prefere instalação local ou usa outros ambientes:

git clone https://github.com/AgriciDaniel/claude-ads.git
cd claude-ads
bash install.sh --source=local

O instalador suporta Python 3.11 e 3.12 no Linux, macOS e Windows. Se bibliotecas do sistema estiverem faltando, o script falhará com um erro antes de fazer qualquer alteração.

Após a instalação, a interação é construída em torno de comandos slash. Por exemplo:

• /ads setup configura o perfil do cliente, KPIs alvo, limites de orçamento aceitáveis e regras de privacidade.
• /ads audit all executa uma auditoria completa dos canais conectados com cada saída vinculada a métricas datadas.
• /ads plan calcula distribuição de orçamento, plano de mídia e plano de teste dividido.
• /ads optimize --draft prepara um rascunho de alterações de lance e criativos sem aplicá-los na plataforma.
• /ads report gera o relatório estruturado final.

Atalhos diretos para contas específicas também funcionam: /ads google, /ads meta, /ads reddit.

Para Quem o Projeto Será Útil

O repositório provavelmente não será necessário para alguém executando um único anúncio com um orçamento de alguns milhares de rublos. Mas se sua empresa executa publicidade em múltiplas plataformas ou você está construindo automação interna para uma agência, há muito o que explorar aqui.

Mesmo que você não use a ferramenta completa, o código-fonte claude_ads_core e a estrutura de diretórios control-plane/ fornecem um exemplo sólido de como projetar skills confiáveis para LLMs. Em vez de prompts de texto caóticos, o autor implementou contratos de dados, schemas de validação e gates de confirmação obrigatórios do operador. O repositório tem uma licença aberta (MIT), então você pode livremente dividir o código em seus próprios módulos.