Traducción del Artículo

Enviamos sitios headless para clientes que lo miden todo -- Core Web Vitals, schema markup, puntuaciones de accesibilidad, deltas de tráfico orgánico. Un mal deploy puede hundir rankings que tomaron meses construir. Así que cuando Anthropic lanzó subagentes, hooks y skills en Claude Code, reconstruimos todo nuestro pipeline pre-deploy alrededor de ellos.

Este post recorre nuestra configuración exacta: la estructura del directorio .claude/, cada definición de subagente, las configuraciones de hooks, y los archivos de skill que los unen. Compartiremos cuatro incidentes reales que el sistema detectó, las matemáticas de ROI a nuestra escala, y dónde este enfoque aún tiene brechas.

Detectamos un pico de CLS del 40% que llegó a producción de todos modos

Hace tres semanas. Rediseño del blog del cliente. Todo se veía bien en dev. Hicimos merge.

Dos días después el CTO del cliente envía una captura de pantalla de Search Console. CLS saltó de 0.08 a 0.14 en móvil. Páginas que clasificaban #3 para "enterprise billing software" cayeron a #8. ¿Impacto en ingresos? Estimaron $40k/mes.

¿El problema? Una imagen hero que se cargaba async pero no tenía atributos de tamaño. Clásico. Nuestro CI no capturó nada porque no estábamos revisando layout shift en el build de vista previa real.

Ahí es cuando empezamos a mirar subagentes.

Los subagentes son instancias de Claude Code con alcance que se ejecutan dentro de una sesión padre con su propio system prompt, acceso a herramientas y límite de tarea. Los hooks disparan subagentes en puntos específicos -- antes de que corra un comando, después de cambios de archivo, o en commit. Los skills son archivos de instrucciones reutilizables (markdown) que enseñan a Claude cómo realizar una tarea específica.

Anthropic lanzó el rediseño el 14 de abril de 2025, introduciendo Routines junto a estas primitivas. Para nuestro caso de uso, subagentes en bruto más hooks nos dieron un control más fino sobre exactamente cuándo dispara cada check y qué contexto recibe.

La diferencia clave de los checks de CI tradicionales: los subagentes pueden razonar sobre resultados, correlacionar fallos a través de checks, y escribir resúmenes legibles por humanos. Un trabajo de CI devuelve código de salida 0 o 1. Un subagente devuelve "Los datos estructurados en /blog/[slug] carecen del campo dateModified, que estaba presente en el build anterior. Esto probablemente causará una regresión de rich snippet en Google Search Console dentro de 3-5 días."

Ese es el punto completo.

Tres meses después, nuestra configuración de GitHub Actions finalmente nos rompió

Nuestro pipeline anterior era un enredo de GitHub Actions llamando a Lighthouse CI, pa11y, linkinator, y scripts personalizados de Node. Funcionaba.

Más o menos.

Pero tenía tres problemas.

Sin razonamiento entre checks. Si Lighthouse señalaba un problema de CLS y el scan de accesibilidad señalaba una etiqueta alt faltante en la misma imagen, obteníamos dos alertas separadas sin conexión. Los ingenieros tenían que hacer grep manualmente a través de logs de CI, correlacionar timestamps, descubrir que era el mismo componente.

Pérdida de tiempo.

Configuración frágil. Cada herramienta tenía su propio archivo de config, formato de threshold, y schema de salida. Actualizar thresholds significaba tocar 4-6 archivos. YAML aquí. JSON allá. Variables de entorno en un tercer lugar. Un typo y todo el pipeline sale 0 cuando debería fallar.

Sin explicaciones contextuales. Los ingenieros obtenían pass/fail. Los devs junior gastaban 20-40 minutos entendiendo por qué algo falló y qué hacer al respecto. "Accessibility score: 87" no te dice qué atributo ARIA falta o por qué importa para los lectores de pantalla.

Gastábamos 3 horas a la semana debuggeando falsos positivos o explicando fallos en Slack.

¿El colmo? Agosto 2025. Pusimos un rediseño de Northwind Traders a las 4pm un viernes (lo sé). Lighthouse pasó. Accesibilidad pasó. Links pasaron. Desplegamos.

Lunes por la mañana el VP de Marketing del cliente nos envía un email. "¿Por qué nuestras páginas de producto desaparecieron de Google?" Resultó que accidentalmente establecimos robots meta en noindex en cada página bajo /products/. Nuestro CI no revisaba robots tags. Tomó seis días ser re-indexado. Perdieron un estimado $12k en ingresos.

