MÓDULO 5.4 · CASES COMPLETOS · ~55 min

🎯 Cases reais de Routines, Hooks e Agent SDK

3 cases onde o salto pra infra acontece de verdade: uma routine em produção há 90 dias, um hook que evitou perda catastrófica de dados, e o primeiro produto SaaS construído com Agent SDK. Cada um com decisões reais de segurança, custo e go-to-market.

⚠ N5 expõe a trava real: não é técnica. É confiança em sistema rodando enquanto você dorme. Cada case mostra como ela foi construída — gradualmente, com red lines explícitas.

CASE 1

🤖 Routine "PR review 24/7" em produção há 90 dias

Cenário

Carla é CTO duma startup B2C de 14 devs. Code review humano vira gargalo: PRs ficam 8-24h esperando 1ª revisão. Devs reclamam. Carla decide configurar routine: todo PR aberto recebe revisão automática em < 5min, com comentários inline. Humano ainda aprova merge, mas chega no PR com 1ª passada feita.

❌ Versão ingênua que QUASE foi pra produção

Routine v0 do Carla: "todo GitHub event 'pull_request opened' → Claude lê diff completo + dispara comentários direto na PR".

Os 4 problemas latentes:

• Sem token budget — PR grande (1k+ linhas) podia queimar R$ 80 sozinho. Sem cap, custo explode.
• Sem rate limit — alguém abre 5 PRs em 2 minutos, 5 reviews simultâneos.
• Sem distinção PR humano vs PR de bot/Dependabot — review automático em PR do Dependabot é gasto óbvio sem valor.
• Comentário direto sem aprovação — autor vê comentário "errado" de Claude e perde confiança no time todo.

✅ Versão de produção (depois de 4 iterações)

Trigger: GitHub webhook em PR opened/synchronize.

Hooks de segurança (não-negociáveis):

# pre-routine-start hook
- Se autor do PR é bot (dependabot, renovate, snyk-bot): ABORTA, log "skipped: bot author"
- Se diff > 2.000 linhas: ABORTA + posta comment "PR muito grande pra revisão automática. Revisor humano será notificado."
- Se contém arquivo em /db/migrations/, /infra/, /.github/workflows/: ABORTA + posta comment "Sensível. Apenas review humano."
- Se já tem comment de "claude-reviewer" nesse PR (sync trigger): roda em modo INCREMENTAL (só diff novo desde última review)

# task-budget hook
- Cap total: 30k tokens por execução. Encerra graciosamente se aproximar do limite.
- Cap mensal por repo: R$ 600. Se ultrapassar, pausa routine + alerta CTO.

# post-routine-end hook
- Posta comments em modo DRAFT (review pendente) — não em modo APPROVE
- Pinga revisor humano designado pra arbitrar comments
- Sempre adiciona disclaimer: "Revisão gerada por Claude. Humano confirma."

Prompt da routine:

Você é code reviewer sênior dessa startup. Ler claude.md primeiro pra entender convenções.

Para esse PR:
1. Avalia se o objetivo está claro na descrição. Se não, comente pedindo contexto.
2. Lê o diff inteiro com atenção em:
   - Lógica que pode quebrar em edge case
   - Padrão violado do claude.md (cite exatamente qual)
   - Teste faltante pra mudança feita
   - Naming inconsistente com convenção
   - TODO esquecido, console.log esquecido, debug esquecido
3. Para cada problema, comente INLINE no código com sugestão concreta. Use sufixo [auto].
4. Use a feature de "suggested change" do GitHub quando aplicável — review humano pode aceitar em 1 click.
5. Resumo final como overview do PR (status: approve / request changes / comment-only).

REGRAS:
- NÃO use tom "robotizado". Linguagem direta, técnica, como humano.
- NÃO comente óbvio ("adicione um teste") sem dizer QUAL teste.
- NÃO ataque o autor. Critique o código.
- SEMPRE diga o motivo da sugestão.
- Se algo está EXCELENTE, elogie em 1 linha (motiva autor).
- Limite 8 comments por PR. Se tiver mais, escolha os 8 mais críticos + 1 overview citando "outros pontos menores na próxima passada".

📊 90 dias em produção — números reais

1.247

PRs revisados

3min 12s

tempo médio até 1ª review

8.700

comentários inline úteis

