TheFittClub Vault

AGENTS

5 min read

AGENTS.md — Instrucciones para agentes/LLMs trabajando en este vault

Si eres una IA leyendo esto: este archivo es tu briefing obligatorio antes de tocar nada. Lee las 5 reglas y la sección “Si la tarea es…” — tardas 2 minutos y evitas romper la coherencia del negocio.

Este vault sigue la convención abierta AGENTS.md. CLAUDE.md (raíz) es solo un puntero hacia este documento.

Contexto en 3 frases

Este vault es la memoria operativa de TheFittClub (Gala Calero, entrenadora suelo pélvico). Los datos de negocio (revenue, alumnas, contactos, lanzamientos) están en una arquitectura de 3 capas diseñada para que cada dato viva en un solo sitio: NEGOCIO_SSOT.md. Si la rompes, los números empezarán a contradecirse silenciosamente entre docs.

Las 5 reglas inquebrantables

  1. Un dato vive en 1 sitio. El valor canónico de cada métrica está en NEGOCIO_SSOT.md. Todo lo demás lo deriva.
  2. SSOT es inmutable. No añadas wikilinks [[...]] ni referencias a otros .md dentro de NEGOCIO_SSOT.md. Refs a .json/.csv (datos crudos) sí están permitidas.
  3. El frontmatter de BUSINESS_INTELLIGENCE.md no se edita a mano. Se regenera con python3 scripts/audit/sync_ssot_to_frontmatter.py desde el SSOT.
  4. Prosa sin números mutables. Si vas a mencionar un dato canónico (114 alumnas, $30.973 revenue, 10.863 contactos), no lo escribas como literal. Usa Dataview inline:
    • En BUSINESS_INTELLIGENCE.md: `= this.alumnas_legacy_pago`
    • En cualquier otro doc: `$= dv.page("BUSINESS_INTELLIGENCE").alumnas_legacy_pago`
    • Excepción: datos históricos puntuales atados a una fecha del pasado (ej. “$9.232 del lanzamiento de Feb 2024”, “51 bajas el 20-Nov-2025”) sí pueden ir en prosa — no pueden driftear.
  5. Valida antes de marcar la tarea como hecha. 
    python3 scripts/audit/audit_ssot.py --strict
    Exit code 0 = puedes commitear. Exit code 1 = revisa _docs/audits/ssot_drift_<fecha>.md y arregla los hallazgos.

Si la tarea es…

…actualizar un dato del SSOT (nuevo lanzamiento, contactos, segmento, evento)

Flujo recomendado (un solo comando, valida y commitea):

python3 scripts/audit/vault_update.py --no-edit --auto-commit -m "<descripción concisa>"

Pasos previos:

  1. Edita NEGOCIO_SSOT.md con el tool Edit (la única edición manual de valores numéricos).
  2. Si añades un campo nuevo que aún no existe en BI, primero amplía FRONTMATTER_TO_SSOT en scripts/audit/audit_ssot.py y, si es una nueva celda en una tabla del SSOT, amplía el parser en parse_ssot().
  3. Ejecuta el comando arriba. Sincroniza BI, audita en estricto, y commitea.

Cheat sheet con 5 casos comunes (lanzamiento, contactos, evento crítico, segmento, estado de producto): _GUIA_ACTUALIZACION_DATOS.md.

…crear un doc nuevo de negocio (análisis, referencia, dashboard)

  1. Copia _TEMPLATE_DOC_NEGOCIO.md como base. Renómbralo con el slug del doc.
  2. Rellena frontmatter (title, type, updated, ssot: "[[NEGOCIO_SSOT]]").
  3. Mantén el banner > 📋 **Datos canónicos:** [[NEGOCIO_SSOT]] en el cuerpo.
  4. Si necesitas mostrar datos del SSOT, usa Dataview inline (ver Regla 4).
  5. Si el doc es estratégico (lo va a leer una IA o humano para entender negocio), añádelo a:
    • _INDEX_NEGOCIO.md → tabla “Mapa de documentos”
    • scripts/audit/audit_ssot.py → STRATEGIC_DOCS (cobertura de wikilink)
    • scripts/hooks/pre-commit → WATCHED_REGEX (validación local)
    • .github/workflows/audit-ssot.yml → ambos paths (validación CI)
  6. Valida con audit_ssot.py --strict antes de commitear.

…crear un doc nuevo NO de negocio (idea, briefing, post IG, etc.)

