Enviamos sites headless para clientes que medem tudo -- Core Web Vitals, schema markup, pontuações de acessibilidade, deltas de tráfego orgânico. Um deploy ruim pode derrubar rankings que levaram meses para construir. Então quando Anthropic lançou subagentes, hooks e skills no Claude Code, reconstruímos todo nosso pipeline pré-deploy em torno deles.

Este post descreve nossa exata configuração: a estrutura do diretório .claude/, cada definição de subagente, as configs de hooks e os arquivos de skill que conectam tudo. Vamos compartilhar quatro incidentes reais que o sistema detectou, a matemática de ROI em nossa escala, e onde essa abordagem ainda tem falhas.

Tivemos um pico de CLS de 40% que mesmo assim chegou à produção

Três semanas atrás. Redesign do blog do cliente. Tudo parecia bem em dev. Mergimos.

Dois dias depois o CTO deles envia um screenshot do Search Console. CLS saltou de 0.08 para 0.14 em mobile. Páginas que ranqueavam #3 para "enterprise billing software" caíram para #8. Impacto na receita? Eles estimaram $40k/mês.

O problema? Uma imagem hero que carregava async mas não tinha atributos de tamanho. Clássico. Nosso CI não detectou nada porque não estávamos checando layout shift no build de preview real.

Aí começamos a procurar por subagentes.

Subagentes são instâncias isoladas do Claude Code que rodam dentro de uma sessão pai com seu próprio system prompt, acesso a tools e limites de tarefa. Hooks disparam subagentes em pontos específicos -- antes de um comando rodar, após mudanças de arquivo, ou em commit. Skills são arquivos de instruções reutilizáveis (markdown) que ensinam Claude como executar uma tarefa específica.

Anthropic enviou o redesign em 14 de abril de 2025, introduzindo Routines junto com essas primitivas. Para nosso caso de uso, subagentes brutos mais hooks nos deram controle mais fino sobre exatamente quando cada check dispara e qual contexto recebe.

A diferença-chave das verificações tradicionais de CI: subagentes podem raciocinar sobre resultados, correlacionar falhas entre checks e escrever resumos legíveis por humanos. Um job CI retorna exit code 0 ou 1. Um subagente retorna "Os dados estruturados em /blog/[slug] estão faltando o campo dateModified, que estava presente no build anterior. Isso provavelmente causará uma regressão de rich snippet no Google Search Console em 3-5 dias."

Esse é o ponto todo.

Três meses depois, nossa configuração do GitHub Actions finalmente nos quebrou

Nossa pipeline anterior era um emaranhado de GitHub Actions chamando Lighthouse CI, pa11y, linkinator e scripts Node customizados. Funcionava.

Mais ou menos.

Mas tinha três problemas.

Sem raciocínio entre checks. Se Lighthouse sinalizava um problema de CLS e o scan de acessibilidade sinalizava uma tag alt faltando na mesma imagem, recebíamos dois alertas separados sem conexão. Engenheiros tinham que fazer grep manualmente nos logs de CI, correlacionar timestamps, descobrir que era o mesmo componente.

Desperdício de tempo.

Config frágil. Cada tool tinha seu próprio arquivo de config, formato de threshold e schema de output. Atualizar thresholds significava tocar 4-6 arquivos. YAML aqui. JSON ali. Variáveis de ambiente em um terceiro lugar. Um typo e toda a pipeline sai com 0 quando deveria falhar.

Sem explicações contextuais. Engenheiros recebiam pass/fail. Devs juniores gastavam 20-40 minutos entendendo por quê algo falhou e o que fazer sobre isso. "Pontuação de acessibilidade: 87" não te diz qual atributo ARIA está faltando ou por que importa para leitores de tela.

Gastávamos 3 horas por semana debugando false positives ou explicando falhas no Slack.

O golpe final? Agosto de 2025. Fazemos push de um redesign do Northwind Traders às 16h de uma sexta (eu sei). Lighthouse passou. Acessibilidade passou. Links passaram. Shipamos.

