Traffic Stack — Manual de Operação

0TL;DR

A Traffic Stack vive em Kit-Piloto-Automatico-V30/11_TRAFFIC_STACK/. Pra usar:

1. Abre PowerShell (Windows) ou Terminal (macOS/Linux) na raiz Kit-Piloto-Automatico-V30/
2. Roda claude
3. Cola o prompt-pai (seção 4)
4. Pede o que quer (*diagnostico 7d, *kill-list, etc.)
5. Confirma toda ação destrutiva (pause/edit/budget)

1O que é a Traffic Stack

Camada operacional dentro do Kit Piloto Automático V30. Enquanto o resto do kit (CoS, agents de copy, pipeline) está orientado a criar campanhas (briefing → estrutura → criativo → subir), a Traffic Stack é orientada a operar campanhas vivas:

• Diagnóstico de queda de performance
• Análise de criativos (hook rate, retention, padrão vencedor)
• Auditoria de tracking (Pixel + CAPI saúde)
• Escala de vencedores (ABO/CBO/Oxigênio/horizontal/multi-account)
• Inteligência competitiva (Meta Ad Library, swipe, engenharia reversa)
• Análise de funil end-to-end (ads → LP → VSL → quiz → checkout)

Arquitetura — quem faz o quê

┌──────────────────────────────────────────────────────────┐
│  L0 — Orquestração                                        │
│  @traffic-orchestrator (entry point único)                │
└──────────────┬───────────────────────────────────────────┘
               │ delega
   ┌───────────┼───────────┬─────────────┬────────────┬────┐
   ▼           ▼           ▼             ▼            ▼    ▼
 Execução   Análise    Tracking    Otimização    Intel
 ────────   ──────────  ─────────  ─────────────  ────────────
 meta-dr-   creative-  attribut-  diagnostician  competitor-
 specialist analyst    ion-       scaling-       spy
            funnel-    auditor    strategist
            analyst

A stack é multi-conta por design: cada cliente em 05_WORKSPACE/clientes/<cliente>/ tem context próprio (CLAUDE.md, act-mapping.yaml, funil.md, icp.md, baseline-kpis.md). O orchestrator carrega o context certo antes de qualquer análise.

2Pré-requisitos (verificar 1× só)

2.1 — CLI Meta funcionando

Rodar no PowerShell pra confirmar:

& "<HOME>\bin\meta.cmd" auth status

Esperado: Authenticated (token: EAA<SEU_TOKEN_TRUNCADO>). Se não, token expirou — gerar novo System User Token no Business Manager e atualizar ~/.profile do WSL (variável ACCESS_TOKEN).

2.2 — WSL ativo

wsl --list --quiet

Esperado: Ubuntu. Se WSL travou: wsl --shutdown e tenta novamente.

2.3 — Estrutura do Kit presente

cd <PASTA_DO_KIT>\Kit-Piloto-Automatico-V30
ls 11_TRAFFIC_STACK\agents
ls 05_WORKSPACE\clientes\<seu-cliente>

Esperado: 8 arquivos de agente em agents/ e 5+ arquivos na pasta do seu cliente.

2.4 — Cliente configurado

Antes de usar a stack pra qualquer cliente, garantir que existe 05_WORKSPACE/clientes/<cliente>/ com:

3Abrir uma sessão

3.1 — No terminal

# Windows (PowerShell):
cd <PASTA_DO_KIT>\Kit-Piloto-Automatico-V30
claude

# macOS / Linux:
cd ~/Kit-Piloto-Automatico-V30
claude

Importante abrir o Claude Code dentro de Kit-Piloto-Automatico-V30/ — assim o CLAUDE.md raiz é carregado e o sistema sabe contexto.

3.2 — Prompt-pai (cola tudo)

Esse é o prompt mestre que invoca a stack. Cola no Claude Code recém-aberto:

Após esse prompt, o Claude vai assumir a persona do @traffic-orchestrator e listar os 8 comandos. A partir daí, você pede o que quiser.

