Instalacao e Setup

Pre-requisitos

• Windows 10/11
• Conexao com internet
• Conta Google Ads e/ou Meta Ads com acesso de API

Passo 1 — Instalar programas base

Execute instalar.bat como administrador (clique direito > Executar como administrador).

Programa	Para que serve
Python 3.11+	Executar scripts de API
VS Code	Editor com Claude Code integrado
Git	Controle de versao

Passo 2 — Criar workspace

python setup_bootcamp.py

O script extrai 26 arquivos, verifica o ambiente, instala dependencias Python e confirma a estrutura.

Passo 3 — Configurar APIs

/configurar-ambiente

Wizard interativo que conecta Google Ads, Meta Ads ou ambas.

Passo 4 — Primeiro diagnostico

/diagnostico-conta

Se tudo estiver conectado, voce vera: gasto, leads, CPL, campanhas ativas e alertas.

Estrutura do Workspace

Seu Workspace/
├── CLAUDE.md                     ← config + IDs
├── credentials/
│   ├── google-ads.yaml           ← OAuth2 Google Ads
│   ├── meta.env                  ← Token Meta Ads
│   └── test_connection.py        ← testa conexao
├── reports/
│   ├── STYLE-GUIDE.md            ← padrao visual
│   └── templates/                ← templates HTML
├── prompts/                      ← prompts de referencia
├── google-ads/lib/               ← scripts Google
├── meta-ads/lib/                 ← scripts Meta
├── system-prompts/
│   ├── agents/                   ← 3 agentes IA
│   └── frameworks/               ← framework PPC
└── .claude/commands/             ← 7 skills

Arquivos-chave

Arquivo	Funcao	Voce edita?
CLAUDE.md	Configuracao central — IDs, skills, padroes	Automaticamente
credentials/google-ads.yaml	Token OAuth2 do Google Ads	1x no setup
credentials/meta.env	Token de acesso do Meta Ads	Renovar periodicamente
reports/STYLE-GUIDE.md	Padrao visual para relatorios HTML	Nao (referencia)

Fluxo de Trabalho Diario

Manha:
  /diagnostico-conta          → ver estado atual

Analise semanal:
  /gerar-relatorio-meta       → dashboard Meta Ads + IG
  /gerar-relatorio            → dashboard Google Ads
  /analise-reels-organico     → analise de Reels + roteiros

Otimizacao:
  Agente de auditoria         → encontrar desperdicio
  Agente de negativas         → limpar search terms
  Agente de copy              → criar headlines RSA

Decisao:
  Framework PPC               → converte? e lucrativo? escala?

Skills (Comandos)

Skills sao comandos que voce executa no Claude Code digitando /nome-do-comando.

Comando	Quando usar	O que faz
/configurar-ambiente	1x por cliente	Wizard: conecta APIs, gera tokens, atualiza CLAUDE.md
/conectar-google	Renovar token	Valida OAuth2, testa conexao, lista contas
/conectar-meta	Renovar token	Valida token, lista ad accounts, verifica permissoes
/diagnostico-conta	Check diario	Puxa gasto, leads, CPL, campanhas ativas, alertas
/gerar-relatorio	Semanal/mensal	Dashboard HTML completo (Google, Meta ou ambos)
/gerar-relatorio-meta	Semanal/mensal	Dashboard Meta Ads + Instagram organico
/analise-reels-organico	Semanal	Analise de Reels: ranking, padroes, roteiros, dashboard

Como usar

1. Abra o Claude Code no VS Code
2. Digite / seguido do nome do comando
3. Responda as perguntas que o Claude fizer
4. O comando executa automaticamente

Agentes Especializados

Agentes sao prompts pre-configurados em system-prompts/agents/.

Agente de Auditoria

Quando usar: revisao mensal, onboarding de cliente novo, suspeita de desperdicio.

Analisa: visao geral da conta, campanhas, keywords, search terms, quick wins.

Leia o agente em system-prompts/agents/agente-auditoria.md
e faca uma auditoria da conta [cliente]

Agente de Copy (RSA)

Quando usar: criar anuncios novos, melhorar CTR.

Gera: 15 headlines + 4 descricoes com variacao de estrutura.

Leia o agente em system-prompts/agents/agente-copy-anuncios.md
e crie anuncios RSA para [campanha/produto]

Agente de Negativas

