urieljareth/MP-Manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
MP-Manager/docs/GUIA_AGENTICA.md
T
urieljareth a35d26fac0 Primer commit
2026-05-30 14:31:19 -06:00

13 KiB
Raw Permalink Blame History

Guía agentica MP Manager

Para Uriel. Cómo usar Claude Code como manager operativo experto del ecosistema MP Manager. Si quieres el detalle técnico de las tools, lee AGENT_TOOLS.md; esta guía se enfoca en cómo pedirle las cosas y qué esperar de vuelta.

1. ¿Para qué sirve esto?

Claude Code es tu manager operativo de MP Manager: le pides auditorías, syncs, búsquedas, fixes o investigaciones, él decide qué tools llamar, te muestra preview, espera tu confirmación y aplica. Reglas de negocio de Monte Providencia (jerarquía de duplicados, Marca↔sucursal, multi-empeño, etc.) ya están en su contexto vía CLAUDE.md + memory.

2. Arrancar una sesión productiva

  1. Abre Claude Code en h:\MegaSync\Proyectos\MP Manager.

  2. Verifica que el MCP está conectado:

    Prompt: "Lista las tools de mp-manager que tienes disponibles."

    Deberías ver 16 tools: list_accounts, search_contacts, sync_missing_contacts, etc. Si no aparecen, ve a §8 Troubleshooting.

  3. (Opcional) Pídele un snapshot inicial para calibrar el estado actual antes de operar — receta 1 abajo.

3. Contrato de seguridad (cómo funciona desde tu lado)

Todo lo que muta datos en Bucéfalo sigue siempre este protocolo de 5 pasos. No hay excepciones — aunque parezca trivial, aunque ya lo hayas autorizado antes para algo similar.

  1. Dry-run primero. Claude llama la tool con apply=False (o el script con --dry-run) y te muestra el plan con números reales: cuántas entidades, qué cambia, valor estimado.
  2. Confirmación explícita tuya. Claude te pregunta antes de mutar. Tú respondes en lenguaje natural ("sí, aplica", "adelante"). Sin tu input no toca producción.
  3. Piloto en 1 sucursal. La primera aplicación va a UNA sucursal (la que indiques, o Claude propone una de bajo volumen / demo). Se valida el resultado contra la API antes de continuar.
  4. Batch al resto solo tras OK del piloto. Si el piloto se ve bien, se aplica al lote completo — también con confirmación explícita.
  5. Rollback disponible. Cada apply genera run_id que queda en script_audit (reversible desde el dashboard del SPA). Para cambios destructivos también se guarda snapshot en generated/migrations/.

Banderas rojas — pídele preview de nuevo o cancela si pasa esto:

  • Te ofrece aplicar sin haberte mostrado preview primero.
  • Quiere ir directo al batch sin piloto (especialmente para fixes nuevos o lógica no probada).
  • Aplica y reporta un cambio que no esperabas.
  • Te dice "ya lo apliqué" sin run_id.
  • No te ofrece rollback cuando algo salió mal.

4. Recetas de uso frecuente

Cada receta trae el prompt literal, qué tools dispara, y qué esperar.

4.1 Snapshot diario del estado

Prompt: "Dame un snapshot del estado actual: totales globales, descuadre Marca vs sucursales si hay, y los últimos errores de los logs."

Por qué funciona: arranca get_global_metrics + agent_audit_report (o run_script audit_brand_vs_branches_totals --json) + error_logs. Es read-only puro, sin riesgo.

Qué esperar: 3 bloques — números globales, lista corta de diferencias por sucursal, top errores con error_id.

4.2 Investigar descuadre de totales

Prompt: "Hay descuadre en el conteo de contactos entre Marca y sucursales. Investiga la causa siguiendo la identidad estándar de descomposición (multiplicidad A-C, missing-in-brand B, solo-Marca D) y prepárame un plan dry-run para corregir lo accionable."

Por qué funciona: la frase "identidad estándar" activa la regla contact_descuadre_reconciliation de memory. Claude correrá audit_brand_vs_branches_discrepancy --show-unsynced-contacts --json y luego sync_missing_contacts(apply=False) para preview.

Qué esperar: descomposición numérica del descuadre + lista de contactos accionables + propuesta de qué sincronizar.

4.3 Buscar un contacto a través de sucursales

