203 lines
13 KiB
Markdown
203 lines
13 KiB
Markdown
# 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](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](#8-troubleshooting-rápido).
|
|
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](AGENT_TOOLS.md#10-troubleshooting) tiene el detalle técnico.
|
|
|
|
---
|
|
|
|
## 9. Referencias cruzadas
|
|
|
|
- [docs/AGENT_TOOLS.md](AGENT_TOOLS.md) — catálogo técnico de las 16 tools del MCP, contrato `confirm_token`, formatos de respuesta.
|
|
- [CLAUDE.md](../CLAUDE.md) — arquitectura del backend MP Manager (módulos, flujo de datos, reglas críticas).
|
|
- [AGENTS.md](../AGENTS.md) — comandos, gotchas de Bucéfalo, paginación, reglas Monte Providencia.
|
|
- [docs/PLAYWRIGHT_SESSION.md](PLAYWRIGHT_SESSION.md) / [PLAYWRIGHT_PATTERNS.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).
|