Quando usar: semanal, apos ativar campanha nova.

Analisa search terms, categoriza e gera listas de negativas.

Leia o agente em system-prompts/agents/agente-negativas.md
e analise os search terms de [cliente]

Relatorios e Dashboards

Todos os relatorios sao HTML interativos com toggle dark/light, graficos Chart.js e design responsivo.

Tipo	Skill	Conteudo
Dashboard Google Ads	/gerar-relatorio	Campanhas, keywords, QS, search terms
Dashboard Meta Ads	/gerar-relatorio-meta	Campanhas, ad sets, criativos, IG organico
Dashboard Unificado	/gerar-relatorio	Google + Meta combinados
Analise de Reels	/analise-reels-organico	Ranking, padroes, boost, roteiros

Analise de Reels Organicos

Metricas coletadas da API

Metrica	Campo API
Alcance	reach
Salvamentos	saved
Compartilhamentos	shares
Watch time medio	ig_reels_avg_watch_time
Curtidas	like_count
Comentarios	comments_count

Formulas

Engagement Rate  = (likes + comments + shares + saves) / reach * 100
Watch Time (s)   = ig_reels_avg_watch_time / 1000
Coef. Viralidade = shares / reach * 100 (> 4% = viral)

Classificacao

Badge	Criterio	Cor
TOP	Melhor Reel do periodo	Amber
ALTO	Eng rate > media + 20%	Verde
MEDIO	Dentro de +-20% da media	Azul
BAIXO	Eng rate < media - 30%	Vermelho

As 6 secoes da analise

1. Coleta de Dados — puxa N Reels via API
2. Analise de Performance — classifica e rankeia
3. Identificacao de Padroes — o que funciona vs. nao funciona
4. Recomendacao de Impulsionamento — quais Reels pagar
5. Sugestao de 3 Novos Reels — roteiros baseados em padroes
6. Copy para Cada Reel — legenda + hashtags + capa

Framework de Decisao PPC

Cadeia de Alinhamento

Intencao de Busca → Keyword → Anuncio → Landing Page → Conversao

Se qualquer elo estiver desalinhado, a performance cai.

Hierarquia de Lucratividade

Avalie NESTA ORDEM:

#	Pergunta	Metricas
1	Esta convertendo?	Taxa de conversao, volume
2	E lucrativo?	CPA vs. meta, ROAS vs. meta
3	E escalavel?	Impression share, margem de orcamento
4	E eficiente?	Quality Score, CTR, gasto desperdicado

