NTT DATA · Train-the-Trainers IA · Día 3

Guía de Laboratorio — SDD + Fundamentos de Agentes (ReqFlow)

Día 3: OpenSpec (SDD) + fundamentos de agentes (routing, evaluator, HITL) sobre un producto real compuesto por 3 repositorios. Este día trabaja sobre el mismo reqflow-workspace/ de los días previos.

4 sesiones · S1–S4 ReqFlow · 3 repos OpenSpec · GitHub MCP Gate: handoff Día 4
README STEP-BY-STEP Flujos Challenge

Antes de empezar

Entrada del día (handoff Día 2)
  • Trabaja desde reqflow-workspace/ (workspace de producto).
  • Debe existir .vscode/mcp.json con github-official y toolset projects.
  • Debe existir el Project ReqFlow del Día 2 con issues en repos correctos.
python tools/check_handoff.py --day 2 ../reqflow-workspace

Si falla, parte de checkpoint/day2 (instructor).

Recursos del día
  • s03-reqflow-setup/CASE.md: contratos, restricciones y DoD vigentes de tu producto.
  • laboratory-flows.html: diagrama animado del flujo.
  • s01–s04: módulos prácticos (material/anexos).

Los pasos operativos están en esta guía. Los módulos siguen existiendo como materiales/anexos.

Laboratorio

S1OpenSpec
Sesión S1

OpenSpec / Spec Kit + Constitution (conceptos) → contrato inicial

Instalar/preparar OpenSpec en workshop-auth-backend y producir los primeros artefactos del cambio.

~1h
Materiales
  • Repo foco del día: workshop-auth-backend.
  • OpenSpec CLI + proveedor GitHub Copilot.
  • Skill reqflow-definition-of-done disponible en .github/skills/.
  • OpenSpec es la implementación SDD del laboratorio; Spec Kit/Constitution quedan como comparación conceptual de S1 (no se ejecuta un segundo flujo paralelo).
  • Decisión del laboratorio: schema estándar proposal → specs → design → tasks → apply + GitHub en paralelo (Issue = trabajo/trazabilidad, Project = prioridad, branch = rama del Issue, PR = revisión, checks = evidencia).

Mantén VS Code abierto en reqflow-workspace/, pero limita prompts operativos al backend.

Pasos
01
Preparar OpenSpec en workshop-auth-backend
Instala la CLI, inicializa seleccionando GitHub Copilot, conserva el schema estándar spec-driven y configura el contexto/reglas del laboratorio.
02
Elegir un Issue real del Project ReqFlow (estado Todo)
Selecciona el issue que guiará el cambio en workshop-auth-backend. Verifica que exista y esté priorizado en el Project.
03
Crear proposal + specs/ desde el Issue
Genera el contrato de cambio (qué se cambia, criterios, no-funcionales) antes de implementar. Pasa por GATE HUMANO antes de continuar a S2.
Output esperado
  • openspec/changes/<CHANGE_NAME>/proposal.md creado y aprobado.
  • openspec/specs/ con al menos 1 archivo.
  • Issue, branch del Issue y Project alineados como trazabilidad en paralelo.
Break / transición
S2Spec→Plan→Tasks
Sesión S2

Specify → Plan → Tasks → Validate (diseño, plan y gates)

Convertir la especificación en diseño y tareas; validar antes de implementar.

~1h
Materiales
  • Artefactos OpenSpec generados en S1.
  • Baseline (Day1): docs/ENDPOINTS.md y docs/TESTING.md del producto.
  • tasks.md puede solaparse parcialmente con el GitHub Issue; durante el taller esa duplicación es intencional.
Pasos
01
Crear design.md (Plan)
Decisiones técnicas, impacto, estrategia incremental y riesgos.
02
Crear tasks.md (Tasks)
Checklist de implementación vinculada al Issue. Mantén GitHub como tracking de trabajo comprometido. GATE HUMANO antes de validar.
03
Validar (Validate) antes de tocar código
Ejecuta openspec validate y revisiones humanas de los artefactos (Specify/Plan/Tasks). Recién después sigue el baseline de characterization tests en S4.
Output esperado
  • Artefactos de OpenSpec listos para aplicar (Specify/Plan/Tasks validados).
  • Gates humanos realizados antes de implementación.
  • openspec validate ejecutado sin errores sobre proposal/specs/design/tasks.
Break / transición
S3Agentes
Sesión S3

