Módulo 1.3 — Migración de sitios existentes

Haz un inventario funcional

Qué es: Mapea formularios, handlers, servicios, endpoints y estados antes de proponer tools.

Por qué aprender: La auditoría revela dónde ya existe la regla y dónde la interfaz contiene lógica que debe separarse.

Antes de modelar

Escribe la solicitud de la persona, el estado actual y la evidencia que probará la finalización.

Error de inicio

Empezar por el nombre de una función o por un botón produce una tool sin un objetivo humano claro.

Anticípate antes de abrir el código

¿Qué información cambia la decisión? ¿Qué efecto debe aparecer en la interfaz? Responde antes de implementar.

form -> submitHandler -> enrollmentService -> POST /api/enrollments

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

formularios

funciones JS

APIs

estado

Prioriza recorridos según su valor y riesgo

Qué es: No todas las funcionalidades merecen migrarse primero; combina frecuencia, valor, estabilidad y reversibilidad.

Por qué aprender: El recorte correcto permite aprender pronto sin empezar con una acción crítica o poco comprendida.

Pregunta	Contrato sólido	Contrato débil
¿Cuándo usarlo?	La descripción expresa la intención y el contexto.	“Hace cosas” o “gestiona”.
¿Qué recibes?	Solo los datos necesarios.	Objeto genérico e ilimitado.
¿Qué devuelve?	Estado y próxima acción verificables.	Texto sin protocolo.
¿Cómo falla?	Código, motivo y recuperación.	Excepción opaca.

Haz

✓ Usa verbos específicos.
✓ Delimita las entradas.
✓ Declara la evidencia.

Evita

✗ Mezclar intenciones.
✗ Aceptar cualquier objeto.
✗ Ocultar efectos.

prioridade = valor * frequencia * estabilidade / risco

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

valor

frecuencia

riesgo

estabilidad

Extrae lógica de la interfaz

Qué es: La misma función de dominio debe servir tanto para el clic humano como para la ejecución de WebMCP.

Por qué aprender: Compartir la lógica evita divergencias entre el flujo visual y el camino del agente.

Observa

Captura el estado, la entrada y el contexto antes de la acción.

Decide

Valida las precondiciones y elige la transición permitida.

Ejecuta

Aplica la regla compartida y respeta la cancelación.

Demuestra

Actualiza la interfaz y devuelve un resultado estructurado.

Punto de control

Si el paso 2 no se aprueba, la tool no intenta «arreglárselas»: devuelve una recuperación explícita.

async function iniciarInscricao(input, context) {
  return enrollmentService.start(input, context);
}

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

servicio común

UI adaptadora

herramienta adaptadora

regla única

Crea wrappers finos

Qué es: La tool traduce los argumentos, llama al servicio existente, actualiza la UI y devuelve una respuesta estructurada.

Por qué aprender: Los wrappers pequeños son más fáciles de revisar y no recrean la aplicación dentro del registro WebMCP.

CÓDIGO DE REFERENCIA

execute: async (input, { signal }) => {
  const result = await service.start(input, { signal });
  ui.showDraft(result);
  return result;
}

Entrada

Es pequeña, está descrita y se puede validar.

Ejecución

Reutiliza la regla real de la aplicación.

Salida

Permite verificar el efecto y continuar.

Lee el código como contrato

Subraya dónde se valida la entrada, dónde ocurre el efecto, dónde llega la cancelación y dónde se actualiza la UI.

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

traducción

servicio existente

UI sincronizada

retorno

Publica mediante mejora progresiva

Qué es: El recorrido humano sigue funcionando cuando WebMCP no existe o está desactivado.

Por qué aprender: Una tecnología experimental se incorpora como capacidad adicional, con observación y rollback.

Fallo provocado

Ejecuta el escenario con estado ausente, entrada no válida o capacidad no disponible.

Recuperación esperada

La respuesta informa qué falló, qué sigue siendo seguro y qué acción puede continuar.

Matriz mínima de pruebas

✓ camino feliz reproducible

✓ entrada inválida accionable

✓ la cancelación termina el trabajo

✓ el fallback preserva el recorrido

✓ la interfaz refleja el estado

✓ el backend mantiene la autorización

if (document.modelContext?.registerTool) {
  registerEnrollmentTools();
}

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

detección de funcionalidades

fallback

rollout

rollback

Entrega el dossier de migración

Qué es: El dossier conecta el inventario, el catálogo, los riesgos, la implementación, las pruebas y el plan de publicación.

Por qué aprender: La migración se vuelve revisable por producto, desarrollo, seguridad y operaciones.

Ejercicio de síntesis

1. Explica el problema sin usar el nombre de la tecnología.
2. Diseña el estado anterior y el posterior.
3. Implementa la prueba funcional más pequeña.
4. Provoca un fallo y registra la recuperación.
5. Entrega código, evidencia y una limitación conocida.

Desafío del módulo

Crear un inventario, un mapa de tools, riesgos, un plan de migración y una primera implementación en un sitio real.

Criterio del Integrator responsable

La entrega debe funcionar, explicar sus límites y preservar la opción humana cuando la capacidad experimental no esté disponible.

entrega/
  inventario.md
  catalogo-tools.json
  riscos.md
  prova-funcional/
  plano-rollout.md

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

mapa

riesgo

prueba funcional

rollout

📦 Entrega del módulo

Crear un inventario, un mapa de tools, riesgos, un plan de migración y una primera implementación en un sitio real.

Criterio de aceptación

La entrega funciona con soporte de WebMCP y mantiene la opción manual cuando la API no existe.

Evidencia

Incluye código, escenario probado, resultado observado y una limitación conocida.

← Volver a la ruta Próximo módulo: 1.4 →

Fuentes técnicas

Draft y repositorio oficial de WebMCP
Especificación renderizada
Snapshot oficial: 26/08/2026 · commit 41d12f0. La API declarativa sigue siendo experimental; valida el draft antes de producción.