Segunda-feira de manhã o VP de Marketing deles nos envia um email. "Por que nossas páginas de produto desapareceram do Google?" Acontece que acidentalmente setamos robots meta para noindex em toda página sob /products/. Nosso CI não checava robots tags. Levou seis dias para ser re-indexado. Perderam um estimado de $12k em receita.

Não precisávamos de outra tool de CI -- precisávamos de uma camada de orquestração que pudesse raciocinar sobre os outputs de tools que já confiávamos. Skill files bem-escritas são a diferença entre um subagente que alucina regras de acessibilidade e um que roda pa11y com as flags certas e interpreta o output JSON corretamente.

Nossa estrutura de diretório .claude/

Aqui está a árvore atual:

.claude/
├── settings.json
├── agents/
│   ├── seo-regression.md
│   ├── cwv-smoke.md
│   ├── accessibility.md
│   ├── broken-links.md
│   ├── schema-validation.md
│   └── deploy-gate.md
├── skills/
│   ├── run-lighthouse.md
│   ├── run-pa11y.md
│   ├── run-linkinator.md
│   ├── parse-schema-org.md
│   ├── compare-seo-snapshot.md
│   └── format-deploy-report.md
└── snapshots/
    └── seo-baseline.json

O diretório snapshots/ mantém dados de baseline para verificações comparativas. Simples. Versionamos no Git para que possamos ver o que mudou quando um cliente pergunta "por que rankings caíram na terça passada?"

Nada sofisticado. Apenas arquivos markdown e JSON.

Um cliente ligou às 23h porque Google dropou todos os rich snippets deles

Setembro de 2025. Estamos construindo um site de e-commerce para um varejista de médio porte (vamos chamá-los de Acme Home Goods). Eles tinham passado seis meses conseguindo rich snippets -- estrelas de produto, pricing, disponibilidade -- aparecendo nos resultados de busca.

Fazemos push de uma atualização de tema Shopify. Parece bem. Envia sexta-feira à noite.

Sábado às 23h14 recebo um texto. "Nossas páginas de produto parecem quebradas no Google. As estrelas sumiram. Os preços sumiram. O que aconteceu?"

Abro Search Console. Toda single página de produto está gerando erros de dados estruturados. O campo offers está faltando priceCurrency. Sem ele, Google não mostra o rich snippet. Rankings não caíram, mas click-through rate caiu de 4.2% para 1.8% durante a noite.

Custo? Aproximadamente $8k/semana em tráfego perdido até corrigirmos e Google re-rastrear tudo.

O schema estava lá. Apenas mudamos o nome da propriedade de priceCurrency para currency porque a API Shopify usa essa chave. Não pensamos nisso. Nenhuma validação detectou.

Aí construímos o subagente schema-validation.

Você cria um arquivo markdown em .claude/agents/ com um system prompt, uma lista de tools permitidas e instruções de tarefa. A sessão pai (ou um hook) o dispara com dispatch_agent() ou via config de hook em settings.json.

Estrutura mínima:

# Agent: [Name]

## Role
[Descrição de uma linha]

## Allowed Tools
- Bash (restrito a comandos específicos)
- Read file
- Write file

## Instructions
[Descrição de tarefa passo-a-passo, referenciando skill files]

## Output Format
[Formato exato que o pai espera]

Seja extremamente específico sobre formato de output. Se o deploy-gate orchestrator espera JSON com um boolean passed e uma string summary, diga isso. Subagentes que retornam texto livre quebram orquestração. Aprendemos isso da forma difícil quando um subagente retornou tabelas markdown e o deploy gate não conseguiu fazer parse. Levou-me duas horas às 2am para debugar porque o pai simplesmente falhou silenciosamente. Sem erro. Apenas não disparou o bloco de deploy.

Não cometa meu erro. Tranche o formato.

Subagent 1: SEO regression check

Isto compara elementos críticos de SEO do build atual contra um snapshot de baseline.

# Agent: SEO Regression Check

## Role
Detectar regressões de SEO entre o build atual e o baseline armazenado.

## Allowed Tools
- Bash (apenas scripts node)
- Read file