Prompt: "Busca a <nombre> con teléfono <10 dígitos> en todas las sucursales y dime en cuáles aparece y si tiene oportunidades."

Por qué funciona: list_accounts para iterar + search_contacts por location. La regla matching_rules (phone+name ≥0.80) ya está en memory, así que evita falsos matches por solo teléfono.

Qué esperar: tabla con sucursal, contact_id, nombre coincidente, count de opps. Si quieres detalle, pídele "ahora dame las opps del contacto X en la sucursal Y".

4.4 Detectar y resolver duplicados cross-branch

Prompt: "Corre el detector de duplicados cross-branch y propónme el cleanup usando la jerarquía estándar (valor monetario → status activo → contacto más antiguo → TIENDA). Quiero ver el plan antes de aplicar."

Por qué funciona: dispara run_script find_cross_branch_duplicates --json y luego cleanup_cross_branch_duplicates --apply=False. La jerarquía está en memory (duplicate_resolution_rules).

Qué esperar: lista de pares duplicados con la decisión propuesta por cada par. Cuando confirmes, ejecuta con --apply --yes --run-id <uuid> y te da el run_id.

4.5 Sincronizar contactos faltantes Sucursal → Marca

Prompt: "Sincroniza a Marca los contactos de sucursal que aún no estén replicados. Hazme dry-run primero con muestra de 5 para revisar el payload."

Por qué funciona: sync_missing_contacts(apply=False). El parámetro "muestra de 5" hace que Claude limite el preview en el resumen para que sea legible.

Qué esperar: muestra de 5 payloads + total proyectado. Tú confirmas → ejecuta con apply=True + confirm_token → te devuelve el run_id.

4.6 Sincronizar oportunidades faltantes (gap multi-empeño)

Prompt: "Replica las opps adicionales por contacto que el workflow n8n [1604] no copió a Marca (gap multi-empeño). Dry-run primero."

Por qué funciona: el "gap multi-empeño" es una regla conocida (memory: opp_multiplicity_replication_gap). Claude llama sync_missing_opps(apply=False) que usa el campo ID Oportunidad Sucursal para filtrar.

Qué esperar: número de opps adicionales detectadas por contacto + plan de inserción.

4.7 Auditar custom fields y tags vs estándar de Marca

Prompt: "Audita el estado de custom fields y tags en todas las sucursales contra el estándar de Marca. Reporta divergencias y propón fix si las hay."

Por qué funciona: combina run_script audit_custom_fields_schema --all --json + run_script audit_tags_across_accounts --json. El estándar (folders Contact/General Info/Additional Info/Block/Form, tags formulario/revisar/qa-test) viene de memory.

Qué esperar: tabla de divergencias por sucursal + propuestas (fix_opportunity_picklist_alignment, cleanup_and_unify_tags, create_missing_brand_fields, apply_custom_field_layout).

4.8 Triage de errores recientes

Prompt: "Revisa los errores de las últimas 24 horas y dime qué patrones se repiten. Diagnóstica los top 3."

Por qué funciona: error_logs(limit=200) + agrupa por event / exception_type. El playbook de triage Playwright (memory playwright_log_triage) se activa si los errores son del browser.

Qué esperar: agrupación por tipo de error + lista de error_id para profundizar + diagnóstico breve.

4.9 Rollback de un run que rompió cosas

Prompt: "El run <run_id> causó problemas. Revisa qué cambió y prepárame el rollback. No apliques hasta confirmar."

Por qué funciona: Claude lee script_audit.script_change_log por run_id, te muestra qué cambió (planned/applied), y propone revertir vía dashboard del SPA o script de rollback equivalente.

Qué esperar: lista de cambios del run + instrucciones para revertir + advertencia si algún cambio dependiente lo bloquea.

4.10 Tarea ad-hoc con script huérfano

Prompt: "Necesito correr <nombre_script>.py con args <...>. Antes inspecciónalo, dime qué hace exactamente, si es mutador y qué efectos tiene. Luego dry-run y, si todo se ve bien, aplico yo."

Por qué funciona: run_script(expect_json=True) para los read-only; para mutadores Claude te explicará qué pide el contrato (--apply --run-id) antes de tocar nada.

Qué esperar: resumen del docstring + categorización + propuesta de invocación + preview.

