Demo: loop de ingeniería dirigido por un goal de producto

Un demo repetible (< 15 min, +5 con el Acto 3 de Linear) con Claude Code: en vez de iterar prompts a mano, se define un goal de producto y el agente itera el código usando un eval como única fuente de verdad, hasta cumplir el criterio o agotar los intentos.

El producto del demo: un clasificador de triage de mensajes de pacientes (urgente / cita / administrativo) definido en PRD.md.

Requisitos

• Node ≥ 20 (brew install node) — el demo no tiene dependencias de npm, y los Actos 1 y 2 corren 100 % local, sin red.
• Claude Code corriendo en la raíz de este repo.
• Solo para el Acto 3: una cuenta de Linear y conexión a internet. Es opcional; sin eso el demo funciona igual.

Estructura

Ruta	Qué es	¿Sobrevive al reset?
PRD.md	El requisito de producto (incluye la regla de negocio)	✅
eval/cases.json	100 mensajes reales con su etiqueta correcta	✅
eval/run-eval.mjs	El gate: npm run eval	✅
.claude/skills/goal/	El comando /goal que ejecuta el loop	✅
.claude/skills/linear-*/	/linear-setup, /linear-report y /linear-reset (Acto 3)	✅
.mcp.json	El servidor MCP de Linear, versionado con el repo	✅
CLAUDE.md	Reglas del juego para el agente (inmutables, anti-overfitting)	✅
RUNBOOK.md	Guion minuto a minuto para el presentador	✅
docs/LINEAR.md	Por qué la integración con Linear está montada así	✅
scripts/reset.sh	Vuelve el repo al estado greenfield	✅
src/	El producto — lo construye el agente en vivo	❌ se borra
runs/	Historial de evals + dashboard (report.html)	❌ se borra

Cómo correr el demo

# 1. Estado limpio (greenfield): no existe src/, el eval da 0%
npm run reset -- --yes
npm run eval                 # → pass rate: 0%

# 2. Dashboard en el proyector (se refresca solo cada 3 s)
npm run dashboard

# 3. En Claude Code — el camino ingenuo (vibe coding):
#      construye el producto que describe PRD.md
#    y correr npm run eval → queda en ~60-80% con violaciones de la regla de negocio

# 4. En Claude Code — el loop:
#      /goal sube el pass rate de npm run eval a 90% o más, y que ningún caso
#      urgente quede clasificado como administrativo. Para después de 5 intentos.

# 5. Al terminar: git diff --stat demo-baseline muestra que solo cambió src/

# 6. Opcional (Acto 3): /linear-setup antes del paso 4 y /linear-report después

El guion completo con tiempos y plan B está en RUNBOOK.md.

Acto 3 (opcional): Linear como herramienta de producto

Para audiencias de producto, el demo cierra el círculo con Linear vía MCP:

# en Claude Code, con linear-server autenticado (/mcp)
/linear-setup     # el PRD se vuelve un proyecto + un issue cuya
                  # definición de done es literalmente `npm run eval`
/goal ...         # el loop corre; Linear no se toca
/linear-report    # sube la evidencia: tabla de intentos leída de
                  # runs/history.json, checkboxes marcados por el gate,
                  # estado del issue y status update del proyecto
/linear-reset     # entre ensayos: el board vuelve a cero

La regla que hace que esto valga algo: el agente solo puede escribir en Linear números que salieron del gate, y el issue pasa a Done únicamente si el eval salió en verde. El razonamiento completo y los antipatrones están en docs/LINEAR.md.

El servidor MCP viaja en .mcp.json: quien clone el repo solo corre /mcp para autenticar.

Cómo funciona el loop

/goal es un skill del repo (.claude/skills/goal/SKILL.md): corre el eval para conocer el punto de partida, y en cada intento anuncia una hipótesis, modifica solo src/, vuelve a correr el eval y usa los fallos como feedback. Para cuando el eval sale en verde (≥ 90 % y 0 urgente→administrativo) o al agotar los intentos. Cada corrida del eval alimenta el dashboard runs/report.html, que muestra la curva de pass rate por intento y el detalle caso por caso.

Reset (repetir el demo desde cero)

npm run reset            # muestra qué va a borrar y pide confirmación
npm run reset -- --yes   # sin confirmación

npm run reset restaura el repo y /linear-reset restaura el board: cada uno se queda en su lado. Un script del repo no borra cosas de tu herramienta de management.

⚠️ El reset hace git clean -fd: lo que no esté commiteado se pierde sin recuperación. Si cambias la configuración del demo, commitea y mueve el ancla antes de resetear.

El ancla es el tag git demo-baseline: el reset descarta todo lo que no esté en ese tag (código del agente, commits del demo, historial de evals) y preserva toda la configuración. Si cambias la configuración del demo (PRD, casos, skill), haz commit y mueve el ancla: git tag -f demo-baseline.