## Instructions
1. Ler o arquivo de skill em .claude/skills/compare-seo-snapshot.md
2. Rodar: node scripts/extract-seo-meta.js --url=$PREVIEW_URL --output=/tmp/seo-current.json
3. Ler .claude/snapshots/seo-baseline.json
4. Comparar os dois snapshots campo por campo:
   - title tags (match exato)
   - meta descriptions (similaridade > 0.85)
   - canonical URLs (match exato)
   - h1 count (deve ser igual a 1 por página)
   - robots meta (não deve ter mudado para noindex)
   - Open Graph tags (og:title, og:description, og:image presentes)
5. Marcar qualquer página onde robots mudou para noindex como CRITICAL.
6. Marcar title tags faltando ou duplicadas como HIGH.
7. Marcar mudanças de meta description > 15% diferentes como MEDIUM.

## Output Format
{"passed": boolean, "critical": [], "high": [], "medium": [], "summary": string}

O script extract-seo-meta.js tem 120 linhas de Puppeteer que acessa toda página no sitemap e faz dump de title, meta, canonicals, h1s e tags OG para JSON. Nada inteligente. Apenas extração.

O valor do subagente está na comparação e raciocínio, não na extração. Ele sabe qual mudança importa. Qual é cosmética. Qual custará ao cliente $15k em tráfego orgânico no próximo trimestre.

Exemplo: se você mudar uma meta description de "Best CRM software for small businesses in 2025" para "Best CRM software for small business", a pontuação de similaridade é 0.91. Está tudo bem. Mas se mudar para "CRM software", similaridade cai para 0.65. O subagente marca como MEDIUM porque essa é uma redução de 40% em densidade de keyword e provavelmente ferirá CTR.

Não é apenas diff. É raciocínio sobre o que o diff significa.

Detectamos quatro problemas com isso até agora. A coisa noindex robots. Um caso onde alguém deletou todas as imagens OG (teria prejudicado social shares). Um caso onde title tags foram truncadas para 40 chars em vez de 60 (apenas parecia ruim, não prejudicou SEO, mas cliente teria notado). E um onde canonical URLs mudaram de https:// para http:// (teria causado penalidades de conteúdo duplicado).

Cada um teria custado pelo menos poucas horas de limpeza e confiança de cliente. Provavelmente mais.

Armazenamos seo-baseline.json no repo e o atualizamos como parte do hook deploy-success.

Subagent 2: Core Web Vitals smoke test

# Agent: CWV Smoke Test

## Role
Rodar Lighthouse em páginas-chave e marcar regressões de CWV.

## Allowed Tools
- Bash

## Instructions
1. Ler .claude/skills/run-lighthouse.md
2. Rodar Lighthouse CI contra $PREVIEW_URL para essas páginas:
   - / (homepage)
   - /blog/ (listing)
   - /blog/[most-recent-post] (detail)
   - /services/ (se existe)
3. Thresholds (falhar se qualquer um abaixo):
   - LCP: 2500ms
   - FID/INP: 200ms
   - CLS: 0.1
   - Performance score: 85
   - Accessibility score: 90
4. Se uma métrica regrediu mais de 10% da execução anterior,
   marcar como WARNING mesmo que ainda acima do threshold.
5. Incluir o elemento específico causando LCP ou CLS onde Lighthouse reporta.

## Output Format
{"passed": boolean, "pages": [{"url": string, "scores": {}, "flags": []}], "summary": string}

O arquivo de skill associado (run-lighthouse.md) contém a invocação lhci CLI exata:

# Skill: Run Lighthouse

## Command
```bash
npx @lhci/cli@0.14.0 collect \
  --url="$1" \
  --numberOfRuns=3 \
  --settings.preset=desktop \
  --settings.output=json \
  --settings.outputPath=/tmp/lhci-results/

Parsing

Ler a execução mediana de /tmp/lhci-results/. Extrair:

• categories.performance.score * 100
• audits['largest-contentful-paint'].numericValue
• audits['cumulative-layout-shift'].numericValue
• audits['interaction-to-next-paint'].numericValue (se presente)

## Subagent 3: Accessibility scan

```markdown
# Agent: Accessibility Scan