3.3 — Variantes de abertura

Pra um diagnóstico direto (sem confirmar greeting antes):

Pra cliente diferente (depois de adicionar):

Pra teste rápido (1 comando CLI só):

3.4 — Atalhos úteis no Claude Code

4Os 8 agentes — guia rápido

Cada agente é um arquivo .md em 11_TRAFFIC_STACK/agents/. O Claude carrega e adota a persona ao ser invocado por nome (@nome-agente) ou comando (*comando).

4.1 — Como invocar um agente diretamente

Em vez de passar pelo orchestrator, você pode acionar agente específico:

4.2 — Como o handoff entre agentes funciona

Cada agente sabe pra qual outro agente delegar. Exemplo: @meta-dr-specialist identifica vencedor → handoff pra @scaling-strategist → escala via @creative-analyst (lateralização). Você não precisa orquestrar manualmente — o orchestrator e os agentes coordenam.

5Workflows comuns (receitas prontas)

6CLI meta — referência rápida

Se quiser rodar comandos diretamente no terminal (sem agente), aqui as receitas mais usadas. Path do wrapper: <HOME>\bin\meta.cmd.

6.1 — Anatomia do comando

meta <grupo> <recurso> <ação> [--flags]
meta ads     campaign  list
meta ads     adset     get      <ID>
meta ads     insights  get      --date-preset last_7d
meta auth    status

6.2 — Receitas leitura SEGURO

Listar todas campanhas ativas

& "<HOME>\bin\meta.cmd" ads campaign list `
  --ad-account-id act_XXXXXXXXXXXXXXX `
  --filter "effective_status=ACTIVE" `
  -o json

Performance dos últimos 7 dias (nível campanha)

& "<HOME>\bin\meta.cmd" ads insights get `
  --ad-account-id act_XXXXXXXXXXXXXXX `
  --date-preset last_7d `
  --level campaign `
  --fields spend,impressions,clicks,ctr,cpc,cpm,actions,purchase_roas `
  -o json

Top 10 ads ordenados por gasto

& "<HOME>\bin\meta.cmd" ads insights get `
  --ad-account-id act_XXXXXXXXXXXXXXX `
  --date-preset last_14d `
  --level ad `
  --sort spend_descending `
  --limit 10 `
  -o json

Detalhes de um ad específico (com creative)

& "<HOME>\bin\meta.cmd" ads ad get <AD_ID> -o json
& "<HOME>\bin\meta.cmd" ads creative get <CREATIVE_ID> -o json

Listar contas que o token tem acesso

& "<HOME>\bin\meta.cmd" ads adaccount list -o json

6.3 — Receitas escrita DESTRUTIVO

Pausar uma campanha

& "<HOME>\bin\meta.cmd" ads campaign update <CAMPAIGN_ID> --status PAUSED

Ativar uma campanha (após validar tudo)

& "<HOME>\bin\meta.cmd" ads campaign update <CAMPAIGN_ID> --status ACTIVE

Mudar budget diário (CBO)

# Limite recomendado: max +20-30%/dia. Nunca dobrar.
& "<HOME>\bin\meta.cmd" ads campaign update <CAMPAIGN_ID> --daily-budget 60000
# 60000 = R$ 600,00 (em centavos)

6.4 — Formatos de saída

6.5 — Quando o CLI NÃO basta — Graph API direto

Setup avançado precisa Python WSL no venv do meta-ads:

# No WSL (não PowerShell):
PYTHON=$HOME/.local/share/pipx/venvs/meta-ads-cli/bin/python

# Token sem expor secret:
$PYTHON -c "
from meta.config import get_access_token
TOKEN = get_access_token()
# usar TOKEN nas chamadas Graph API requests/SDK
"

Quando ir pra Graph API:

• Placements específicos (Stories-only, Feed-only)
• is_adset_budget_sharing_enabled (declarar false em ABO)
• promoted_object completo (pixel + custom_event_type)
• url_tags em AdCreative (NÃO editável depois)
• attribution_spec customizado
• Upload de imagem (/adimages → image_hash)

Detalhes técnicos: ~/.claude/.../memory/reference_meta_ads_cli_vs_graphapi.md.

7Multi-conta — operar várias contas

7.1 — Estrutura

O CLI aceita --ad-account-id act_OUTRO_ID em qualquer comando. A stack mantém o mapeamento em dois lugares:

• 00_OS/clients-map.yaml — mapa global act_id ↔ cliente
• 05_WORKSPACE/clientes/<cliente>/act-mapping.yaml — todas as contas daquele cliente (alguns têm múltiplas)

7.2 — Conta unificada (multi-produto)

É comum o operador rodar vários produtos próprios numa mesma conta de anúncios. Convenção recomendada:

• <PRODUTO_A> — descrição
• <PRODUTO_B> — descrição
• <MARCA_PESSOAL> — topo de funil
• Outros produtos — adicionar conforme lançar

Filtragem por produto via naming convention das campanhas:

# Campanhas do produto A
meta ads campaign list --ad-account-id act_XXXXXXXXXXXXXXX `
  --filter "name:CONTAINS=PRODUTO_A_" -o json

# Campanhas do produto B
meta ads campaign list --ad-account-id act_XXXXXXXXXXXXXXX `
  --filter "name:CONTAINS=PRODUTO_B_" -o json

7.3 — Adicionar nova conta

Pra integrar uma conta nova (ex: cliente da agência):

1. Atribuir conta ao System User no Business Manager (BM → Configurações → Usuários do Sistema → Atribuir Conta de Anúncios)
2. Validar acesso:

   & "<HOME>\bin\meta.cmd" ads adaccount get act_NOVO_ID -o json

3. Pedir pra criar context em sessão Claude Code (ver workflow "Adicionar conta nova")

7.4 — Multi-cliente — caso de agência

Cada cliente tem sua pasta. Cria conforme adiciona contas:

05_WORKSPACE/clientes/
├── <cliente-1>/                # sua marca / produto principal
├── <cliente-2>/                # cliente da agência
├── <cliente-3>/                # ...
└── <cliente-N>/                # um por act_id ou um por marca

Antes de qualquer análise, agente lê o CLAUDE.md do cliente alvo. Nunca misturar context entre clientes — cada um tem ICP, baseline, restrições próprias.

8Regras inegociáveis

9Troubleshooting

10Referências e arquivos relacionados

10.1 — Arquivos da stack

10.2 — Cliente exemplo (template)

10.3 — Memória do operador (auto)

Localização: <HOME>/.claude/projects/<PROJECT_DIR>/memory/

Claude Code mantém memória persistente por projeto automaticamente — feedbacks, decisões, padrões aprendidos. Nada precisa ser configurado manualmente.

10.4 — Skills compartilhadas do V30

10.5 — Regras globais recomendadas

Cada operador pode adicionar suas regras em ~/.claude/rules/ ou ~/.claude/CLAUDE.md. Sugestões pra quem opera DR pt-BR:

Cheat sheet — abrir e rodar (cole nos favoritos)

# 1. Abrir terminal (Windows: PowerShell / macOS-Linux: Terminal):
cd <PASTA_DO_KIT>/Kit-Piloto-Automatico-V30
claude

# 2. Cola este prompt-pai:
Aciona @traffic-orchestrator (11_TRAFFIC_STACK/agents/traffic-orchestrator.md).
Carrega context <SEU_CLIENTE> (05_WORKSPACE/clientes/<seu-cliente>/).
Lista comandos disponíveis e aguarda meu pedido.
Auto mode ON. Confirma antes de qualquer ação destrutiva. pt-BR.

# 3. Pede o que precisar:
*diagnostico 7d filtrando <PRODUTO>
*kill-list
*lateralizar <ID>
*queda
*plano-escala
*spy [concorrente]