5. Cómo formular prompts que funcionen bien

  • Sé específico con la sucursal: usa el nombre comercial o el location_id. "En Cancún" funciona; "en una sucursal" no.
  • Empieza con preview: para cualquier cosa que muta, di "dry-run primero" o "muéstrame el plan antes de aplicar".
  • Pide volcado a archivo si esperas reportes largos: el MCP lo hace automático >8KB, pero decir "guárdame el reporte completo y devuélveme solo el summary" lo fuerza.
  • Apóyate en reglas conocidas: frases como "usa la jerarquía estándar", "aplica el patrón Monte Providencia", "respeta la regla de matching phone+name" activan memory entries específicas y evitan que Claude reinvente.
  • Acota el alcance al confirmar: en vez de "sí aplica todo", di "aplica solo los primeros 10" o "aplica solo Cancún". Reduce blast radius.

6. Qué NO pedirle (límites realistas)

  • Playwright sin sesión configurada: tocar ghl_browser_*.py cuando el storage_state o el perfil Chrome no están al día va a fallar. Primero python start_persistent_profile.bat o validar generated/browser/session.json.
  • Mutaciones masivas sin audit reciente: pedirle "limpia todos los duplicados" sin haber corrido el detector primero es receta para borrar lo que no querías.
  • Tocar workflows en producción a ciegas: antes de modificar workflows usa run_script health_check_workflows.
  • Cosas fuera del alcance E3: marketing tradicional, diseño para imprenta, asesoría legal/financiera. Claude te redirigirá al área que corresponda.
  • Imprimir o exfiltrar tokens del CSV: aunque se lo pidas, no debe; los tokens son secretos.

7. Evolucionar el ecosistema (loop de mejora continua)

Conforme uses el MCP vas a notar fricción. Pídele a Claude que la resuelva:

  • "Este flujo lo repito mucho — conviértelo en tool dedicada del MCP" → edita mcp_server/server.py y manifest.py.
  • "Script X no aparece en el inventario" → refresca con python scripts/audit_agent_readiness.py, y si conviene, regístralo en SCRIPTS_METADATA del script_runner.py para que también salga en el SPA.
  • "Cuando agregues un script nuevo, asegúrate que cumple la convención" → docstring header (Category:, Mutates:, Tool-safe:), soporta --json, y si muta también --apply + --run-id. El audit lo verifica.
  • "Hay un patrón repetido en N sucursales que aún no automaticé" → pídele que diseñe un nuevo script + tool en una sola pasada.

8. Troubleshooting rápido

Síntoma Qué pedirle a Claude
No veo las tools de mp-manager "Verifica .mcp.json en la raíz y arranca python -m mcp_server manualmente para ver el error de stdio."
Claude aplicó algo sin pedir confirmación "Reporta el run_id y haz rollback inmediato. Después explica cómo te saltaste el preview."
El reporte es demasiado largo "Ya debe estar volcado en generated/agent/runs/. Dame solo el summary ejecutivo del report_path."
Los totales no cuadran con el dashboard "El cache SQLite puede estar stale. Corre sync_all_accounts (endpoint o script) y repite el audit."
El MCP devuelve audit_report.json no existe "Corre python scripts/audit_agent_readiness.py antes de invocar tools que dependen del reporte."
Un script huérfano que necesito ya "Inspeccióna scripts/<nombre>.py, dime qué hace, y úsalo con run_script siguiendo el contrato."
Sospecho que la API de Bucéfalo está rate-limited "Revisa error_logs por códigos 429 y dime si conviene bajar SYNC_ENGINE_MAX_WORKERS o reintentar más tarde."

Si el problema persiste, AGENT_TOOLS.md §10 tiene el detalle técnico.

9. Referencias cruzadas

  • docs/AGENT_TOOLS.md — catálogo técnico de las 16 tools del MCP, contrato confirm_token, formatos de respuesta.
  • CLAUDE.md — arquitectura del backend MP Manager (módulos, flujo de datos, reglas críticas).
  • AGENTS.md — comandos, gotchas de Bucéfalo, paginación, reglas Monte Providencia.
  • docs/PLAYWRIGHT_SESSION.md / PLAYWRIGHT_PATTERNS.md — automatización browser.
  • generated/agent/tools_manifest.json — inventario navegable autogenerado (tools + scripts + endpoints).
  • generated/agent/audit_report.json — salud actual del ecosistema (correr python scripts/audit_agent_readiness.py para refrescar).
Reference in New Issue View Git Blame Copy Permalink