## Role
Rodar pa11y contra URLs de preview e reportar violações WCAG 2.1 AA.

## Allowed Tools
- Bash

## Instructions
1. Ler .claude/skills/run-pa11y.md
2. Rodar pa11y contra o mesmo conjunto de páginas do agente CWV.
3. Agrupar resultados por severidade: error, warning, notice.
4. Para cada error, incluir:
   - O critério WCAG violado (ex: 1.1.1 Non-text Content)
   - O elemento HTML (selector)
   - Uma sugestão de fix de uma frase
5. Falhar se qualquer error existir. Avisar se warnings > 10.

## Output Format
{"passed": boolean, "error_count": number, "warning_count": number, "errors": [{"criterion": string, "selector": string, "fix": string}], "summary": string}

Usamos pa11y@8.0.0 com a flag --runner=axe. O runner htmlcs padrão perde algumas questões de contraste de cor que axe detecta.

Subagent 4: Broken link scan

# Agent: Broken Link Scan

## Role
Rastrear o site de preview e reportar links internos e externos quebrados.

## Allowed Tools
- Bash

## Instructions
1. Ler .claude/skills/run-linkinator.md
2. Rodar: npx linkinator@6.1.2 $PREVIEW_URL --recurse --timeout 15000 --format json > /tmp/link-results.json
3. Filtrar resultados para status >= 400 ou status === 0 (timeout).
4. Separar links internos (mesmo domínio) de links externos quebrados.
5. Links internos quebrados são CRITICAL. Links externos quebrados são WARNING.
6. Excluir domínios externos conhecidos-flaky: twitter.com, linkedin.com (eles bloqueiam crawlers).

## Output Format
{"passed": boolean, "internal_broken": [{"source": string, "target": string, "status": number}], "external_broken": [...], "summary": string}

Subagent 5: Schema validation

# Agent: Schema Validation

## Role
Validar dados estruturados JSON-LD em todas as páginas.

## Allowed Tools
- Bash
- Read file

## Instructions
1. Ler .claude/skills/parse-schema-org.md
2. Para cada página no sitemap:
   a. Extrair todos os blocos <script type="application/ld+json">
   b. Fazer parse como JSON (falhar se malformado)
   c. Validar campos obrigatórios por @type:
      - Article: headline, datePublished, dateModified, author, image
      - LocalBusiness: name, address, telephone
      - WebPage: name, description
      - BreadcrumbList: itemListElement com position, name, item
   d. Checar que todas as referências @id se resolvem dentro do graph da página
   e. Validar URLs no schema são absolutas, não relativas
3. Marcar campos obrigatórios faltando como HIGH.
4. Marcar JSON malformado como CRITICAL.

## Output Format
{"passed": boolean, "pages": [{"url": string, "schemas": [{"type": string, "valid": boolean, "issues": []}]}], "summary": string}

Subagent 6: Deploy gate orchestrator

Este agente pai dispara os outros cinco e toma a decisão go/no-go.

# Agent: Deploy Gate

## Role
Orquestrar todos os checks pré-deploy e produzir uma decisão de deploy final.

## Allowed Tools
- Bash
- Read file
- Write file
- dispatch_agent

## Instructions
1. Disparar esses agentes em paralelo:
   - .claude/agents/seo-regression.md
   - .claude/agents/cwv-smoke.md
   - .claude/agents/accessibility.md
   - .claude/agents/broken-links.md
   - .claude/agents/schema-validation.md
2. Coletar todos os outputs.
3. Ler .claude/skills/format-deploy-report.md
4. Lógica de decisão:
   - Se QUALQUER agente tem um flag CRITICAL: BLOQUEAR deploy.
   - Se 2+ agentes tem flags HIGH: BLOQUEAR deploy.
   - Se 1 agente tem flags HIGH: AVISAR, requer override manual.
   - Senão: APROVAR.
5. Escrever o relatório completo para /tmp/deploy-report.md
6. Output a decisão.

## Output Format
{"decision": "APPROVE" | "WARN" | "BLOCK", "reports": {agent_name: agent_output}, "summary": string}

Hook configuration: settings.json