No necesitábamos otra herramienta de CI -- necesitábamos una capa de orquestación que pudiera razonar sobre los outputs de herramientas que ya confiábamos. Los archivos de skill bien escritos son la diferencia entre un subagente que alucina reglas de accesibilidad y uno que ejecuta pa11y con los flags correctos e interpreta la salida JSON correctamente.

Nuestra estructura de directorio .claude/

Aquí está el árbol actual:

.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

El directorio snapshots/ contiene datos baseline para checks de comparación. Simple. Lo versionamos en Git para que podamos ver qué cambió cuando un cliente pregunta "¿por qué los rankings cayeron el martes pasado?"

Nada sofisticado. Solo archivos markdown y JSON.

Un cliente llamó a las 11pm porque Google eliminó todos sus rich snippets

Septiembre 2025. Estamos construyendo un sitio de e-commerce para un minorista de tamaño medio (llamémoslos Acme Home Goods). Habían gastado seis meses consiguiendo que rich snippets -- estrellas de producto, precios, disponibilidad -- aparezcan en resultados de búsqueda.

Pusimos una actualización de tema de Shopify. Se ve bien. Se envía viernes por la noche.

Sábado a las 11:14pm recibo un texto. "Nuestras páginas de producto se ven rotas en Google. Las estrellas se fueron. Los precios se fueron. ¿Qué pasó?"

Abro Search Console. Cada página de producto está lanzando errores de datos estructurados. El campo offers carece de priceCurrency. Sin él, Google no mostrará el rich snippet. Los rankings no cayeron, pero el click-through rate pasó de 4.2% a 1.8% de la noche a la mañana.

¿Costo? Aproximadamente $8k/semana en tráfico perdido hasta que lo arreglamos y Google re-rastreó todo.

El schema estaba ahí. Solo cambiamos el nombre de propiedad de priceCurrency a currency porque la API de Shopify usa esa clave. No pensamos en ello. Ninguna validación lo capturó.

Ese es cuando construimos el subagente de schema-validation.

Creas un archivo markdown en .claude/agents/ con un system prompt, una lista de herramientas permitidas, e instrucciones de tarea. La sesión padre (u un hook) lo dispara con dispatch_agent() o a través de la config de hook en settings.json.

Estructura mínima:

# Agent: [Name]

## Role
[Descripción de una línea]

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

## Instructions
[Descripción de tarea paso a paso, referenciando archivos de skill]

## Output Format
[Formato exacto que espera el padre]

Sé extremadamente específico sobre el formato de output. Si el orquestador deploy-gate espera JSON con un boolean passed y un string summary, especifícalo. Los subagentes que devuelven texto libre rompen la orquestación. Aprendimos esto de la manera difícil cuando un subagente devolvió tablas markdown y el deploy gate no pudo parsearlo. Me tomó dos horas a las 2am debuggearlo porque el padre simplemente falló silenciosamente. Sin error. Solo no disparó el bloque de deploy.

No cometas mi error. Bloquea el formato.

Subagente 1: Verificación de regresión SEO

Esto compara los elementos críticos para SEO del build actual contra una snapshot baseline.

# Agent: SEO Regression Check

## Role
Detectar regresiones SEO entre el build actual y el baseline almacenado.

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

## Instructions
1. Lee el archivo de skill en .claude/skills/compare-seo-snapshot.md
2. Ejecuta: node scripts/extract-seo-meta.js --url=$PREVIEW_URL --output=/tmp/seo-current.json
3. Lee .claude/snapshots/seo-baseline.json
4. Compara los dos snapshots campo a campo:
   - title tags (coincidencia exacta)
   - meta descriptions (similitud > 0.85)
   - canonical URLs (coincidencia exacta)
   - h1 count (debe ser igual a 1 por página)
   - robots meta (debe no haber cambiado a noindex)
   - Open Graph tags (og:title, og:description, og:image presentes)
5. Señala cualquier página donde robots cambió a noindex como CRITICAL.
6. Señala title tags faltantes o duplicados como HIGH.
7. Señala cambios de meta description > 15% diferentes como MEDIUM.

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

El script extract-seo-meta.js tiene 120 líneas de Puppeteer que accede a cada página en el sitemap y vuelca title, meta, canonicals, h1s, y OG tags a JSON. Nada inteligente. Solo extracción.

