← Todas las entradas
terminado

Implementar un PoC multiagente

Stack: Claude Code · Playwright · Angular · Node.js

Arquitectura para implementar multiagentes.claude/agentsLíder técnicoCoordinadorFase 1AnalistaConstructorVerificadorEspecificación ejecutable + fuente de conocimientodecidereportapide la especificaciónFase 0encargoentregadefectos o aprobadoescribeconstruye contraprueba contra
circuito de trabajo · 5 roles

Para probar el método con un caso simple y real. El repositorio trae solo la app original: páginas armadas en el servidor con Node.js, Express y plantillas EJS. Todo lo demás (la estructura del proyecto, los agentes, las specs y el plan) lo arma el Analista a partir de un solo prompt. Los agentes construyen después la versión en Angular.

Qué necesitas: Claude Code, Node.js 20 o superior y git. La app original está en el repositorio github.com/yabrvod/poc-multiagente; su dirección va en el archivo .env del primer paso. Si quieres probar con tu propia app, pon su repositorio en lugar de ese, con la app en la carpeta original/.

Fase 0 · El Analista entiende y especifica

Una sesión normal de Claude Code (se abre con claude). Conversa contigo, baja y prueba la app original, hace el levantamiento y deja todo especificado. Todavía no se construye nada.

Primero: crea el archivo con los datos del ejercicio

mkdir C:\poc
notepad C:\poc\.env

Escribe esto en el archivo y guárdalo:

POC_REPO=https://github.com/yabrvod/poc-multiagente.git
POC_USUARIO=prueba
POC_CLAVE=prueba123

Queda fuera del repositorio a propósito: la dirección del repositorio, el usuario y la clave no se escriben en el prompt ni en el proyecto. El Analista y las pruebas los leen de ahí. En el PoC no son credenciales reales, pero así se trabaja con las de verdad.

Nota: aunque en este caso el .env queda fuera del repositorio y git no lo ve, se recomienda excluirlo siempre con una regla en el .gitignore.

Después: en la misma terminal, abre Claude Code en esa carpeta

cd C:\poc
claude

Ábrelo ahí y no en tu carpeta de usuario: así los agentes quedan dentro del proyecto y no en tu configuración global.

Después pega el prompt para el Analista: ábrelo con Ver el prompt completo y usa el botón Copiar.

Ver el prompt completo
Tengo una app web que quiero migrar a Angular: páginas armadas en el servidor con Node.js, Express y plantillas EJS. Su repositorio solo trae la carpeta original/. Eres el Analista: vas a entenderla, armar el proyecto de migración y especificarla, para que después un equipo de agentes la construya. Hazlo todo de corrido; detente solo si algo falla o si hay algo que yo deba decidir.

No quiero que después, construyendo, el equipo me interrumpa pieza por pieza con dudas. Cuando termines el análisis, dame UNA SOLA LISTA con todo lo que necesite una decisión mía, junta. Si más tarde aparece algo que no estaba en esa lista, es que el análisis quedó corto: tu trabajo es que esa lista esté completa.

Los datos del ejercicio están en C:\poc\.env, fuera del repositorio: POC_REPO (dirección del repositorio), POC_USUARIO y POC_CLAVE (credencial de la app). Léelos de ahí cada vez que los necesites y no escribas sus valores en ningún archivo del proyecto (CLAUDE.md, conocimiento/, specs/, nuevo/ ni estado/): refiérete a ellos por su nombre. Si el archivo no existe o le falta alguno, detente y avísame.

Hay una sola excepción, y es necesaria: Angular corre en el navegador y no puede leer C:\poc\.env por su cuenta. Un script de arranque de la app nueva puede generar dentro de nuevo/ un archivo con la credencial (por ejemplo nuevo/src/assets/config.json). Ese archivo se genera al levantar la app, nunca se escribe a mano, va en .gitignore y no se versiona jamás. Ningún otro archivo del proyecto lleva esos valores, y el código fuente tampoco: los lee de ahí.

1. Bajar y probar: clona POC_REPO en C:\poc\poc-multiagente (si ya existe, no lo sobrescribas: avísame). Desde ahora trabaja solo dentro de esa carpeta. En original/, npm install y npm start en segundo plano; espera a que responda en http://localhost:8080 (máximo 3 minutos) y recórrela con POC_USUARIO y POC_CLAVE.

   No te bases solo en leer el código. Usa la app como la usaría alguien que quiere romperla: direcciones que no existen, barras y mayúsculas de más, parámetros vacíos, repetidos o mal escritos, formularios enviados vacíos o con espacios, recargar después de enviar, el botón atrás, y entrar directo a una página sin haber iniciado sesión. Anota exactamente qué hace el original en cada caso, aunque sea feo o parezca un error: eso también es comportamiento, y hay que copiarlo o decidir no copiarlo.