Aqui está nosso settings.json atual (com URLs específicos de cliente redacted):

{
  "hooks": {
    "pre-commit": [
      {
        "agent": ".claude/agents/schema-validation.md",
        "condition": "files_changed_match('**/*.json', '**/structured-data/**')",
        "env": {
          "PREVIEW_URL": "http://localhost:3000"
        }
      }
    ],
    "pre-push": [
      {
        "agent": ".claude/agents/deploy-gate.md",
        "env": {
          "PREVIEW_URL": "$VERCEL_PREVIEW_URL"
        },
        "timeout": 300,
        "on_failure": "block"
      }
    ],
    "post-deploy-success": [
      {
        "command": "node scripts/extract-seo-meta.js --url=$PRODUCTION_URL --output=.claude/snapshots/seo-baseline.json",
        "description": "Atualizar baseline de SEO após deploy bem-sucedido"
      }
    ]
  },
  "agent_defaults": {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 8192,
    "timeout": 120
  },
  "skills_directory": ".claude/skills/"
}

Notas sobre essa config:

• Usamos claude-sonnet-4-20250514 para subagentes, não Opus. As tarefas de raciocínio aqui não justificam a diferença de custo. Sonnet lida com "comparar dois objetos JSON e marcar diferenças" bem.
• O timeout: 300 no deploy gate dá tempo a todos os cinco subagentes para rodar. Agentes individuais têm defaults de 120s. O orquestrador recebe 5 minutos porque espera por todos eles.
• O condition no hook pre-commit significa que validação de schema apenas roda quando você toca arquivos relacionados a schema. Sem ponto rodar em uma mudança CSS.
• post-deploy-success atualiza o baseline. Sem isso, seu check de regressão de SEO compara contra dados stale.

Skill definitions que colam tudo junto

O arquivo de skill que faz o trabalho mais pesado é compare-seo-snapshot.md:

# Skill: Compare SEO Snapshots

## Purpose
Comparar dois snapshots de metadata de SEO e identificar regressões.

## Input
- Snapshot atual: /tmp/seo-current.json
- Snapshot baseline: .claude/snapshots/seo-baseline.json

## Comparison Rules

### Title Tags
- Se um title mudou E o tráfego orgânico da página (de metadata baseline) > 1000 sessions/mês, marcar como HIGH.
- Se um title agora está vazio ou corresponde ao title de outra página, marcar como CRITICAL.
- Se um title mudou em uma página de baixo tráfego, marcar como MEDIUM.

### Canonical URLs
- Qualquer mudança para URL canonical é HIGH.
- Uma canonical apontando para um domínio diferente é CRITICAL.
- Uma canonical faltando (estava presente, agora foi) é HIGH.

### Robots Meta
- Qualquer página que ganhou "noindex" é CRITICAL.
- Qualquer página que ganhou "nofollow" em links internos é HIGH.

### Novas Páginas
- Páginas em current mas não em baseline são INFO (esperado para conteúdo novo).
- Mas verificar que elas têm: title, meta description, canonical, pelo menos um h1.

### Páginas Removidas
- Páginas em baseline mas não em current são HIGH.
- Essas podem indicar remoção de rota acidental.

Esse arquivo de skill codifica meses de resposta de incidente de SEO em um formato que Claude pode seguir confiável. Sem ele, o subagente faria julgamentos razoáveis mas inconsistentes sobre o que constitui uma regressão.

Quatro incidentes que o sistema detectou

Incident 1: Noindex acidental em 47 posts de blog

Cliente: Empresa B2B SaaS, 200 páginas, 60k sessões orgânicas/mês.

Um desenvolvedor atualizou o componente <Head> no template de blog para adicionar uma nova meta tag. Eles copy-pastaram da config de staging, que tinha <meta name="robots" content="noindex, nofollow"> hardcoded. A mudança passou na code review porque o reviewer focou na nova tag, não nas existentes.

O subagente de regressão de SEO marcou 47 páginas como CRITICAL -- robots meta mudou para noindex. O deploy foi bloqueado.