R$ 380

custo médio/mês

Comentário do time interno após 90 dias: "PR fica mais polido antes de chegar pra mim. Eu reviso em metade do tempo. Carla criou tempo do nada."

2 incidentes que os hooks impediram: (1) dependabot abriu 38 PRs em 1h — todos pulados, R$ 0 gastos. (2) PR de migration esquemática foi tratada como "sensível" e não comentada (humano avaliou pessoalmente).

CASE 2

🛡 O hook pre-tool-use que salvou de um DROP TABLE

Cenário

Equipe Felicidata (dataops B2B). Ricardo, dev, configurou routine pra Claude limpar tabelas temporárias do warehouse semanalmente. Por engano colou o nome _users_temp_2026_05_ errado na config — o nome real correto da tabela de produção é users sem underscore. A routine, executando autonomamente, ia rodar DROP TABLE users em produção.

✅ O hook que estava lá há 6 meses

Felicidata tinha um hook pre-tool-use que Ricardo nem lembrava direito ter configurado:

# /.claude/hooks/pre-tool-use/database-guards.js

module.exports = function(tool, context) {
  if (tool.name !== 'sql_execute') return { allow: true };

  const sql = tool.params.query.toUpperCase();

  // BLOQUEIO ABSOLUTO sem exceção:
  if (sql.match(/\bDROP\s+TABLE\b/) || sql.match(/\bTRUNCATE\b/)) {
    if (!sql.includes('_TEMP_') && !sql.includes('_STAGING_')) {
      return {
        allow: false,
        reason: 'DROP/TRUNCATE detectado em tabela sem sufixo _TEMP_ ou _STAGING_. Aprovação humana obrigatória.',
        escalate_to: 'oncall@felicidata.io',
        require_token: true  // requer Ricardo digitar token manual no painel
      };
    }
  }

  // BLOQUEIO em produção sem WHERE:
  if (sql.match(/^DELETE FROM/) && !sql.includes('WHERE')) {
    return {
      allow: false,
      reason: 'DELETE sem WHERE em produção.',
      escalate_to: 'oncall@felicidata.io'
    };
  }

  // Outros DROPs e DDLs: permitir mas LOGAR
  if (sql.match(/\b(DROP|ALTER|TRUNCATE)\b/)) {
    log({ type: 'sensitive_ddl', sql, agent: context.agent_id });
  }

  return { allow: true };
};

Quando a routine rodou e tentou DROP TABLE users, o hook DISPAROU. Bloqueou. Mandou alerta pro oncall. Ricardo recebeu Slack às 3h22 da madrugada (que ele só viu de manhã): "BLOCKED: DROP TABLE users — requer aprovação humana".

🧠 Análise post-mortem

O que falhou na config: Ricardo havia digitado nome de tabela sem o sufixo _temp_ esperado. Erro humano simples — 4 caracteres faltando.

O que SALVOU: hook tinha regra explícita: "DROP sem sufixo _TEMP_/_STAGING_ = bloqueio absoluto". Não importa qual tabela.

Princípio: hooks não confiam em config humana. Operam como network firewall — black list por padrão, white list por exceção.

Custo evitado: recover de DROP TABLE users em produção = horas de downtime, perda de sessão, possível perda de dados não cobertos pelo backup das últimas 4h. Estimativa interna: R$ 80-180k.

🛡 Outros hooks que valeriam no seu setup

• pre-tool-use: bloquear rm -rf em path não-whitelist; bloquear git push --force em main; bloquear comando que envia e-mail externo sem aprovação
• post-edit: rodar linter/formatter em todo arquivo editado; verificar se commit não inclui secrets
• stop: notificar Slack/email quando sessão longa termina; salvar resumo automático em /sessions/
• response: badge no terminal quando Claude precisa de input humano (não fica passando despercebido)

CASE 3

🚀 Primeiro produto SaaS com Agent SDK — de prestador a builder

Cenário

Helena, dev solo, há 3 anos vende serviços de implementação (R$ 8-15k/projeto). Vê 80% dos clientes pedirem a MESMA coisa: importar lista de leads do LinkedIn, enriquecer com dados públicos (site, LinkedIn da empresa, notícias recentes), ranquear por fit ICP, exportar pra CSV pronto pro Outreach/Apollo. Helena pensa: "se isso é a mesma coisa toda vez, virou produto."

