Proceso de funcionalidad
Principio rector: cuantas menos decisiones tome el agente por sí mismo, más estable será el resultado. Cada fase termina con un artefacto en docs/features/<slug>/ y una verificación («puerta»). Donde se indique, el avance solo continúa tras la confirmación humana.
Cómo escribir el código – fsd-frontend; verificación de basura – anti-slop-review; inicio de sesión y sesión – frontend-auth-session.
1. Fases
| # | Fase | Artefacto | Aprueba | Puerta |
|---|---|---|---|---|
| 0 | Preparación | rama | — | Árbol de trabajo limpio; después de instalar dependencias y migraciones – /clear |
| 1 | PRD | prd.md | persona | No-Objetivos completados; criterios verificables; sin soluciones técnicas |
| 2 | Especificación | spec.md, hasta 150 líneas | persona | Cubre todos los criterios del PRD y nada más |
| 3 | Tareas | tasks.md | persona | Una tarea – un commit; la primera – tracer bullet |
| 4 | Investigación | registro en tasks.md | — | Solo lectura; encontrado qué reutilizar |
| 5 | Tracer bullet | commit | — | Un escenario recorre todo el flujo y se ve en el navegador |
| 6 | Compilación | commit por tarea | — | Test primero para lógica; pnpm check en verde |
| 7 | Revisión | informe de reviewer | persona por hallazgos | Hallazgos confirmados corregidos |
| 8 | Navegador | e2e para camino crítico | — | Escenarios del PRD se cumplen sin errores en consola |
Una tarea pequeña (un commit, sin nuevo comportamiento para el usuario) omite las fases 1–3, pero los No-Objetivos aún se registran en la descripción de la tarea. La omisión de una fase se menciona explícitamente, no ocurre en silencio.
2. PRD
Plantilla – docs/features/_template/prd.md.
- El agente redacta un borrador a partir de la solicitud y solo pregunta lo indispensable para continuar. El resto son suposiciones en «Preguntas abiertas», que la persona confirma al aprobar.
- Los No-Objetivos son obligatorios. Enumera lo que al agente le gustaría hacer «de paso»: responsive para nuevos tamaños, animaciones, i18n, cacheo, panel de administración, refactorización de código vecino. Sin esta lista, la funcionalidad se expande.
- Los criterios de aceptación son verificables: «Dado / Cuando / Entonces», no «cómodo» o «rápido».
- Sin bibliotecas, archivos ni esquemas: se trata de «qué y por qué», no de «cómo».
3. Especificación
Plantilla – docs/features/_template/spec.md.
- Hasta 150 líneas. La redacta el agente, la aprueba la persona. Una especificación larga generada automáticamente es peor que ninguna: satura el contexto y difumina las decisiones.
- Antes de redactar, una breve revisión de solo lectura de las capas afectadas: qué existe ya, qué reutilizar.
- Contiene: dónde vive el código (capas, slices), contratos de datos (esquemas zod, mapeo DTO), API (entrada, salida, errores →
kind), estados de UI, casos límite, escenarios de aceptación con nivel de prueba. - La especificación vive junto con el código. Si el comportamiento cambia, se corrige
spec.mden el mismo commit. El código que diverge de la especificación es un defecto de uno de los dos.
4. Tareas
Plantilla – docs/features/_template/tasks.md.
- Una tarea – un commit, tras el cual el proyecto compila y las verificaciones pasan. Si el agente llega a un callejón sin salida, es más barato revertir al commit anterior que discutir con el modelo.
- La tarea cabe en una sola sesión; cada una tiene un «listo cuando».
- La primera tarea es tracer bullet; luego vienen estados, casos límite, pulido.
5. Investigación (solo lectura)
Antes de cada tarea, sin modificar archivos:
AGENTS.mdde las carpetas afectadas;- código existente que resuelve algo similar (
rgpor nombres y contratos); - contratos y tipos de los que depende la tarea.
Si lo encontrado se necesita más adelante – 2–3 líneas en el registro de tasks.md.
6. Tracer bullet
Un escenario de principio a fin: ruta → página → funcionalidad o entidad → request() → manejador de ruta o backend → resultado en pantalla.
- Es código de producción, no un prototipo: capas correctas, contratos reales de la especificación.
- Intencionadamente sin: validación detallada, pulido de estados de carga y error, estilos, casos límite.
- Si el backend no está listo – manejador MSW o manejador de ruta que devuelve datos según el contrato de la especificación; esto se anota en
tasks.md. - Verificación – en el navegador: el escenario se cumple y no hay errores en consola.
7. Compilación
- Lógica – test primero: funciones puras, stores, mapeo de respuestas, hooks con bifurcaciones. El test debe fallar por la razón esperada, luego el código. Un test escrito después del código tiende a verificar lo que el código hace, no lo que se requiere.
- Maquetación y estilos – sin test previo: los verifica el navegador (fase 8), el camino crítico se cubre con e2e.
- Después de la tarea:
pnpm check, commit (lint-staged verificará los archivos modificados). - Detención: tres intentos fallidos de corregir lo mismo – alto. Describe a la persona qué probaste y cuál es la hipótesis. No ajustes los tests al código, no desactives reglas del linter, no debilites tipos.
- Todo lo que esté fuera de la tarea – al registro «después», no en este commit.
8. Revisión
- Subagente
reviewer(.claude/agents/reviewer.md) con contexto limpio: pásale la ruta aprd.mdyspec.mdy el rango de commits; el diff lo leerá él mismo. El autor del código ve peor sus propios errores: en su contexto hay argumentos de por qué la solución es correcta. - Los hallazgos confirmados se corrigen; los discutibles los decide la persona.
- La seguridad la revisa también la persona: inicio de sesión, sesiones, redirecciones, cookies, entrada de usuario en HTML. Las verificaciones en verde no lo garantizan: en la práctica, una redirección abierta ha pasado tests, y una página de error ilegible, el linter.
9. Navegador
- Next.js: habilidad
next-dev-loopconagent-browser, si está instalado; si no, Playwright o Chrome DevTools MCP. - Recorre los escenarios del PRD, incluidos los negativos: datos vacíos, error de red, reenvío. Revisa la consola y los estados de las peticiones.
- Para UI – tema claro y oscuro, ancho de teléfono.
- Camino crítico – test e2e en
e2e/. - Listo cuando cada criterio del PRD esté verificado; en el mensaje final – lista de criterios y cómo se verificó cada uno.
10. Contexto
- El estado del trabajo vive en
docs/features/<slug>/, no en la conversación: una nueva sesión comienza leyendoprd.md,spec.md,tasks.md. - Después de pasos ruidosos (instalación, migraciones, logs largos) –
/clear. - Experimentos paralelos – en
git worktree, no en la rama de trabajo.
11. Qué no hacer
- Preguntas aclaratorias infinitas: pregunta solo lo que bloquea; el resto – suposiciones en el PRD.
- Orquestadores con muchos agentes: basta con un ejecutor y un revisor.
- Especificaciones y documentación que nadie ha aprobado ni lee.
- Omitir fases en silencio y «de paso arreglé».