Va a su carpeta normal (00_Home/Ideas/, 40_Contenido_Redes/, 99_Archivo/Historico_Social/, etc.). No requiere plantilla.

Pero si mencionas un número de negocio, sigue la Regla 4 (Dataview inline). El auditor flageará hardcodes incluso en docs no estratégicos.

…editar un doc existente

  1. Lee primero el banner > 📋 **Datos canónicos:** si existe — te indica qué doc es la fuente.
  2. Si vas a añadir/cambiar un número canónico en prosa, usa Dataview inline.
  3. Si vas a tocar NEGOCIO_SSOT.md, lee este archivo entero antes y usa el flujo de “actualizar un dato”.
  4. No toques BUSINESS_INTELLIGENCE.md frontmatter — se regenera por script.

…hacer commit

# El pre-commit hook valida automáticamente si está activo:
git config core.hooksPath scripts/hooks  # una sola vez por clon
 
# Si quieres validar manualmente antes:
python3 scripts/audit/audit_ssot.py --strict

Nunca uses --no-verify salvo emergencia documentada. Si el hook bloquea, es porque hay drift real.

Patrones rápidos: SÍ vs NO

Caso❌ NO✅ SÍ
Mencionar alumnas en prosa nueva"Tenemos 114 alumnas legacy""Tenemos `$= dv.page("BUSINESS_INTELLIGENCE").alumnas_legacy_pago` alumnas legacy"
Actualizar el revenue totalEditar BI frontmatter a manoEditar SSOT y correr vault_update.py
Añadir un doc estratégicotouch nuevo_doc.md y empezar a escribircp _TEMPLATE_DOC_NEGOCIO.md y editar
Referenciar a otro doc desde SSOTAñadir [[BUSINESS_INTELLIGENCE]] en SSOTMover la referencia a _INDEX_NEGOCIO.md
Resolver fallo del pre-commit hookgit commit --no-verifyLeer el reporte y arreglar el drift real

Archivos críticos — extrema precaución

ArchivoRegla
NEGOCIO_SSOT.mdSolo tablas. Sin wikilinks salientes ni refs a .md. Es la única fuente de verdad de valores numéricos.
99_Archivo/.../BUSINESS_INTELLIGENCE.md (frontmatter)NUNCA editar a mano. Se regenera con sync_ssot_to_frontmatter.py.
scripts/audit/*.pyCualquier cambio aquí afecta a la validación de todo el vault. Lee el código antes de editar.
scripts/audit/render_strategic_doc.pyAplana Dataview+wikilinks para empujar al dev repo. Si lo cambias, valida con docs ejemplo antes de mergear.
_INDEX_NEGOCIO.mdMapa de roles por doc. Actualizar cuando se añade/elimina un doc estratégico.
_TEMPLATE_DOC_NEGOCIO.mdPlantilla canónica para nuevos docs de negocio. Si la cambias, todos los docs nuevos heredarán el cambio.
10_Marca/Brand.md, 10_Marca/Estrategia.md, 40_Contenido_Redes/Email_Brief_L9.mdCanónicos aquí. Renderizados al dev repo vía .github/workflows/sync-dev-repo-snapshots.yml. NO editar nunca la copia del dev repo a mano: se sobreescribe en el próximo render.

Si dudas

Lee, en este orden:

  1. README_ESTRUCTURA_2026.md — sección “Arquitectura de datos (3 capas)”
  2. _GUIA_ACTUALIZACION_DATOS.md — flujo guiado para datos
  3. _INDEX_NEGOCIO.md — mapa de roles por doc
  4. _docs/audits/ssot_drift_<última-fecha>.md — último reporte del auditor (te dice cómo está el sistema ahora mismo)

Si después de leer eso sigues sin saber qué hacer, pregunta antes de commitear. Es más barato hacer una pregunta que arreglar un drift propagado en 5 docs.

Si eres una IA específica

  • Anthropic Claude (Claude Code, SDK): lees CLAUDE.md automáticamente al iniciar sesión. Es un puntero que te trae aquí.
  • OpenAI Codex / Cursor / Aider / Jules / Zed: cargan AGENTS.md (este archivo) por convención.
  • Otras IAs (ChatGPT, Gemini, Copilot Chat sin agent): el humano debe pegar este archivo o decir “lee AGENTS.md antes de tocar nada y obedece las 5 reglas”.

Las reglas son idénticas para todas. La convención del archivo es lo único que cambia.

Graph View

Backlinks