Fundamentos de agente: model + tools + context + loop

Consolidar el workspace multi-repo, skills y GitHub MCP oficial como “tools” del agente.

~1h
Materiales
  • Módulo de setup: s03-reqflow-setup — 3 repos (workshop-login-frontend, workshop-auth-backend, workshop-requirements-api) + 1 workspace de producto + GitHub MCP oficial + Project ReqFlow.
  • Módulo de skills: s02-agent-skills — discovery-analysis, spec-writing, architecture-decision, issue-implementation, reqflow-definition-of-done.
  • Módulo de agentes: s01-custom-agents — roles PM/PO, Discovery, Architect, Developer con límites explícitos.
  • Modelo mental: Agent = quién soy + límites; Skill = cómo ejecuto una práctica; Caso = qué problema resuelvo; OpenSpec = qué cambio está definido; MCP = qué sistema externo puedo operar.

Estos módulos son anexos/materiales. La ejecución paso a paso está en esta guía.

Pasos
01
Copiar los Custom Agents al workspace
Copia los templates desde bcp-ai-lab-day-03/templates/agents/ hacia reqflow-workspace/.github/agents/ (en S4 paso 0 también a workshop-auth-backend).
02
Probar los límites de un agente aislado
Selecciona un solo Custom Agent (Discovery, PM/PO, Architect o Developer) sin usar tools y verifica que explique su responsabilidad y a qué rol debe pasar lo que no le corresponde.
03
Verificar MCP oficial + Projects habilitado
Confirma que github-official expone tools de Projects y que puedes leer Projects vía MCP.
04
Completar backlog (sin inventar trabajo)
Discovery revalida HALLAZGOS.md y convierte hallazgos revisados en issues reales y verificables en el repo correcto.
05
De single-agent a routing
Mapea cada rol a un tipo de trabajo: producto/alcance → PM/PO, hallazgo → Discovery, diseño → Architect, implementación → Developer. Prepara el routing explícito de S4.
Output esperado
  • reqflow-workspace/.github/agents/ con pm-po.agent.md, discovery.agent.md, architect.agent.md y developer.agent.md.
  • Project ReqFlow usable vía MCP (lectura demostrable).
  • Backlog consistente (issues reales en repos correctos).
  • Participante puede explicar que Agent != prompt largo y justificar por qué una tarea se enruta a un rol y no a otro.
Break / transición
S4Apply + PR
Sesión S4

Patrones: routing, evaluator, HITL → PR final

Implementar con OpenSpec apply, proteger comportamiento con characterization tests y cerrar con PR auditable.

~2h
Materiales
  • Módulo SDD: s04-openspec-sdd
  • Ruta alternativa (solo referencia): GitHub Copilot Agents
  • Routing: PM/PO → necesidad/alcance/proposal-specs; Architect → design/tasks; Developer → characterization, apply e implementación.
  • Evaluator: openspec validate, tests, diff, Definition of Done, GitHub checks.
  • HITL: el participante revisa y decide antes de aceptar cada artefacto y antes de integrar el cambio.
  • Personalización opcional de fin de día: templates/openspec/schemas/reqflow-github/ (elimina tasks.md, deja el tracking en GitHub Issues; cambia el proceso, no la funcionalidad de ReqFlow).
Pasos
01
Confirmar el routing del Issue
Verifica que proposal/specs/design/tasks ya pasaron por PM/PO y Architect antes de que Developer implemente.
02
Proteger baseline (characterization)
Asegura que el comportamiento actual quede cubierto antes de implementar.
03
Aplicar e implementar incrementalmente
Usa OpenSpec apply, implementa, ejecuta tests y evidencia.
04
Evaluator + DoD + PR
Ejecuta Definition of Done, abre PR con Closes #N y revisa checks. GATE HUMANO de cierre antes de integrar a main.
Output esperado
  • PR final en workshop-auth-backend con evidencia y DoD.
  • .github/agents/ y .github/skills/ versionados en main.
  • Routing, evaluator y HITL identificables en el PR final (quién decidió qué y con qué evidencia).
HANDOFF · cierre del día Checklist para iniciar el Día 4

Desde la carpeta del laboratorio, ejecuta el chequeo. Si falla, no continúes al Día 4.

python tools/check_handoff.py --day 3 ../reqflow-workspace

Criterio: al menos 1 repo en [OK] + artefactos OpenSpec + agentes/skills + tag.