Los 4 bloques HADS
Semantica explicita para consumo eficiente por LLMs
Cada bloque indica al modelo que debe leer y con que nivel de confianza, sin necesidad de razonar sobre la estructura del documento.
**[SPEC]**
Hecho autoritativo. Conciso. Listas, tablas o codigo. Siempre es verdad en la version actual.
IA: siempre lee
**[NOTE]**
Contexto humano, historia, motivacion, ejemplos narrativos. La IA puede omitir si [SPEC] responde la pregunta.
IA: puede omitir
**[BUG] descripcion**
Fallo verificado con sintoma + causa + fix. Conocimiento duro ganado a pulso. Siempre leer antes de generar codigo.
IA + humano: siempre lee
**[?]**
Afirmacion no verificada o inferida. Confianza reducida. La IA debe marcar incertidumbre al responder.
IA: confianza baja
Antes vs Despues
README informal → documentacion HADS
El agente CampaignAnalyzer de CULTIVA IA tenia un README mezclado con historia, instrucciones y bugs dispersos. HADS separa la informacion para que un LLM lea solo lo que necesita.
README.md original
Antes
~680 tokens · todo mezclado
# CampaignAnalyzer Agent
Este agente fue creado en enero 2025 para automatizar el analisis de campanas. Lo creamos porque nuestros account managers perdian 4 horas/semana en reports manuales. Conecta con Meta Business API y Google Ads API, procesa los datos de rendimiento, detecta anomalias y genera un PDF con recomendaciones en espanol.
## Como usarlo:
- Input: account_id + date_range + plataformas
- Output: PDF informe + JSON con metricas clave
- Modelos usados: claude-3-5-sonnet para analisis, claude-3-haiku para clasificacion de anomalias
- Rate limits: max 50 campanas por ejecucion, 10 ejecuciones/hora por cliente
## Cosas que sabemos que fallan:
- A veces cuando el account de Meta tiene mas de 500 ad sets, el agente se cuelga. Esto pasa porque la paginacion de la API de Meta tiene un bug con cursor-based pagination cuando hay muchos objetos. La solucion es usar page_size=100...
- Google Ads API v14 ya no esta soportada, hay que usar v17. Si alguien configura v14 el auth falla silenciosamente sin error claro.
- La deteccion de anomalias falla en campanas con menos de 7 dias de datos. El modelo necesita minimo 7 dias para tener baseline estadistico.
## Config necesaria:
- META_ACCESS_TOKEN (nunca commitear)
- GOOGLE_ADS_DEVELOPER_TOKEN
- GOOGLE_ADS_CUSTOMER_ID
- CLAUDE_API_KEY
- OUTPUT_DIR
campaign-analyzer.hads.md
Despues HADS
~280 tokens para IA (−59%)
# CampaignAnalyzer Agent
**Version 2.3.0** · CULTIVA IA · 2026-06 · HADS 1.0.0
## AI READING INSTRUCTION
Leer [SPEC] y [BUG] para operar el agente.
Leer [NOTE] solo si falta contexto de integracion.
[?] = no verificado, marcar incertidumbre.
Leer [NOTE] solo si falta contexto de integracion.
[?] = no verificado, marcar incertidumbre.
## 1. INPUTS / OUTPUTS
**[SPEC]**
- Input: account_id, date_range, platforms: [meta|google|both]
- Output: PDF informe ES + JSON metricas
- Rate: max 50 campanas/ejecucion · 10 ejecuciones/h/cliente
- Modelos: sonnet → analisis · haiku → clasificacion anomalias
- Output: PDF informe ES + JSON metricas
- Rate: max 50 campanas/ejecucion · 10 ejecuciones/h/cliente
- Modelos: sonnet → analisis · haiku → clasificacion anomalias
## 2. CONFIGURACION
**[SPEC]**
| ENV VAR | Requerida | Notas |
|---|---|---|
| META_ACCESS_TOKEN | si | nunca commitear |
| GOOGLE_ADS_DEVELOPER_TOKEN | si | — |
| GOOGLE_ADS_CUSTOMER_ID | si | — |
| CLAUDE_API_KEY | si | — |
| OUTPUT_DIR | si | ruta local PDFs |
|---|---|---|
| META_ACCESS_TOKEN | si | nunca commitear |
| GOOGLE_ADS_DEVELOPER_TOKEN | si | — |
| GOOGLE_ADS_CUSTOMER_ID | si | — |
| CLAUDE_API_KEY | si | — |
| OUTPUT_DIR | si | ruta local PDFs |
## 3. BUGS CONOCIDOS
**[BUG] Meta paginacion cuelga >500 ad sets**
Sintoma: agente se cuelga en cuentas con >500 ad sets
Causa: cursor pagination Meta API, default page_size=25
Fix: forzar page_size=100 en MetaClient
Causa: cursor pagination Meta API, default page_size=25
Fix: forzar page_size=100 en MetaClient
**[BUG] Google Ads API v14 auth silencioso**
Sintoma: auth falla sin error legible
Causa: v14 deprecada y desactivada
Fix: usar api_version: v17
Causa: v14 deprecada y desactivada
Fix: usar api_version: v17
**[BUG] Anomalias falsas <7 dias datos**
Sintoma: deteccion anomalias poco fiable
Causa: baseline estadistico insuficiente
Fix: validar date_range ≥ 7 dias antes de ejecutar
Causa: baseline estadistico insuficiente
Fix: validar date_range ≥ 7 dias antes de ejecutar
**[NOTE]**
Creado en enero 2025 para ahorrar 4h/semana a account managers. Los bugs de Meta y Google se descubrieron en produccion con clientes reales.
−59%
tokens consumidos por IA
leyendo solo [SPEC]+[BUG]
leyendo solo [SPEC]+[BUG]
3
bugs surfaceados explicitamente
antes dispersos en prosa
antes dispersos en prosa
0
herramientas externas necesarias
Markdown estandar, sin tooling
Markdown estandar, sin tooling
Artefacto final
campaign-analyzer.hads.md — documento completo
El documento HADS generado para el agente CampaignAnalyzer de CULTIVA IA. Listo para ser leido por Claude Code, Cursor o cualquier LLM con instrucciones de lectura explicitas.
campaign-analyzer.hads.md
# CampaignAnalyzer Agent
**Version 2.3.0** · CULTIVA IA · 2026-06-16 · HADS 1.0.0
## AI READING INSTRUCTION
Leer [SPEC] y [BUG] para hechos autoritativos y fallos conocidos.
Leer [NOTE] solo si se necesita contexto adicional de integracion o historia.
Los bloques [?] son no verificados — tratar con confianza reducida.
Optimizacion: leer primero headings, luego [SPEC]+[BUG] en secciones relevantes.
Leer [NOTE] solo si se necesita contexto adicional de integracion o historia.
Los bloques [?] son no verificados — tratar con confianza reducida.
Optimizacion: leer primero headings, luego [SPEC]+[BUG] en secciones relevantes.
## 1. QUE HACE / INPUTS Y OUTPUTS
**[SPEC]**
| Campo | Detalle |
|---|---|
| input.account_id | ID de cuenta Meta o Google Ads |
| input.date_range | ISO 8601: YYYY-MM-DD/YYYY-MM-DD — minimo 7 dias |
| input.platforms | meta | google | both |
| output.report | PDF en espanol con analisis + recomendaciones |
| output.metrics | JSON con KPIs clave (CTR, CPC, ROAS, anomalias) |
| rate_limits | max 50 campanas/ejecucion · 10 ejecuciones/h/cliente |
**[SPEC]**
Modelos LLM:
· claude-3-5-sonnet-20241022 → analisis de rendimiento y recomendaciones
· claude-3-haiku-20240307 → clasificacion de anomalias (alta velocidad)
Pipeline: fetch datos → normalizar → detectar anomalias (haiku) → generar informe (sonnet) → PDF
· claude-3-5-sonnet-20241022 → analisis de rendimiento y recomendaciones
· claude-3-haiku-20240307 → clasificacion de anomalias (alta velocidad)
Pipeline: fetch datos → normalizar → detectar anomalias (haiku) → generar informe (sonnet) → PDF
## 2. CONFIGURACION
**[SPEC]**
# Variables de entorno requeridas — nunca commitear secrets
META_ACCESS_TOKEN="..." # token OAuth2 Meta Business
GOOGLE_ADS_DEVELOPER_TOKEN="..." # dev token Google Ads
GOOGLE_ADS_CUSTOMER_ID="123-456-7890" # sin guiones opcionales
CLAUDE_API_KEY="sk-ant-..." # clave Anthropic
OUTPUT_DIR="/var/cultiva/reports" # ruta absoluta, debe existir
# Google Ads API — VERSION CRITICA
GOOGLE_ADS_API_VERSION="v17" # v14 deprecada: auth falla en silencio
META_ACCESS_TOKEN="..." # token OAuth2 Meta Business
GOOGLE_ADS_DEVELOPER_TOKEN="..." # dev token Google Ads
GOOGLE_ADS_CUSTOMER_ID="123-456-7890" # sin guiones opcionales
CLAUDE_API_KEY="sk-ant-..." # clave Anthropic
OUTPUT_DIR="/var/cultiva/reports" # ruta absoluta, debe existir
# Google Ads API — VERSION CRITICA
GOOGLE_ADS_API_VERSION="v17" # v14 deprecada: auth falla en silencio
## 3. BUGS CONOCIDOS
**[BUG] Meta API — cuelgue en cuentas con mas de 500 ad sets**
Sintoma: agente se congela indefinidamente; no hay timeout explicito
Causa: cursor-based pagination de Meta API con page_size default (25); >500 objetos genera cursores corruptos
Afecta: cuentas con >500 ad sets activos — tipicamente clientes enterprise
Fix: establecer page_size=100 en MetaClient.__init__; verificado y funcionando
Causa: cursor-based pagination de Meta API con page_size default (25); >500 objetos genera cursores corruptos
Afecta: cuentas con >500 ad sets activos — tipicamente clientes enterprise
Fix: establecer page_size=100 en MetaClient.__init__; verificado y funcionando
# meta_client.py — linea ~47
self.page_size = 100 # NO usar default=25; causa cuelgue >500 ad sets
self.page_size = 100 # NO usar default=25; causa cuelgue >500 ad sets
**[BUG] Google Ads API v14 — fallo de autenticacion silencioso**
Sintoma: agente termina sin output; logs muestran 200 OK pero metricas vacias
Causa: API v14 fue desactivada por Google; las peticiones retornan datos vacios sin error HTTP
Afecta: cualquier instancia configurada con GOOGLE_ADS_API_VERSION=v14
Fix: usar GOOGLE_ADS_API_VERSION=v17 — unica version activa a fecha 2026-06
Causa: API v14 fue desactivada por Google; las peticiones retornan datos vacios sin error HTTP
Afecta: cualquier instancia configurada con GOOGLE_ADS_API_VERSION=v14
Fix: usar GOOGLE_ADS_API_VERSION=v17 — unica version activa a fecha 2026-06
**[BUG] Deteccion de anomalias — falsos positivos con menos de 7 dias de datos**
Sintoma: haiku clasifica fluctuaciones normales como anomalias; rate >60% FP
Causa: baseline estadistico insuficiente; el modelo necesita minimo 7 dias para calcular media movil
Fix: validar date_range ≥ 7 dias antes de llamar al detector; retornar error descriptivo si no se cumple
Causa: baseline estadistico insuficiente; el modelo necesita minimo 7 dias para calcular media movil
Fix: validar date_range ≥ 7 dias antes de llamar al detector; retornar error descriptivo si no se cumple
# campaign_runner.py — agregar antes de ejecutar
if (end_date - start_date).days < 7:
raise ValueError("date_range minimo 7 dias para deteccion de anomalias")
if (end_date - start_date).days < 7:
raise ValueError("date_range minimo 7 dias para deteccion de anomalias")
## 4. ARQUITECTURA
**[SPEC]**
┌────────────────────────────────────────────────────────────┐
│ CampaignAnalyzer v2.3 — Pipeline de ejecucion │
└────────────────────────────────────────────────────────────┘
Input (account_id + date_range + platforms)
│
▼
[MetaClient] + [GoogleAdsClient] ←── APIs externas
│ (fetch + normalize)
▼
[AnomalyDetector] ←── claude-3-haiku (clasificacion rapida)
│
▼
[ReportGenerator] ←── claude-3-5-sonnet (analisis + recomendaciones ES)
│
▼
Output: PDF (OUTPUT_DIR) + metrics.json
│ CampaignAnalyzer v2.3 — Pipeline de ejecucion │
└────────────────────────────────────────────────────────────┘
Input (account_id + date_range + platforms)
│
▼
[MetaClient] + [GoogleAdsClient] ←── APIs externas
│ (fetch + normalize)
▼
[AnomalyDetector] ←── claude-3-haiku (clasificacion rapida)
│
▼
[ReportGenerator] ←── claude-3-5-sonnet (analisis + recomendaciones ES)
│
▼
Output: PDF (OUTPUT_DIR) + metrics.json
## 5. CONTEXTO (lectura opcional para IA)
**[NOTE]**
CampaignAnalyzer fue construido en enero 2025 cuando los account managers de CULTIVA IA invertian 4h/semana en reports manuales de Meta y Google. El MVP tenia un solo modelo (sonnet) para todo; la arquitectura dual haiku+sonnet se adopto en v2.0 para reducir latencia y coste de clasificacion.
Los tres bugs documentados fueron descubiertos en produccion con clientes reales y costaron en total ~8h de debugging. Se documentan como [BUG] para evitar que futuros devs o agentes reproduzcan los mismos errores.
Los tres bugs documentados fueron descubiertos en produccion con clientes reales y costaron en total ~8h de debugging. Se documentan como [BUG] para evitar que futuros devs o agentes reproduzcan los mismos errores.
## 6. CHANGELOG
v2.3.0 (2026-06) — Fix page_size Meta, documentacion HADS
v2.2.0 (2026-03) — Migracion Google Ads API v14→v17
v2.1.0 (2025-11) — Validacion date_range ≥ 7 dias
v2.0.0 (2025-06) — Arquitectura dual haiku+sonnet
v1.0.0 (2025-01) — MVP inicial
v2.2.0 (2026-03) — Migracion Google Ads API v14→v17
v2.1.0 (2025-11) — Validacion date_range ≥ 7 dias
v2.0.0 (2025-06) — Arquitectura dual haiku+sonnet
v1.0.0 (2025-01) — MVP inicial
Como lo lee un LLM
Flujo de lectura optimizado para agentes
1
Leer Manifesto
AI READING INSTRUCTION primero
2
[SPEC] siempre
Hechos autoritativos, verdad actual
3
[BUG] siempre
Antes de generar cualquier codigo
4
[NOTE] opcional
Solo si [SPEC] no responde
5
[?] baja confianza
Marcar incertidumbre al responder