El valor del subagente está en la comparación y razonamiento, no en la extracción. Sabe qué cambios importan. Cuáles son cosméticos. Cuáles le costarán al cliente $15k en tráfico orgánico el próximo trimestre.

Ejemplo: si cambias una meta description de "Best CRM software for small businesses in 2025" a "Best CRM software for small business", la puntuación de similitud es 0.91. Eso está bien. Pero si cambia a "CRM software", la similitud cae a 0.65. El subagente lo señala como MEDIUM porque esa es una reducción del 40% en densidad de palabras clave y probablemente herirá el CTR.

No es solo diff. Es razonamiento sobre lo que el diff significa.

Hemos capturado cuatro problemas con esto hasta ahora. La cosa noindex de robots. Un caso donde alguien eliminó todas las imágenes OG (habría hundido las acciones sociales). Un caso donde title tags fueron truncados a 40 caracteres en lugar de 60 (solo se veía mal, no hirió SEO, pero el cliente lo habría notado). Y uno donde las URLs canonicals cambiaron de https:// a http:// (habría causado penalizaciones de contenido duplicado).

Cada uno nos habría costado al menos algunas horas de limpieza y confianza del cliente. Probablemente más.

Almacenamos seo-baseline.json en el repo y lo actualizamos como parte del hook deploy-success.

Subagente 2: Prueba de humo de Core Web Vitals

# Agent: CWV Smoke Test

## Role
Ejecuta Lighthouse en páginas clave y señala regresiones de CWV.

## Allowed Tools
- Bash

## Instructions
1. Lee .claude/skills/run-lighthouse.md
2. Ejecuta Lighthouse CI contra $PREVIEW_URL para estas páginas:
   - / (homepage)
   - /blog/ (listing)
   - /blog/[most-recent-post] (detail)
   - /services/ (si existe)
3. Thresholds (fallan si alguno está debajo):
   - LCP: 2500ms
   - FID/INP: 200ms
   - CLS: 0.1
   - Performance score: 85
   - Accessibility score: 90
4. Si una métrica regresó más del 10% de la ejecución anterior,
   señala como WARNING incluso si aún está por encima del threshold.
5. Incluye el elemento específico causando LCP o CLS donde Lighthouse lo reporta.

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

El archivo de skill asociado (run-lighthouse.md) contiene la invocación exacta del CLI de lhci:

# 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

Lee la ejecución mediana desde /tmp/lhci-results/. Extrae:

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

## Subagente 3: Escaneo de accesibilidad