Regra: Nao otimize eficiencia (#4) antes de resolver lucratividade (#2).

Arquivos de Referencia

Preciso de...	Arquivo
IDs de conta e config	CLAUDE.md
Padrao visual	reports/STYLE-GUIDE.md
Template HTML de Reels	reports/templates/analise-reels-organicos-template.html
Framework de decisao	system-prompts/frameworks/framework-trafego-pago.md
Helper Meta	meta-ads/lib/meta_client.py

Credenciais

Plataforma	Arquivo	Validade
Google Ads	credentials/google-ads.yaml	~6 meses
Meta Ads	credentials/meta.env	1h (user) / 60d (system user)

Recomendacao: Use System User Token no Meta para evitar renovacoes constantes.

/configurar-ambiente

Quando usar: primeira vez com um cliente novo, ou ao reconectar APIs.

O que faz

1. Pergunta qual plataforma: Google Ads, Meta Ads, ou ambas
2. Verifica se credenciais existem
3. Guia passo-a-passo para obter tokens
4. Testa conexao com as APIs
5. Cria estrutura do cliente em clients/{slug}/
6. Atualiza CLAUDE.md com IDs da conta

/conectar-google

Quando usar: token expirado (RefreshError), verificar conexao.

Erros comuns

Erro	Causa	Solucao
RefreshError	Token expirado (~6 meses)	Rodar get_google_refresh_token.py
PERMISSION_DENIED	Sem acesso a conta	Verificar permissoes
INVALID_CUSTOMER_ID	ID errado	10 digitos sem tracos

/conectar-meta

Quando usar: token expirado (OAuthException), verificar conexao.

Tipos de token

Tipo	Validade	Recomendacao
User Token	~1 hora	Apenas para testes
Long-Lived User Token	~60 dias	OK para uso pessoal
System User Token	Nao expira	Recomendado

/diagnostico-conta

Quando usar: check diario, antes de otimizar, reuniao com cliente.

Alertas automaticos

Condicao	Alerta
Hoje sem conversoes apos 15h	Zero leads hoje
CTR < 5% em Search	CTR abaixo do esperado
Orcamento restante < 20%	Orcamento critico
CPA > 2x meta	CPL acima da meta
Campanha ativa sem impressoes	Campanha travada

/gerar-relatorio

Quando usar: relatorio mensal, apresentacao para cliente.

Plataforma	O que inclui
Google Ads	Campanhas, keywords, QS, search terms, gasto diario
Meta Ads	Campanhas, ad sets, criativos, organico, Reels
Ambos	Dashboard unificado

/gerar-relatorio-meta

Quando usar: dashboard semanal/mensal de Meta Ads.

13 secoes do dashboard

1. Filtro de Periodo
2. Header (cliente, periodo, toggle dark/light)
3. Resumo Executivo (6 KPIs com deltas)
4. Metricas de Conversao
5. Graficos (gasto/dia, distribuicao)
6. Campanhas (cards com saturacao)
7. Conjuntos de Anuncios
8. Criativos (cards com thumbnail)
9. Visao Consolidada (pago + organico)
10. Instagram Organico
11. Reels (cards com metricas)
12. Alertas e Insights
13. Footer

/analise-reels-organico

Quando usar: analise semanal de conteudo organico.

8 passos

Passo	Acao
0	Identifica cliente e IG User ID
1	Coleta N Reels via Instagram Insights API
2	Classifica performance (TOP, ALTO, MEDIO, BAIXO)
3	Identifica padroes de sucesso e fracasso
4	Recomenda quais Reels impulsionar
5	Sugere 3 novos roteiros de Reels
6	Escreve copy completa para cada roteiro
7	Gera dashboard HTML interativo

Padrao Visual (Style Guide)

Design System (CSS Variables)

:root, [data-theme="dark"] {
  --bg:#0c0e18;      /* fundo da pagina */
  --card:#13161f;     /* fundo dos cards */
  --accent:#6c5ce7;   /* cor principal */
  --green:#22c55e;    /* bom/positivo */
  --red:#ef4444;      /* ruim/critico */
  --amber:#f59e0b;    /* destaque */
  --blue:#0984e3;     /* medio */
}

Hierarquia das secoes

1. Header — identidade visual
2. KPIs consolidados — visao rapida
3. Tabela comparativa/ranking
4. Graficos — visualizacao (grid 2x2)
5. Cards de detalhe — analise individual
6. Padroes/Insights — conclusoes
7. Recomendacoes/Acoes — proximo passo
8. Alertas — urgencias
9. Footer

Tipos de Relatorio

Dashboard Google Ads

Skill: /gerar-relatorio

Conteudo: resumo executivo, campanhas ativas, keywords com Quality Score, search terms, gasto diario.

Dashboard Meta Ads + IG Organico

Skill: /gerar-relatorio-meta

13 secoes com filtro de periodo interativo, comparativo automatico, KPIs com setas de tendencia, funil de retencao de video.

Dashboard Unificado

Skill: /gerar-relatorio (selecionando "ambos")

Combina Google Ads + Meta Ads em um unico dashboard.

Analise de Reels

Skill: /analise-reels-organico

11 secoes com thumbnails, graficos Chart.js, cards detalhados, padroes, recomendacoes e roteiros.

Data-Driven Rendering

Os relatorios usam dados embarcados como JSON dentro do HTML. O JavaScript renderiza tudo automaticamente.

Vantagem

Para gerar um novo relatorio, basta trocar os dados no array. Todo o HTML, graficos e cards se adaptam automaticamente.

Onde ficam os relatorios

clients/{slug}/{plataforma}/reports/{tipo}-{periodo}.html

Abra o arquivo .html diretamente no navegador para visualizar.

Personalizacao

Mudar cores

:root, [data-theme="dark"] {
  --accent:#6c5ce7;   /* mude para a cor da sua marca */
}

Mudar agencia no footer

O footer usa o nome da agencia definido no setup. Para alterar manualmente:

<span>Gerado por <strong>Claude Code</strong> — Sua Agencia</span>

Mapa de Entregaveis

Categoria	Qtd	Descricao
Skills (comandos)	7	Automacoes executaveis
Agentes IA	3	Prompts especializados PPC
Framework	1	Modelo de decisao
Scripts de dashboard	4	Geradores HTML
Templates HTML	1	Template data-driven
Style Guide	1	Padrao visual
Helpers/Libs	3	Conexao API + utilitarios
Guias interativos	3	HTML passo-a-passo
Docs de referencia	4	Guia, skills, relatorios, troubleshooting
Total	26	Extraidos automaticamente

Dependencias entre Entregaveis

instalar.bat
  └── setup_bootcamp.py
        ├── CLAUDE.md (personalizado)
        ├── credentials/ (templates)
        ├── .claude/commands/ (7 skills)
        │     ├── /configurar-ambiente → preenche CLAUDE.md
        │     ├── /conectar-google → valida google-ads.yaml
        │     ├── /conectar-meta → valida meta.env
        │     ├── /diagnostico-conta → usa APIs
        │     ├── /gerar-relatorio → usa dashboard scripts
        │     ├── /gerar-relatorio-meta → usa relatorio scripts
        │     └── /analise-reels-organico → usa meta_client.py
        ├── system-prompts/agents/ (3 agentes)
        ├── system-prompts/frameworks/ (1 framework)
        └── google-ads/lib/ + meta-ads/lib/ (helpers)

Solucao de Problemas — Instalacao

instalar.bat nao abre / fecha imediatamente

Causa: Nao esta rodando como administrador.

Solucao: Clique direito > "Executar como administrador".

winget nao encontrado

Solucao: Abra a Microsoft Store, busque "App Installer" e atualize. Ou instale manualmente.

python nao reconhecido

Solucao: Feche todos os terminais, reabra e tente novamente. Se persistir, reinstale Python marcando "Add to PATH".

pip install falha

python -m pip install --upgrade pip
python -m pip install google-ads requests jinja2 python-dotenv google-auth-oauthlib

Solucao de Problemas — Google Ads API

RefreshError / Token expirado

Refresh token vence a cada ~6 meses.

python credentials/get_google_refresh_token.py

PERMISSION_DENIED

Verifique se o Customer ID esta correto (10 digitos) e se o usuario tem acesso na conta.

INVALID_CUSTOMER_ID

Use apenas numeros, sem tracos. Exemplo: 5921066791

Solucao de Problemas — Meta Ads API

OAuthException (codigo 190)

Token expirado. Execute /conectar-meta e gere um novo token.

Erro 100: plays metric not supported

Metrica plays descontinuada na v22.0+. Ja corrigido nas skills atuais.

Token expira a cada hora

Voce esta usando User Token. Gere um System User Token no Business Manager:

1. Business Manager > Configuracoes
2. Usuarios do sistema > Adicionar (Admin)
3. Gerar token com todas as permissoes
4. Colar em credentials/meta.env

Permissoes insuficientes

Essenciais: ads_management, ads_read, business_management, instagram_basic, pages_manage_ads, pages_read_engagement

Solucao de Problemas — Relatorios HTML

Relatorio abre em branco

Abra o console (F12 > Console) e verifique erros de JavaScript. Se os dados estao vazios, re-execute a skill.

Graficos nao aparecem

Chart.js vem via CDN. Verifique conexao com internet.

Thumbnails nao carregam

URLs de thumbnail do Instagram expiram. Re-execute a skill para gerar URLs frescas.

Solucao de Problemas — Claude Code

Skill nao aparece ao digitar /

Verifique se a pasta .claude/commands/ existe com 7 arquivos .md. Se faltou, re-execute python setup_bootcamp.py.

Claude nao reconhece o CLAUDE.md

Abra a pasta raiz (onde esta o CLAUDE.md) no VS Code, nao uma subpasta.

Claude pede informacoes que estao no CLAUDE.md

CLAUDE.md nao esta preenchido. Execute /configurar-ambiente.

Checklist de Diagnostico Rapido

1. Token valido?
   → /conectar-google ou /conectar-meta

2. IDs corretos no CLAUDE.md?
   → Verificar secao "Contas Conectadas"

3. Credenciais no lugar?
   → credentials/google-ads.yaml existe?
   → credentials/meta.env existe?

4. Permissoes suficientes?
   → /conectar-meta lista as permissoes

5. Internet funcionando?
   → Chart.js precisa de CDN

6. Pasta correta aberta no VS Code?
   → CLAUDE.md deve estar na raiz