2. Montar el proyecto en C:\poc\poc-multiagente:
   - CLAUDE.md: qué se migra, dónde está cada cosa, cómo levantar las dos apps (original en 8080; nuevo/, en Angular, con ng serve --port 4201), dónde están los datos del ejercicio (C:\poc\.env, solo por nombre) y qué leer antes de trabajar.
   - conocimiento/reglas.md: no tocar original/, mismos textos y estados que el original, aserciones dinámicas en las specs, toda espera con tope y nunca escribir los valores de C:\poc\.env en el proyecto.
   - conocimiento/decisiones.md, con estas decisiones ya tomadas: las rutas se mantienen; la app nueva lee la API /api/pedidos del original; el aspecto puede mejorar, pero textos y mensajes quedan iguales; el login se valida en Angular contra POC_USUARIO y POC_CLAVE, que la app nueva recibe de C:\poc\.env al levantarse, sin escribirlos en su código, y la sesión va en sessionStorage (no es seguridad real); un número mal escrito se trata igual que el original (parseInt antes de llamar a la API); tras un error, los formularios se vacían como en el original; no se agrega un texto de "Cargando…" que el original no tiene.

     Además: como la vieja arma las páginas en el servidor y la nueva es Angular, seguro hay cosas que no se van a poder copiar igual. Búscalas AHORA, no después de construir. Como mínimo revisa: qué pasa con el botón atrás, con recargar, con el historial del navegador, con cómo queda escrita la dirección en la barra, con las direcciones que no existen y con el código de error que devuelve el servidor. Para cada una decide: la igualamos, o la aceptamos distinta y queda escrito por qué. Si se puede igualar, la decisión lleva su prueba en la spec; si se acepta distinta, dilo explícitamente y explica por qué ninguna spec la comprueba. Ninguna queda pendiente. Ante cualquier otra duda, la regla es: igual que el original.
   - plantillas/: encargo.md (pieza, ronda, objetivo, qué leer, qué puede y no puede tocar, entrega), ficha.md y reporte.md (primera línea: ESTADO: TERMINADO | CON DEFECTOS | BLOQUEADO).
   - estado/bitacora.md (una fila antes de cada paso) y estado/reportes/.
   - .gitignore con node_modules/ y .env, para que ningún archivo de datos o credenciales se suba nunca al repositorio.
   - Playwright: package.json y playwright.config.js con dos proyectos (original en http://localhost:8080 y nuevo en http://localhost:4201); el config carga C:\poc\.env con process.loadEnvFile y las specs toman la credencial de process.env. npm install y npx playwright install chromium.

3. Crear el equipo en C:\poc\poc-multiagente\.claude\agents\ (nunca en mi carpeta de usuario, ~/.claude), con el formato de agentes de Claude Code (name, description, tools, model):
   - equipo-coordinador (model: opus; tools: Agent(equipo-constructor, equipo-verificador), Bash, Read, Glob, Grep, Edit, Write): sigue estado/plan.md pieza por pieza, arma los encargos, lanza al constructor y después al verificador, máximo 3 rondas por pieza; anota la bitácora, marca el plan y me avisa. Las decisiones ya escritas en decisiones.md no se vuelven a consultar conmigo: se aplican.
   - equipo-constructor (model: sonnet; tools: Read, Glob, Grep, Edit, Write, Bash): construye una pieza en nuevo/ hasta que su spec pase con --project=nuevo; no toca original/, specs/ ni conocimiento/; entrega su reporte.
   - equipo-verificador (model: sonnet; tools: Bash, Read, Glob, Grep, Write): corre la spec y recorre los estados de la ficha comparando con el original; no corrige código; solo escribe su reporte, con evidencia y propuesta por defecto. Las divergencias ya aceptadas en decisiones.md no son defectos.
   Y C:\poc\poc-multiagente\.claude\settings.json: permite npm, npx playwright y ng sin preguntar; bloquea Edit en original/** (en Claude Code esa regla cubre también la escritura de archivos; no agregues una regla Write) y git push.

4. Crear inventario y SDD: completa conocimiento/inventario.md (una fila por página: ruta, funcionalidades, estados con el texto exacto de cada mensaje, validaciones, datos o API, complejidad y prioridad; al final, estimación en horas y orden). Con Playwright, toma una captura de cada página y de cada estado que se vea distinto (vacío, con datos, con error) en conocimiento/capturas/<pieza>-<estado>.png, y enlázalas desde su fila del inventario y desde su ficha. Por cada página, su ficha en conocimiento/fichas/<pieza>.md y su spec en specs/<pieza>.spec.js, en verde con --project=original.

   Las fichas y las specs salen del recorrido del punto 1, no solo del camino feliz. Cada spec debe comprobar, además de los estados: el título que aparece en la pestaña del navegador, la dirección exacta que queda en la barra después de cada acción, y al menos tres entradas inválidas distintas. Tienen que fallar si la app nueva se ve o se comporta distinto en cualquier detalle que yo pueda notar.

   Cada decisión de decisiones.md que fije un comportamiento (por ejemplo, que los campos se vacían tras un error) debe tener su comprobación en la spec de la pieza que afecta. Cada spec comprueba solo lo de su pieza: si un escenario necesita contenido de otra pieza, esa comprobación va en la spec de la otra. Una vez decidido un comportamiento, la spec exige ese único resultado y no acepta alternativas.
   - Fichas: escenarios Dado/Cuando/Entonces (estilo GitHub Spec Kit), uno por estado, con identificador E-01, E-02… y el texto exacto del mensaje del original; lo que falte decidir, marcado [POR DECIDIR].
   - Specs: una prueba por escenario con su identificador en el nombre, siguiendo las buenas prácticas oficiales de Playwright (getByRole/getByLabel, aserciones con expect que esperan solas, pruebas aisladas).

5. Crear plan: completa estado/plan.md con las piezas en orden, sus dependencias y su estimación. Todo lo que la app nueva comparta —rutas, configuración global del router, sesión, cabecera, servicios comunes— se resuelve completo en la primera pieza, para que después ninguna otra pieza tenga que tocar archivos compartidos.

No modifiques nada de original/. Al terminar, dame un resumen corto para aprobar: estructura creada, agentes, inventario, specs, la lista única de decisiones pendientes y plan.

Tú no lanzas la fase 1. Cuando yo apruebe, deja la app original corriendo y cierra diciéndome que siga con el Coordinador en otra terminal: cd C:\poc\poc-multiagente y claude --agent equipo-coordinador.

Prompt de la fase 0 para el Analista (versión 2)

Es la versión 2, corregida después de una primera corrida completa del PoC. Más abajo está qué cambió y por qué.

Qué hace el Analista con este prompt

El prompt le asigna el rol de Analista y le pide hacerlo todo de corrido, deteniéndose solo si algo falla o si hay algo que tú debas decidir. Además le exige entregarte una sola lista con todo lo que necesite una decisión tuya, para que nadie te interrumpa después durante la construcción. Sus 5 pasos, con los mismos nombres:

  1. Bajar y probar: clona el repositorio en C:\poc\poc-multiagente, levanta la app original (puerto 8080) y la recorre como alguien que quiere romperla: direcciones que no existen, parámetros mal escritos, formularios vacíos, recargar, el botón atrás. Anota qué hace el original en cada caso.
  2. Montar el proyecto: crea CLAUDE.md, el mapa que leen todas las sesiones; las reglas; las decisiones ya tomadas, más las diferencias entre las dos tecnologías que hay que igualar o aceptar por escrito; las plantillas; la bitácora; el .gitignore, y Playwright para probar la app original y la nueva.
  3. Crear el equipo en .claude/agents/ del proyecto: Coordinador, Constructor y Verificador, con permisos acotados (nadie puede tocar original/ ni hacer git push).
  4. Crear inventario y SDD (desarrollo guiado por especificación), página por página:
    • conocimiento/inventario.md: una fila por página, con sus estados y el texto exacto de cada mensaje, validaciones, datos y estimación.
    • conocimiento/capturas/: una imagen por estado distinto.
    • conocimiento/fichas/<página>.md: escenarios Dado/Cuando/Entonces (estilo GitHub Spec Kit).
    • specs/<página>.spec.js: una prueba de Playwright por escenario, en verde contra la app original. Además de los estados, cada spec comprueba el título de la pestaña, la dirección que queda en la barra y al menos tres entradas inválidas.
  5. Crear plan: estado/plan.md, con las piezas en orden, sus dependencias y su estimación. Lo compartido (rutas, sesión, cabecera) se resuelve en la primera pieza. El Coordinador lo sigue en la fase 1 y va marcando cada pieza.

Al final, sin haber tocado original/, te entrega un resumen para aprobar antes de construir: estructura, agentes, inventario, specs, la lista única de decisiones pendientes y plan.

Qué esperar: el Analista trabaja solo; no hace falta mirarlo. En nuestra prueba tomó unos 15 minutos. Espera a que te entregue en su terminal un resumen corto para aprobar. Si debajo aparece algo como "1 shell still running", es la app original corriendo en segundo plano: es normal y debe seguir así para la fase 1. Para entonces tendrás la app original en http://localhost:8080, la estructura del proyecto con los tres agentes en .claude/agents/, conocimiento/inventario.md con las 4 páginas y sus capturas, una ficha y una spec por página (todas en verde contra el original) y estado/plan.md. Mientras trabaja, puedes leer más abajo el ejemplo de lo que entrega y los pasos para cerrar la fase 0.

Si el Analista (la sesión donde pegaste el prompt) te pregunta algo: en el PoC tú eres el líder y decides. El criterio es ante la duda, igual que el original: el PoC mide si los agentes migran con paridad, no si mejoran la app. Si algo sí quieres mejorarlo, dilo y pídele que lo anote en conocimiento/decisiones.md. Las preguntas que ya conocemos (login, números mal escritos, formularios tras un error, "Cargando…") vienen decididas en el prompt, y lo que no se puede igualar por la tecnología lo resuelve el Analista y te lo informa como interpretación suya.

Cuando termine, puedes seguir conversándole. El Analista es una sesión normal: conoce todo lo que armó y puede ayudarte a revisarlo antes de aprobar. Por ejemplo:

Genera una página HTML en estado/resumen-fase0.html con el inventario y sus capturas, las fichas, el resultado de las specs, las decisiones y el plan, y ábrela en el navegador.

Prompt para pedir un resumen de la fase 0

Otras preguntas útiles: "¿qué estados del original no quedaron cubiertos por ninguna spec?", "explícame la spec de login prueba por prueba" o "¿qué pieza ves más riesgosa y por qué?".

Ejemplo: así queda el repositorio al terminar la fase 0

Todo, menos original/, lo crea el Analista. Es lo que generó en nuestra prueba; los nombres pueden variar algo entre corridas:

C:\poc\poc-multiagente\
├── original\                      venía en el repositorio (no se toca)
├── CLAUDE.md                      lo que toda sesión lee al empezar
├── .claude\
│   ├── agents\
│   │   ├── equipo-coordinador.md  los tres agentes del equipo (solo existen en este proyecto)
│   │   ├── equipo-constructor.md
│   │   └── equipo-verificador.md
│   └── settings.json              permisos: original\ bloqueado, npm y Playwright sin preguntar
├── conocimiento\
│   ├── reglas.md
│   ├── decisiones.md
│   ├── inventario.md              una fila por página, estimación y orden
│   ├── capturas\                  una por página y por estado distinto
│   └── fichas\                    login.md, pedidos.md, pedido.md, contacto.md
├── specs\                         una spec por página, en verde contra el original (y apoyo.js, lo común)
├── herramientas\                  capturas.js, para repetir las capturas
├── plantillas\                    encargo.md, ficha.md, reporte.md
├── estado\                        plan.md, bitacora.md, encargos\, reportes\
├── playwright.config.js           dos proyectos: original (8080) y nuevo (4201)
├── package.json
└── nuevo\                         vacía: la llena la fase 1

.claude/agents/equipo-verificador.md: así se ve un agente de Claude Code; arriba, entre ---, su configuración, y abajo, sus instrucciones.

---
name: equipo-verificador
description: Verifica una pieza ya construida en nuevo/ - corre su spec y recorre cada estado de la ficha comparando la app nueva (4201) con la original (8080). No corrige código; solo escribe su reporte en estado/reportes/ con evidencia y una propuesta por defecto para cada defecto. Lo lanza equipo-coordinador después del constructor.
tools: Bash, Read, Glob, Grep, Write
model: sonnet
---
Eres el **Verificador** del PoC multiagente. Eres el contrapeso del constructor: quien construye no se
verifica a sí mismo.

## Cómo trabajas
1. Lee el encargo y lo que lista: CLAUDE.md, reglas, decisiones, la ficha, sus capturas, la spec y el
   reporte del constructor.
2. Agrega una fila en estado/bitacora.md antes de empezar.
3. Comprueba que ambas apps responden (8080 y 4201, tope 3 minutos). Si no, BLOQUEADO.
4. Corre la spec en los dos proyectos y las de piezas ya terminadas con --project=nuevo (regresión).
5. Recorre cada escenario E-xx de la ficha en las dos apps, también lo que la spec no cubre.
6. Escribe el reporte en estado/reportes/<pieza>-r<n>-verificador.md:
   ESTADO: TERMINADO · CON DEFECTOS (con evidencia y propuesta) · BLOQUEADO.
…
## Límites
- No corriges código ni specs: solo lees, ejecutas y escribes tu reporte.
- Toda espera con tope. Nunca git commit ni git push.

conocimiento/inventario.md: una fila por página, con lo que se ve en la app original y el enlace a sus capturas.

Página de ingreso de la app original con el mensaje Usuario o clave incorrectos
capturas/login-error.png
Listado Mis pedidos de la app original con filtros por estado y número
capturas/pedidos-con-datos.png
PiezaRutaEstados y texto exacto de cada mensajeDatos o APIComplejidadPrioridadCapturas
login/login (+ /, /logout, protección de rutas)Error: "Usuario o clave incorrectos" · Expirada: "Tu sesión expiró. Vuelve a ingresar." · OK: va a /pedidosNinguno (sesión en sessionStorage)MediaAltainicial · error · expirada
pedidos/pedidos?estado=&numero=Con datos · Filtrado · Vacío: "No hay pedidos que coincidan con el filtro." · Sin sesión: va a /login?expirada=1GET /api/pedidosMediaAltacon datos · filtrado · vacío
pedido/pedido?numero=NCon datos · No encontrado: "Pedido no encontrado" · Sin sesiónGET /api/pedidos/{numero}BajaMediacon datos · no encontrado
contacto/contactoVacíos: "Completa todos los campos." · Correo: "El correo no es válido." · Enviado: "Mensaje enviado. Te responderemos a la brevedad."Ninguno (no envía nada)BajaBajainicial · vacíos · correo · enviado

conocimiento/fichas/<pieza>.md: la spec en lenguaje natural de una página. Ejemplo de contacto.md:

# Ficha: contacto

| Campo      | Valor                                                              |
|------------|--------------------------------------------------------------------|
| Ruta       | /contacto                                                          |
| Original   | original/views/contacto.ejs · original/server.js (GET/POST /contacto) |
| Spec       | specs/contacto.spec.js (E-01…E-09)                                 |
| Datos      | Ninguno: no se envía nada a ningún servidor                        |
| Depende de | login (sesión, cabecera)                                           |

## Qué hace
Formulario con Nombre, Correo y Mensaje. Valida que no haya campos vacíos (también solo espacios)
y luego que el correo contenga @. Si todo está bien, reemplaza el formulario por una confirmación.

## Escenarios
### E-05 Correo sin @
![contacto-error-correo](../capturas/contacto-error-correo.png)
- **Dado** que completé todo con el correo ana.correo.cl
- **Cuando** pulso "Enviar"
- **Entonces** veo "El correo no es válido." y los tres campos quedan vacíos (D-06).
…

specs/<pieza>.spec.js: la misma ficha, ejecutable con Playwright. Ejemplo de una prueba de contacto.spec.js:

// antes de cada prueba, un beforeEach inicia sesión con POC_USUARIO / POC_CLAVE (de C:\poc\.env) y abre /contacto;
// enviar(), esperarSoloMensaje() y esperarFormularioVacio() están al inicio del archivo
test('E-05 correo sin @: "El correo no es válido." y se vacía el formulario (D-06)', async ({ page }) => {
  await enviar(page, { nombre: 'Ana Pérez', correo: 'ana.correo.cl', mensaje: 'Hola' });
  await esperarSoloMensaje(page, CORREO);
  await esperarFormularioVacio(page);
  await expect(page.getByRole('button', { name: 'Enviar' })).toBeVisible();
});

estado/plan.md: el orden que seguirá el Coordinador. Las horas las estima el Analista según la complejidad; varían entre corridas (en nuestras dos pruebas dio 11,5 h y 16,5 h).

OrdenPiezaRutaDepende deEstimaciónEstadoRondas
1login/login, /, /logout + protección + cabecera—6 hPENDIENTE0/3
2pedidos/pedidos?estado=&numero=login5 hPENDIENTE0/3
3pedido/pedido?numero=Nlogin, pedidos3 hPENDIENTE0/3
4contacto/contactologin2,5 hPENDIENTE0/3

El resumen para tu aprobación (ejemplo de cómo lo entrega el Analista):

Terminé la preparación. original/ no se modificó y la app original sigue corriendo en 8080.
Specs: 40 pruebas en verde y 3 omitidas con --project=original (solo aplican a la app nueva).
Estructura: CLAUDE.md, conocimiento/ (reglas, decisiones, inventario, 4 fichas y 12 capturas),
plantillas/, estado/ y herramientas/capturas.js.
Agentes: equipo-coordinador (opus), equipo-constructor y equipo-verificador (sonnet).
Inventario: 4 páginas, 41 escenarios, todos con el texto exacto de sus mensajes.
Interpretaciones mías: parseInt solo en el detalle; sin required ni type="email"; …
Plan: login → pedidos → pedido → contacto, unas 16,5 h (estimación, no medición).
Para empezar la construcción, aprueba el plan.

Cómo se cierra la fase 0

  1. Espera el resumen. El Analista termina cuando te entrega en su terminal un resumen como el de arriba. Si te hace una pregunta antes, respóndela y sigue solo.
  2. Revísalo. Pídele el resumen en HTML o hazle preguntas sobre el inventario, las fichas y el plan. Es la base de todo lo que construyen los agentes.
  3. Resuelve lo pendiente. Si el resumen trae decisiones pendientes, respóndelas y espera a que actualice las fichas y las specs.
  4. Apruébalo. Escríbele, por ejemplo: "Apruebo el inventario, las fichas y el plan." El Analista no arranca la fase 1: te responde que sigas con el Coordinador en otra terminal.
  5. Deja esa terminal abierta y pasa a la fase 1 en otra. Volverás a esta al final, para el cierre.

Fase 1 · El Coordinador construye con sus agentes

El Coordinador es un agente: se abre en otra terminal, dentro del repositorio, con claude --agent equipo-coordinador. Sigue el plan pieza por pieza y es el único que lanza al constructor y al verificador. Tú solo intervienes cuando te avisa que cerró una pieza o que algo se bloqueó.

Abrir el Coordinador y darle el plan

En otra terminal: cd C:\poc\poc-multiagente y claude --agent equipo-coordinador. Tiene que abrirse dentro del proyecto, porque ahí están los agentes. Al abrirse no muestra nada: no se presenta ni pregunta, espera tu primer mensaje. Pégale (usa el botón Copiar):

Antes de empezar, dime en una línea cuántas piezas hay en el plan y con cuál partes. Después construye la app nueva siguiendo estado/plan.md. Para cada pieza, en el orden del plan:
1. Anota la fila en estado/bitacora.md, arma el encargo con plantillas/encargo.md y lanza a equipo-constructor.
2. Cuando entregue, lanza a equipo-verificador sobre la misma pieza y ronda.
3. Si el verificador reporta defectos, arma el encargo de la ronda siguiente con esos defectos (máximo 3 rondas). Si no converge o algo bloquea, detente en esa pieza y avísame con la evidencia.
4. Si el verificador dice TERMINADO, marca la pieza como cerrada en estado/plan.md y avísame en una línea.
5. Si el verificador encuentra un caso que la spec no cubre, anótalo en estado/specs-pendientes.md (pieza, caso y qué hace el original) para que el Analista lo agregue a la spec; tú no tocas specs/.

Al terminar todas, corre npx playwright test --project=nuevo completo y dame el resultado, con lo que tomó cada pieza frente a lo estimado en el plan.

Prompt de la fase 1 para el Coordinador

Qué esperar: el Coordinador trabaja solo; no hace falta mirarlo. Te escribe en su terminal en tres casos:

  • Cerró una pieza: un aviso de una línea. No tienes que responder.
  • Algo se bloqueó: te explica qué pasa y espera tu respuesta.
  • Terminó todas: te da el resultado de las specs contra la app nueva y lo que tomó cada pieza frente a lo estimado.

La app nueva queda en nuevo/ y se ve en http://localhost:4201. Cuando el Coordinador avise que terminó, sigue con Cuándo termina.

Ejemplo: así queda el repositorio al terminar la fase 1

C:\poc\poc-multiagente\
├── original\                          sin cambios
├── nuevo\                             ← la app Angular (la creó el constructor)
│   └── src\app\
│       ├── paginas\                   login, pedidos, pedido y contacto (leen la API del original, D-02)
│       ├── nucleo\                    sesión y protección de rutas
│       └── app.routes.ts              las mismas rutas del original (D-01)
├── conocimiento\ y specs\              sin cambios (los agentes no los tocan)
└── estado\
    ├── plan.md                        ← cada pieza marcada como cerrada
    ├── bitacora.md                    ← una fila antes de cada paso
    ├── specs-pendientes.md            ← casos que el verificador encontró fuera de las specs
    ├── encargos\                      ← uno por agente y ronda (lo arma el Coordinador)
    └── reportes\                      ← uno por agente y ronda
        ├── login-r1-constructor.md
        ├── login-r1-verificador.md        TERMINADO
        ├── pedidos-r1-constructor.md
        ├── pedidos-r1-verificador.md      CON DEFECTOS → hubo ronda 2
        ├── pedidos-r2-verificador.md      TERMINADO
        ├── pedido-r1-constructor.md
        ├── pedido-r1-verificador.md       TERMINADO
        ├── contacto-r1-constructor.md
        └── contacto-r1-verificador.md     TERMINADO

estado/encargos/pedido-r1-constructor.md: el encargo que el Coordinador le pasa al constructor (sale de plantillas/encargo.md; en una ronda 2 agrega los defectos del verificador). Resumido:

# Encargo: pedido · ronda 1 · constructor

Objetivo: construir el detalle de un pedido en nuevo/, leyendo
GET /api/pedidos/{numero} del original (D-02), con los mismos textos,
formatos ($1.234.567, dd-mm-aaaa) y estados que el original.
Criterio de cierre: specs/pedido.spec.js en verde con --project=nuevo
(y --project=original sigue en verde). Regresión: login y pedidos.

Qué leer: CLAUDE.md, conocimiento/reglas.md y decisiones.md,
conocimiento/fichas/pedido.md y sus capturas, specs/pedido.spec.js,
original/views/pedido.ejs. Piezas cerradas: login y pedidos.
Puede tocar: nuevo/**, su reporte y una fila de la bitácora.
No puede tocar: original/**, specs/**, conocimiento/**, estado/plan.md,
git commit / git push.
Entrega: estado/reportes/pedido-r1-constructor.md

estado/bitacora.md: el Coordinador anota cada paso antes de lanzarlo y su resultado al terminar; si algo se corta, se retoma desde la última fila sin resultado. Un extracto real:

QuiénPiezaRondaPasoResultado
Coordinadorpedidos1Lanzar equipo-verificador (13:06)CON DEFECTOS (13:06): 12/13; único defecto E-08, depende de la pieza pedido
Coordinadorpedidos1Detener y consultar al usuarioE-08 era error de la spec; el Analista la corrigió. Ronda 2 solo con verificador
Coordinadorpedidos2Lanzar equipo-verificador (15:02)TERMINADO (15:02): 24 passed, 2 skipped
Coordinadorpedido1Lanzar equipo-constructor (15:03)TERMINADO según constructor (15:03): 10 passed
Coordinadorpedido1Lanzar equipo-verificador (15:04)TERMINADO (15:05): 18 passed, 2 skipped; regresión 27 passed
Coordinadortodas—Correr la suite completaOK (15:09): nuevo 46 passed; original 40 passed, 6 skipped

estado/reportes/pedido-r1-constructor.md: lo entrega el constructor (sale de plantillas/reporte.md; la primera línea dice el estado). Resumido:

ESTADO: TERMINADO
# Reporte: pedido · ronda 1 · constructor

Resumen: se construyó el detalle /pedido?numero=N en
nuevo/src/app/paginas/pedido.ts, que lee GET /api/pedidos/{n} con
parseInt(numero, 10) (D-05). Si el número no es válido o la API falla,
muestra "Pedido no encontrado" (D-08). Se retiró el detalle provisorio.

npx playwright test specs/pedido.spec.js --project=nuevo
10 passed
npx playwright test specs/login.spec.js specs/pedidos.spec.js --project=nuevo
27 passed

estado/reportes/pedidos-r1-verificador.md: lo entrega el verificador, que además de correr la spec recorre los estados de la ficha. Resumido:

ESTADO: CON DEFECTOS
# Reporte: pedidos · ronda 1 · verificador

Resumen: la spec pasa en el original y en el nuevo pasan 12 de 13.
El único fallo es E-08, y su único motivo es que /pedido sigue siendo
provisorio (la pieza pedido no está construida).

npx playwright test specs/pedidos.spec.js --project=original --project=nuevo
23 passed, 2 skipped, 1 failed
  [nuevo] E-08 el número enlaza al detalle /pedido?numero=N

| Escenario     | Original | Nuevo | Evidencia                         |
| E-01 Con datos | OK      | OK    | h1, filtros, filas, $185.000 iguales |
| ...           |          |       |                                   |

Ese defecto no era del código: la spec de pedidos comprobaba el contenido del detalle, que es de otra pieza. El Coordinador se detuvo y consultó; el Analista movió esa comprobación a la spec de pedido y la ronda 2 fue solo de verificación. Por eso el prompt de la fase 0 ahora pide que cada spec compruebe solo lo de su pieza.

estado/plan.md al final: el Coordinador marca cada pieza y anota lo real.

OrdenPiezaEstimaciónEstadoRondasReal (bitácora)
1login6 hTERMINADO1/3≈ 8 min
2pedidos5 hTERMINADO2/3≈ 3 min
3pedido3 hTERMINADO1/3≈ 2 min
4contacto2,5 hTERMINADO1/3≈ 2 min

Son los archivos de nuestra corrida, resumidos. La fase 1 completa tomó unos 22 minutos de trabajo (15 de los agentes y 6 del Coordinador), sin contar el tiempo que la consulta esperó al líder, frente a 16,5 h estimadas. En tu corrida los tiempos y los defectos serán otros.

Si algo se corta

Se cerró la terminal, se acabaron los tokens o se cayó el equipo: vuelve a abrir claude --agent equipo-coordinador en el repositorio y pégale (usa el botón Copiar):

Lee estado/plan.md, estado/bitacora.md y los últimos reportes de estado/reportes/. Dime en qué quedó cada pieza (cerrada, en construcción, en verificación, bloqueada) y qué paso hay que relanzar. Cuando te lo confirme, sigue con el plan desde ahí.

Prompt para retomar con el Coordinador

Cuándo termina

Cuando el Coordinador avise que cerró la última pieza, vuelve a la terminal del Analista (la de la fase 0) y pídele que lo compruebe por su cuenta (usa el botón Copiar):

El Coordinador terminó la fase 1. Compruébalo por tu cuenta:

1. Revisa que la app original responda en http://localhost:8080 y la nueva en http://localhost:4201. Si alguna no responde, levántala en segundo plano (npm start en original/, npx ng serve --port 4201 en nuevo/), con un tope de 3 minutos.
2. Corre todas las specs contra la app nueva: npx playwright test --project=nuevo. Dime cuántas pasan y, si alguna falla, cuál y por qué.
3. Confirma que original/ no tiene cambios (git status original/).
4. Si existe estado/specs-pendientes.md, agrega esos casos a las specs y córrelas con --project=original y con --project=nuevo. Si alguno falla contra la app nueva, dime cuál.
5. Con estado/plan.md, estado/bitacora.md y estado/reportes/, arma una tabla por pieza: estimación, tiempo real, rondas y defectos encontrados.
6. Genera estado/resumen-fase1.html con todo eso y ábrela en el navegador.

Prompt de cierre para el Analista

El PoC salió bien si las 4 piezas quedaron cerradas, las horas reales están anotadas frente a las estimadas y hay una lista de lo que costó más de lo esperado. Con eso se decide si vale la pena escalar a un proyecto real, con más carriles en paralelo.

Versión 2 del prompt: qué cambió y por qué

La primera corrida completa del PoC necesitó 10 rondas y 5 paradas para consultar decisiones. Casi todo se debió a que las specs salieron de un recorrido feliz de la app, en vez de uno que buscara los bordes. Estos son los cuatro cambios del prompt de la fase 0:

  1. La lista única de decisiones, arriba del todo. Es el cambio que más pesa. La versión 1 decía "ante cualquier duda, igual que el original": una regla correcta, pero pasiva, que permitía esperar a que las dudas aparecieran solas. Aparecieron una por una durante la construcción, con una parada cada vez. La frase nueva convierte "avísame si hay dudas" en "demuéstrame que no quedan".
  2. Recorrido adversarial en el paso 1, antes de especificar. En la primera corrida ese recorrido sí ocurrió, pero lo hizo el Verificador en la fase 1, o sea después de construir, cuando cada hallazgo costaba una ronda entera.
  3. Las diferencias entre las dos tecnologías, buscadas de antemano. Las que aparecieron (historial, botón atrás, normalización de la dirección, código HTTP, recarga tras enviar, mayúsculas en la ruta) eran predecibles como clase. Escribirlas en la fase 0 habría evitado tres paradas. Además, una diferencia aceptada se documenta igual, diciendo por qué no la comprueba ninguna spec.
  4. Un mínimo de completitud para las specs. La versión 1 pedía "una prueba por escenario", y los escenarios eran la propia lista del Analista: un círculo, sin forma de notar lo que faltaba. Ahora se exige explícitamente el título de la pestaña, la dirección resultante y entradas inválidas. En la primera corrida el título faltaba en 3 de 4 specs, y la dirección tras filtrar fue el primer defecto de pedidos.
Corrida 1 (prompt v1)Corrida 2 (specs y decisiones ya corregidas)
Tiempo con agentes trabajando41 min15 min
Tiempo esperando decisiones3 h 46 min0
Rondas totales104
Paradas para consultar50
Resultado29/29 en verde29/29 en verde

Con una salvedad: la corrida 2 no fue un experimento limpio, porque heredó las specs ampliadas y las decisiones que salieron de los tropiezos de la corrida 1. La versión 2 del prompt busca llegar a ese punto de partida desde el principio.

Qué trae el repositorio

El repositorio yabrvod/poc-multiagente trae solo original/, la app que se migra, y un README. Todo lo demás lo genera el Analista en la fase 0.