Tempo para detectar: 2 minutos 14 segundos após push. Sem o sistema, teria sido detectado quando Search Console mostrou uma queda de coverage 3-7 dias depois.

Impacto estimado evitado: Esses 47 posts dirigem aproximadamente $14,000/mês em pipeline. Mesmo um evento de deindex de uma semana poderia ter custado $3,500+.

Incident 2: Regressão de CLS de uma nova imagem hero

Cliente: Marca de e-commerce, storefront Next.js 14 em Shopify Hydrogen.

O time de design trocou o hero da homepage por uma nova imagem com proporção de aspecto diferente mas não atualizou os atributos width/height no componente <Image>. A imagem carregou bem mas causou um CLS de 0.34 -- bem acima do threshold de 0.1.

O subagente CWV smoke test reportou regressão de CLS na homepage. O resumo especificamente apontou: "CLS causado pelo elemento img.hero-banner deslocando 0.34 cumulativo. As dimensões da imagem (1920x800) não correspondem à proporção de aspecto do container (16:9 = 1920x1080). Adicionar width={1920} height={800} explícito ou atualizar o container."

Tempo para detectar: 1 minuto 47 segundos.

Incident 3: Links internos quebrados após reestruturação de URL

Cliente: Firma de serviços profissionais, 80 páginas.

Reestruturamos suas páginas de serviço de /services/[name] para /[category]/[name]. Redirects estavam em lugar, mas três posts de blog tinham links hardcoded para as URLs antigas, e a navegação dirigida por CMS tinha uma entrada cached apontando para uma página deletada.

O scan de link quebrado encontrou 4 404s internos. O resumo do subagente notou que 3 dos 4 estavam no conteúdo do corpo do post de blog (não navegação), o que significava que tinham sido perdidos pelo audit de redirect.

Tempo para detectar: 3 minutos 8 segundos. O crawl do linkinator é a parte mais lenta.

Incident 4: DateModified faltando no schema de Article

Cliente: Empresa de mídia, 2,000 artigos.

Uma migração CMS de WordPress para Sanity perdeu o mapeamento de campo dateModified. O código de geração de schema voltou para null para dateModified, que produziu JSON-LD inválido.

O subagente de validação de schema marcou toda página de artigo como HIGH -- campo obrigatório dateModified faltando. O resumo explicou: "Google requer dateModified para dados estruturados Article serem elegíveis para Top Stories e rich results. Todas as 2,147 páginas de artigo são afetadas."

Tempo para detectar: 4 minutos 22 segundos (large sitemap).

ROI: minutos economizados por ship e dólares por mês

Aqui está nossa matemática:

Métrica	Antes (CI + manual)	Depois (subagentes)	Delta
Checks por deploy	4 tools, review manual	5 agents, automatizado	+1 check, -100% review manual
Tempo para rodar todos os checks	8-12 min (CI sequencial)	3-5 min (subagentes paralelos)	-60%
Tempo para entender falhas	20-40 min por falha	1-2 min (resumo contextual)	-90%
Deploys por semana (todos clientes)	18	18	Mesmo
Taxa de false positive	~15% (Lighthouse barulhento)	~4% (raciocínio filtra ruído)	-73%

Minutos economizados por ship: Média 25 minutos quando um check falha (30% de deploys). Isso é 25 × 5.4 deploys falhando/semana = 135 minutos/semana = 9 horas/mês.

Custo do sistema:

• Custos de API Claude para subagentes: ~$0.12 por full deploy gate run (5 agents, Sonnet, 6,000 tokens médio por agent)
• 18 deploys/semana × 4.3 semanas × $0.12 = $9.29/mês em custos de API
• Infraestrutura Puppeteer/Lighthouse: roda em instâncias de build Vercel existentes, sem custo adicionado
• Tempo de manutenção: ~2 horas/mês atualizando arquivos de skill e thresholds

Valor em dólar de tempo de engenheiro economizado: 9 horas/mês × $85/hora (blended rate para nosso time) = $765/mês economizado.

Valor em dólar de incidentes prevenidos: Baseado nos quatro incidentes acima, o incidente noindex sozinho poderia ter custado $3,500. Se prevenirmos um incidente assim por trimestre, isso é $1,166/mês em impacto de cliente evitado.

