Cómo va una idea desde la conversación con el usuario hasta producción, usando Spec-Driven Development (SDD) con agentes Claude Code especializados.
📄 El contrato OpenAPI YAML es la fuente de verdad que conecta a todos los agentesDos aplicaciones independientes que se comunican solo por HTTP — no comparten código.
GET /v1/agent-catalog y GET /v1/activity-catalogagents-web ──HTTP REST──▶ agents-hub · CI con path filtering: cada app dispara solo sus propios checks
El agente principal orquesta los handoffs (los subagentes no pueden llamarse entre sí). Toda conversación comienza con el product-owner.
El usuario describe un problema, feature o bug. El PO discrimina si es bug o feature, hace preguntas de clarificación y crea el ticket en Notion con criterios de aceptación en formato Gherkin (Given/When/Then).
Genera el plan de pruebas en Gherkin — Happy Path, No Happy Path, Bordes (+ Performance/BD cuando aplica) — y lo appendea al final del mismo ticket. En modo coordinado recibe el contenido en el prompt (sin notion-fetch); en modo autónomo el usuario lo invoca con la URL del ticket.
Convierte el Gherkin en un contrato OpenAPI YAML (página hija del ticket: "Contrato OpenAPI — [nombre]"), valida la cobertura Gherkin ↔ OpenAPI y escribe la spec técnica con subtareas y estimación de complejidad.
Backend: lee el contrato → genera modelos Pydantic + endpoint stubs → implementa (FastAPI, Temporal, Alembic). Frontend: lee el contrato → genera tipos TS + schemas Zod + hooks → implementa (Next.js, Zustand, TanStack). Pueden trabajar en paralelo porque ambos parten del mismo contrato.
Revisa calidad, patrones y convenciones del monorepo, detecta dead code y over-engineering, y valida que la implementación matchee el contrato OpenAPI. Cualquier desviación del contrato es un hallazgo bloqueante. Según lo que tocó el cambio, se suman los reviewers especializados (ver sección 4).
Genera test cases directamente desde las validaciones del schema OpenAPI (maxLength, format, enum, required) y los ejecuta contra el stack local (Docker: DB, logs, containers). Contrato del equipo: local verde antes de push.
Crea el tag de release (QA-YYYYMMDD-XX / RC-YYYYMMDD-XX), dispara el GitHub Action de build + update Argo, sincroniza secrets en GCS y vigila el rollout en GKE.
Un solo artefacto conecta a todos los roles. Nadie implementa "de memoria": todo se deriva del contrato.
Después del code-reviewer, se activan solo cuando el cambio toca su dominio.
tenant_id.docs/architecture/*.dsl alineado con el código.make test-story STORY=ADA-XXX, diagnostica fallos y reporta. Regla del equipo: local verde antes de push.Estas reglas no se negocian — son lo que hace que el pipeline funcione.
Cuando alguien describe un problema, feature o bug, SIEMPRE se delega primero al product-owner para discriminar, clarificar y crear el ticket en Notion.
Inmediatamente tras crearse el ticket, el qa-testing-planner recibe el page_id + contenido de la historia y appendea el plan de pruebas al mismo ticket (nunca reemplaza contenido existente).
El tech-lead DEBE publicar el contrato OpenAPI YAML antes del handoff a los devs. Si no existe contrato, los devs no comienzan: piden al tech-lead que lo genere.
Si el code-reviewer detecta desviaciones entre la implementación y el contrato OpenAPI, el hallazgo es bloqueante: se corrige antes de seguir.
Todo se orquesta desde el Makefile en la raíz del monorepo.
| Comando | Qué hace |
|---|---|
make setup | Setup inicial de ambos proyectos |
make infra | Levanta infraestructura: Postgres, Temporal, Mercure |
make hub-api | Corre agents-hub API local en :8000 |
make web | Corre agents-web dev server en :3000 |
make up / make down | Docker: levanta / detiene todo el stack |
make test | Corre todos los tests |
make db-upgrade | Aplica migraciones de base de datos |
make lint | Lint de agents-web |