A decisão: usar Agent SDK pra empacotar o que ela já faz manual em SaaS pequeno. Não quer competir com Apollo. Quer atender as 200 contas que pedem "uma camada de inteligência" e pagam R$ 200-500/mês.

✅ MVP do produto "LeadFit"

Arquitetura:

• Frontend simples (Next.js) — upload CSV, dashboard, export
• Backend Node + Agent SDK (TypeScript) — orquestrador de agents
• 3 agentes especializados:
– Scraper: coleta dados de site/LinkedIn/notícias (com cache 7d pra mesma empresa)
– ICP Matcher: avalia fit baseado nas regras ICP que cliente cadastrou
– Enricher: gera nota de personalização pra cada lead (4-5 linhas pra usar no e-mail)
• Postgres + Redis pra cache
• Stripe pra cobrança

Hooks essenciais do dia 1:

• Token budget por cliente/mês (cap rígido baseado no plano)
• Rate limit por agente (pra não bater nos limites da API do scraping)
• Fallback se 1 agente falhar (continua os outros, marca lead como "enriched: parcial")
• Idempotência (mesmo CSV não re-processa)

📊 Os primeiros 6 meses

Mês	Clientes	MRR	Custo infra+API	Margem
M1	8 (beta grátis)	R$ 0	R$ 380	— (investimento)
M2	14 (8 pagantes)	R$ 1.940	R$ 540	R$ 1.400
M3	27 (22 pagantes)	R$ 5.380	R$ 980	R$ 4.400
M4	41	R$ 9.870	R$ 1.420	R$ 8.450
M5	58	R$ 13.940	R$ 1.980	R$ 11.960
M6	73	R$ 17.610	R$ 2.380	R$ 15.230

M6: Helena fechou o último contrato de implementação (era R$ 12k de prestação). Hoje vive 100% de SaaS. Trabalha 30h/semana. MRR > renda de prestadora.

⚠ Lições do builder iniciante

• MVP precisa caber em 1 prompt mental. "Importa lead → enriquece → ranqueia → exporta" é simples. Helena não tentou virar "Apollo killer". Foco mata feature-creep.
• Token budget por plano é essencial dia 1. Sem isso, primeiro cliente "espertinho" subindo CSV de 5k linhas zera margem do mês.
• Pricing transparente sobre custo de IA. Helena coloca "até X leads/mês incluso, R$ Y por mil extras" — cliente entende, não brigam.
• SDK não te livra de UX. 40% do tempo de Helena foi em UX/onboarding. Backend agentic é o "fácil" comparado a fazer cliente usar direito.
• Conteúdo > ads na fase pré-PMF. Helena escreveu 12 posts técnicos no Linkedin sobre lead enrichment. 64% dos clientes chegaram daí.

★

🧠 Padrão N5 dos 3 cases

1. Hooks NÃO confiam em config humana — operam como firewall. White list por exceção, não black list.
2. Token budget por execução E por mês — cap duplo. Sem isso, custo explode em 1 erro.
3. Routine com pre/post hooks claros — antes de rodar, decide se deve. Depois, audita. Visibilidade total.
4. Mode "draft" antes de "executor" — Claude posta sugestão, humano confirma. Por 4-8 semanas. Depois você relaxa.
5. SaaS com Agent SDK começa com MVP de 1 frase — "importa X → enriquece → exporta Y". Sem feature creep nos 6 primeiros meses.

🎓 Resumo do Módulo

✓

Case 1 — Routine PR review 24/7: 1.247 PRs revisados em 90d, R$ 380/mês, hooks bloqueando bots e arquivos sensíveis.

✓

Case 2 — Hook que evitou DROP TABLE users: bloqueio absoluto sem confiar em config, R$ 80-180k em recovery evitados.

✓

Case 3 — Primeiro SaaS com Agent SDK: 0 → MRR R$ 17.6k em 6 meses. De prestador a builder.

✓

Padrão N5: firewall em hooks, cap duplo de tokens, draft antes de executor, MVP de 1 frase.

Próximo Módulo:

5.5 — Walkthrough: como João, ex-tech lead, fechou primeiro cliente N5 pagante (R$ 12k/mês) em 21 dias, do zero.

← Voltar para Trilha Próximo Módulo →