ROI Líquido: $1,920/mês em valor por $9.29/mês em custos de API. Esse é um retorno de 206x. Mesmo se você 10x os custos de API para um time maior, ainda é favorável.

Gaps e o que mudássemos

Esse sistema não é perfeito. Aqui está o que ainda é rough:

Nenhum teste de regressão visual. Subagentes podem rodar Lighthouse e pa11y mas não conseguem olhar para screenshots e dizer "a seção hero está quebrada." Estamos observando as capacidades de visão do Claude para isso.

Baseline drift. O baseline de SEO atualiza em deploy bem-sucedido, mas se você fizer ship de uma regressão que o sistema não detecta, ela vira o novo baseline. Nós revisamos baselines manualmente mensalmente.

Flakiness de link externo. Twitter/X, LinkedIn e alguns sites governamentais bloqueiam crawlers ou rate-limit agressivamente. Mantemos uma lista de exclusão, mas precisa de atualizações manuais.

Tempo de cold start. A primeira execução após clonar um repo leva mais tempo porque npx precisa buscar pacotes. Estamos considerando pré-instalar as CLI tools em uma camada Docker.

Rate limits do Anthropic. Disparar 5 subagentes simultaneamente pode ocasionalmente bater em rate limits da API Claude durante horas de pico. Adicionamos um stagger de 2 segundos entre spawns, o que funciona mas é inelegante.

Nossas definições de agent mais longas (schema validation tem 400 palavras) ocasionalmente produzem output menos estruturado que as mais curtas. Estamos considerando dividir o agente schema validation em sub-subagentes por-tipo.

FAQ

Subagentes de Claude Code funcionam com qualquer LLM, ou apenas Claude?

Subagentes são uma feature do Claude Code vinculada à API do Anthropic. Você precisa de uma chave de API Claude com acesso ao Claude Code. O formato de definição de agent é específico à convenção de diretório .claude/ do Claude Code, não um padrão geral.

Quanto custa rodar cinco subagentes por deploy em taxas de API?

Em nossa escala, aproximadamente $0.12 por full deploy gate run usando Claude Sonnet. Isso é aproximadamente $9-10/mês para 18 deploys por semana. Opus custaria aproximadamente 5x mais mas não encontramos necessário para essas tarefas.

Subagentes podem rodar em pipelines CI/CD como GitHub Actions?

Sim. Você pode invocar Claude Code headlessly em um ambiente CI. Disparamos nossos em conclusão de deploy de preview do Vercel via um webhook que chama claude-code run .claude/agents/deploy-gate.md com a URL de preview como uma variável de ambiente.

Qual é a diferença entre uma skill de Claude Code e um subagent?

Uma skill é um arquivo de instruções markdown que ensina Claude como fazer algo -- como uma receita. Um subagent é uma instância Claude isolada que pode ser disparada com seu próprio contexto e tools. Subagentes usam skills. Pense em skills como documentação e agentes como trabalhadores.

Você precisa da feature Routines do Anthropic ou subagentes brutos são suficientes?

Para nosso workflow de deploy gate, subagentes brutos mais hooks em settings.json são suficientes. Routines adicionam uma camada de orquestração de nível mais alto que é útil para workflows multi-step mais complexos. Podemos adotar Routines se nossos checks de deploy crescerem além de seis agentes.

Como você lida com falhas ou timeouts de subagent?

Cada subagent tem um timeout de 120 segundos. Se um subagent falha ou timeout, o orquestrador deploy gate o trata como um WARN, não um BLOCK. Preferimos fazer ship com um check incompleto que bloquear deploys porque Lighthouse ficou travado. O resumo nota qual checks não completou.

Essa abordagem pode substituir tools dedicadas como Lighthouse CI ou pa11y?

Não -- envolve elas. Os subagentes chamam essas tools via bash e então raciocinam sobre o output. Você ainda precisa das tools subjacentes instaladas. O valor está na orquestração, correlação e camada de reporte em linguagem natural, não em substituir os scanners em si.