```markdown
# Agent: Accessibility Scan

## Role
Ejecuta pa11y contra URLs de vista previa y reporta violaciones de WCAG 2.1 AA.

## Allowed Tools
- Bash

## Instructions
1. Lee .claude/skills/run-pa11y.md
2. Ejecuta pa11y contra el mismo conjunto de páginas que el agente de CWV.
3. Agrupa resultados por severidad: error, warning, notice.
4. Para cada error, incluye:
   - El criterio de WCAG violado (ej. 1.1.1 Non-text Content)
   - El elemento HTML (selector)
   - Una sugerencia de corrección de una oración
5. Falla si existen errores. Advierte si 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 con el flag --runner=axe. El runner htmlcs predeterminado pierde algunos problemas de contraste de color que axe captura.

Subagente 4: Escaneo de enlaces rotos

# Agent: Broken Link Scan

## Role
Rastrear el sitio de vista previa y reportar enlaces internos y externos rotos.

## Allowed Tools
- Bash

## Instructions
1. Lee .claude/skills/run-linkinator.md
2. Ejecuta: npx linkinator@6.1.2 $PREVIEW_URL --recurse --timeout 15000 --format json > /tmp/link-results.json
3. Filtra resultados a status >= 400 o status === 0 (timeout).
4. Separa enlaces rotos internos (mismo dominio) de externos.
5. Los enlaces rotos internos son CRITICAL. Los enlaces rotos externos son WARNING.
6. Excluye dominios externos conocidos como frágiles: twitter.com, linkedin.com (bloquean rastreadores).

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

Subagente 5: Validación de schema

# Agent: Schema Validation

## Role
Validar datos estructurados JSON-LD en todas las páginas.

## Allowed Tools
- Bash
- Read file

## Instructions
1. Lee .claude/skills/parse-schema-org.md
2. Para cada página en el sitemap:
   a. Extrae todos los bloques <script type="application/ld+json">
   b. Parsea como JSON (falla si está malformado)
   c. Valida campos requeridos por @type:
      - Article: headline, datePublished, dateModified, author, image
      - LocalBusiness: name, address, telephone
      - WebPage: name, description
      - BreadcrumbList: itemListElement con position, name, item
   d. Verifica que todas las referencias @id se resuelvan dentro del gráfico de la página
   e. Valida que URLs en schema sean absolutas, no relativas
3. Señala campos requeridos faltantes como HIGH.
4. Señala JSON malformado como CRITICAL.

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

Subagente 6: Orquestador de puerta de deploy

Este agente padre dispara los otros cinco y hace la llamada go/no-go.

# Agent: Deploy Gate

## Role
Orquestar todos los checks pre-deploy y producir una decisión de deploy final.

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

## Instructions
1. Dispara estos agentes en 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. Recoge todos los outputs.
3. Lee .claude/skills/format-deploy-report.md
4. Lógica de decisión:
   - Si CUALQUIER agente tiene una bandera CRITICAL: BLOQUEA deploy.
   - Si 2+ agentes tienen banderas HIGH: BLOQUEA deploy.
   - Si 1 agente tiene banderas HIGH: ADVIERTE, requiere override manual.
   - De lo contrario: APRUEBA.
5. Escribe el reporte completo a /tmp/deploy-report.md
6. Output la decisión.

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

Configuración de hook: settings.json

Aquí está nuestro actual settings.json (con URLs específicas del cliente redactadas):

{
  "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": "Actualiza SEO baseline después de un deploy exitoso"
      }
    ]
  },
  "agent_defaults": {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 8192,
    "timeout": 120
  },
  "skills_directory": ".claude/skills/"
}

Notas sobre esta config:

  • Usamos claude-sonnet-4-20250514 para subagentes, no Opus. Las tareas de razonamiento aquí no justifican la diferencia de costo. Sonnet maneja "compara dos objetos JSON y señala diferencias" bien.
  • El timeout: 300 en la puerta de deploy da tiempo a los cinco subagentes para ejecutarse. Los agentes individuales tienen defaults de 120s. El orquestador obtiene 5 minutos porque espera a todos.
  • La condition en el hook pre-commit significa que validación de schema solo corre cuando tocas archivos relacionados con schema. Sin punto ejecutarlo en un cambio de CSS.
  • post-deploy-success actualiza el baseline. Sin esto, tu check de regresión SEO compara contra datos obsoletos.

Definiciones de skill que lo unen todo

El archivo de skill que hace la mayoría del trabajo es compare-seo-snapshot.md:

# Skill: Compare SEO Snapshots

## Purpose
Compara dos snapshots de metadatos SEO e identifica regresiones.

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

## Comparison Rules

### Title Tags
- Si un título cambió Y el tráfico orgánico de la página (del metadata baseline) > 1000 sesiones/mes, señala como HIGH.
- Si un título ahora está vacío o coincide con otro title de página, señala como CRITICAL.
- Si un título cambió en una página de bajo tráfico, señala como MEDIUM.

### Canonical URLs
- Cualquier cambio a URL canónica es HIGH.
- Un canónico apuntando a un dominio diferente es CRITICAL.
- Un canónico faltante (estaba presente, ahora se fue) es HIGH.

### Robots Meta
- Cualquier página que ganó "noindex" es CRITICAL.
- Cualquier página que ganó "nofollow" en enlaces internos es HIGH.

### Páginas Nuevas
- Las páginas en actual pero no en baseline son INFO (esperado para contenido nuevo).
- Pero verifica que tengan: title, meta description, canonical, al menos un h1.

### Páginas Removidas
- Las páginas en baseline pero no en actual son HIGH.
- Estas podrían indicar eliminación accidental de ruta.

Este archivo de skill codifica meses de respuesta a incidentes SEO en un formato que Claude puede seguir confiablemente. Sin él, el subagente haría juicios razonables pero inconsistentes sobre qué constituye una regresión.

Cuatro incidentes que el sistema capturó

Incidente 1: noindex accidental en 47 posts de blog

Cliente: Compañía SaaS B2B, 200 páginas, 60k sesiones orgánicas/mes.

Un desarrollador actualizó el componente <Head> en la plantilla de blog para añadir una etiqueta meta nueva. Copiaron y pegaron desde la config de staging, que tenía <meta name="robots" content="noindex, nofollow"> hardcodeado. El cambio pasó la revisión de código porque el revisor se enfocó en la nueva etiqueta, no en las existentes.

El subagente de regresión SEO señaló 47 páginas como CRITICAL -- robots meta cambió a noindex. El deploy fue bloqueado.

Tiempo para detectar: 2 minutos 14 segundos después de push. Sin el sistema, habría sido capturado cuando Search Console mostró una caída de cobertura 3-7 días después.

Impacto estimado evitado: Esos 47 posts impulsaban aproximadamente $14,000/mes en pipeline. Incluso un evento de deindex de una semana podría haber costado $3,500+.

Incidente 2: Regresión de CLS de una nueva imagen hero

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

El equipo de diseño cambió el hero de la homepage a una imagen nueva con aspect ratio diferente pero no actualizó los atributos width/height en el componente <Image>. La imagen se cargó bien pero causó un CLS de 0.34 -- muy por encima del threshold de 0.1.

El subagente de prueba de humo de CWV reportó regresión de CLS en la homepage. El resumen específicamente señaló: "CLS causada por elemento img.hero-banner cambiando 0.34 acumulativa. Las dimensiones de imagen (1920x800) no coinciden con el aspect ratio del contenedor (16:9 = 1920x1080). Añade explicit width={1920} height={800} o actualiza el contenedor."

Tiempo para detectar: 1 minuto 47 segundos.

Incidente 3: Enlaces internos rotos después de reestructuración de URL

Cliente: Firma de servicios profesionales, 80 páginas.

Reestructuramos sus páginas de servicio de /services/[name] a /[category]/[name]. Los redirects estaban en su lugar, pero tres posts de blog tenían enlaces hardcodeados a las URLs antiguas, y la entrada cacheada del navegador impulsado por CMS señalaba a una página eliminada.

El escaneo de enlaces rotos encontró 4 404s internos. El resumen del subagente notó que 3 de los 4 estaban en contenido del cuerpo del post de blog (no navegación), lo que significaba que habían sido perdidos por la auditoría de redirect.

Tiempo para detectar: 3 minutos 8 segundos. El rastreo linkinator es la parte más lenta.

Incidente 4: dateModified faltante en schema de Article

Cliente: Compañía de medios, 2,000 artículos.

Una migración de CMS de WordPress a Sanity perdió el mapeo del campo dateModified. El código de generación de schema se retiró a null para dateModified, que produjo JSON-LD inválido.

El subagente de validación de schema señaló cada página de artículo como HIGH -- campo dateModified requerido faltante. El resumen explicó: "Google requiere dateModified para que los datos estructurados de Article sean elegibles para Top Stories y rich results. Las 2,147 páginas de artículos están afectadas."

Tiempo para detectar: 4 minutos 22 segundos (sitemap grande).

ROI: minutos ahorrados por ship y dólares por mes

Aquí están nuestras matemáticas:

Métrica Antes (CI + manual) Después (subagentes) Delta
Checks por deploy 4 herramientas, revisión manual 5 agentes, automatizado +1 check, -100% revisión manual
Tiempo para ejecutar todos los checks 8-12 min (CI secuencial) 3-5 min (subagentes paralelos) -60%
Tiempo para entender fallos 20-40 min por fallo 1-2 min (resumen contextual) -90%
Deploys por semana (todos los clientes) 18 18 Igual
Tasa de falso positivo ~15% (Lighthouse ruidoso) ~4% (filtros de razonamiento ruido) -73%

Minutos ahorrados por ship: Promedio 25 minutos cuando un check falla (30% de deploys). Eso es 25 × 5.4 deploys fallidos/semana = 135 minutos/semana = 9 horas/mes.

Costo del sistema:

  • Costos de API de Claude para subagentes: ~$0.12 por ejecución completa de puerta de deploy (5 agentes, Sonnet, 6,000 tokens promedio por agente)
  • 18 deploys/semana × 4.3 semanas × $0.12 = $9.29/mes en costos de API
  • Infraestructura de Puppeteer/Lighthouse: se ejecuta en instancias de build Vercel existentes, sin costo adicional
  • Tiempo de mantenimiento: ~2 horas/mes actualizando archivos de skill y thresholds

Valor en dólares del tiempo de ingeniero ahorrado: 9 horas/mes × $85/hora (tasa combinada para nuestro equipo) = $765/mes ahorrados.

Valor en dólares de incidentes prevenidos: Basado en los cuatro incidentes anteriores, el incidente noindex solamente podría haber costado $3,500. Si prevenimos un incidente como ese por trimestre, eso es $1,166/mes en impacto del cliente evitado.

ROI neto: $1,920/mes en valor por $9.29/mes en costos de API. Eso es un retorno de 206x. Incluso si multiplicar por 10 los costos de API para un equipo más grande, aún es favorable.

Brechas y qué cambiaríamos

Este sistema no es perfecto. Aquí está lo que aún es aproximado:

Sin prueba de regresión visual. Los subagentes pueden ejecutar Lighthouse y pa11y pero no pueden mirar capturas de pantalla y decir "la sección hero está rota." Estamos observando las capacidades de visión de Claude para esto.

Drift de baseline. El baseline de SEO se actualiza en deploy exitoso, pero si envías una regresión que el sistema no captura, se convierte en el nuevo baseline. Revisamos baselines manualmente mensualmente.

Fragilidad de link externo. Twitter/X, LinkedIn, y algunos sitios gubernamentales bloquean rastreadores o abusan de la tasa agresivamente. Mantenemos una lista de exclusión, pero necesita actualizaciones manuales.

Tiempo de cold start. La primera ejecución después de clonar un repo toma más tiempo porque npx necesita buscar paquetes. Estamos considerando pre-instalar las herramientas de CLI en una capa Docker.

Límites de tasa de Anthropic. Disparar 5 subagentes simultáneamente puede ocasionalmente golpear límites de tasa en la API de Claude durante horas pico. Añadimos un escalonamiento de 2 segundos entre disparos, que funciona pero es inelegante.

Nuestras definiciones de agente más largas (validación de schema tiene 400 palabras) ocasionalmente producen salida menos estructurada que las más cortas. Estamos considerando dividir el agente de validación de schema en sub-subagentes por tipo.

FAQ

¿Los subagentes de Claude Code funcionan con cualquier LLM, o solo Claude?

Los subagentes son una característica de Claude Code vinculada a la API de Anthropic. Necesitas una clave de API de Claude con acceso a Claude Code. El formato de definición de agente es específico de la convención .claude/ de Claude Code, no un estándar general.

¿Cuánto cuesta ejecutar cinco subagentes por deploy en honorarios de API?

A nuestra escala, aproximadamente $0.12 por ejecución completa de puerta de deploy usando Claude Sonnet. Eso es aproximadamente $9-10/mes para 18 deploys por semana. Opus costaría aproximadamente 5x más pero no hemos encontrado que sea necesario para estas tareas.

¿Pueden los subagentes ejecutarse en pipelines de CI/CD como GitHub Actions?

Sí. Puedes invocar Claude Code sin cabeza en un entorno de CI. Disparamos el nuestro en la finalización de deploy de vista previa de Vercel a través de un webhook que llama a claude-code run .claude/agents/deploy-gate.md con la URL de vista previa como una variable de entorno.

¿Cuál es la diferencia entre un skill de Claude Code y un subagente?

Un skill es un archivo de instrucciones markdown que enseña a Claude cómo hacer algo -- como una receta. Un subagente es una instancia de Claude aislada que puede ser disparada con su propio contexto y herramientas. Los subagentes usan skills. Piensa en skills como documentación y agentes como trabajadores.

¿Necesitas la característica Routines de Anthropic o son suficientes subagentes en bruto?

Para nuestro flujo de trabajo de puerta de deploy, subagentes en bruto más hooks en settings.json son suficientes. Routines añaden una capa de orquestación de nivel superior que es útil para flujos de trabajo multi-paso más complejos. Podemos adoptar Routines si nuestros checks de deploy crecen más allá de seis agentes.

¿Cómo manejas fallos de subagentes o timeouts?

Cada subagente tiene un timeout de 120 segundos. Si un subagente falla o agota el tiempo, el orquestador de puerta de deploy lo trata como WARN, no BLOCK. Preferimos enviar con un check incompleto que bloquear deploys porque Lighthouse se colgó. El resumen nota qué checks no completaron.

¿Puede este enfoque reemplazar herramientas dedicadas como Lighthouse CI o pa11y?

No -- las envuelve. Los subagentes llaman a estas herramientas vía bash y luego razonan sobre la salida. Aún necesitas las herramientas subyacentes instaladas. El valor está en la capa de orquestación, correlación, y reportaje en lenguaje natural, no en reemplazar los scanners mismos.