”Lo he mirado y está bien” no prueba nada
Antes de construir nada le creo una ficha: qué se hace, cómo se demuestra que funciona y qué queda fuera. Todo lo que no decidas tu lo decidirá el agente.
La semana pasada dejamos el PRD con sus Must, sus Should y lo que no se construye en esta versión.
Un Must como "registro con email" parece claro hasta que alguien tiene que construirlo. ¿Hay que confirmar el correo? ¿Qué pasa si ese email ya existe? ¿Qué contraseña vale? Si nadie lo decide, lo decide el agente a su manera, y te enteras cuando ya está construido.
Por eso, en mi plantilla, ningún Must llega al código sin pasar antes por una ficha.
El agente no se equivoca al rellenar los huecos de un requisito: hace exactamente lo que le pediste, y le pediste poco.
Hola, soy Pol Marzà, AI Product Builder y cada semana escribo una nueva edición de Con Criterio, la newsletter sobre construir productos digitales con IA, con planificación, método y sin atajos. Si te han reenviado este email, puedes suscribirte aquí:
En este envío:
La ficha es el acuerdo, escrito antes del código, y cuándo no hace falta.
La tabla de cobertura, la parte de la ficha que de verdad importa.
Por qué el agente señala problemas antes de proponer soluciones, con un ejemplo real.
Tres estados para poder retomar el trabajo, y por qué se construye una fila cada vez.
Cómo pasar tu primer Must a ficha, paso a paso.
Preguntas para seguir el hilo con Claude.
1. La ficha es el acuerdo, escrito antes del código
El PRD describe el producto entero y el código es lo que acaba existiendo, pero entre los dos falta una pieza: la unidad de trabajo, lo que se acuerda, se construye y se da por terminado de una vez. Esa pieza es la ficha, un archivo en docs/features/ con cuatro partes:
Qué se construye.
Qué decisiones se han tomado.
Cómo se va a comprobar cada requisito.
Qué queda fuera.
La diferencia con el PRD es de nivel. El PRD dice qué quiere el producto y la ficha dice cómo se resuelve un trozo concreto y con qué se demuestra que funciona. Y lo más importante es el momento en que se escribe: antes de empezar, no reconstruida después a partir de lo que cambió en el código.
No todo merece una ficha. Yo la creo cuando el trabajo cierra algún requisito del PRD, toca más de tres o cuatro archivos o va a ocupar más de una sesión. Para un arreglo puntual, un cambio de texto o un ajuste de estilos, la descarto: basta con apuntarlo en el changelog al terminar. Tampoco escribo fichas retroactivas, porque una ficha existe para que no se pierda el acuerdo previo, y si ya hay código no queda nada que acordar.
2. La tabla de cobertura: ningún requisito sin su tercera columna
De toda la ficha, la parte que funciona como contrato es una tabla con tres columnas: el requisito, dónde se implementa y con qué se valida. Tiene una sola regla, y es innegociable: ningún requisito se queda sin la tercera columna rellena.
Hay tres formas válidas de rellenarla:
La primera es la ruta del test que lo validará, que no tiene que existir todavía: se escribe después de implementar. La segunda es una revisión humana, que vale tanto como un test siempre que diga qué se mira y qué tiene que verse, de forma que otra persona pueda repetirla y llegar a la misma conclusión. La tercera es la excepción, para lo que no tiene pantalla que mirar ni test que lo cubra, con la razón concreta y cómo se comprueba entonces. “No aplica” no es una razón, y “no me dio tiempo” tampoco: eso es un test pendiente.
Lo que se queda sin validar casi nunca se decide…
Nadie dice “este requisito no lo vamos a comprobar”. Simplemente no aparece en ningún sitio, y nadie lo echa de menos hasta que falla. Obligar a escribir la excepción convierte una omisión invisible en una frase que alguien puede leer y discutir.
Y esta regla no depende de la buena voluntad de nadie. La plantilla trae un script, scripts/verificar-cobertura.mjs, que se ejecuta en cada pull request y falla si una fila no tiene tercera columna, si una excepción no explica nada, si una revisión humana no dice qué se mira y qué tiene que verse o si una ficha dice estar terminada y le falta un test que prometió. La comprobación vive donde no se puede saltar, porque quien rellena la tabla es el mismo agente que tendría que cumplirla. Conviene saber lo que no hace: detecta el test prometido que no se escribió, no el test que no comprueba nada.
3. Por qué el agente señala problemas antes de proponer soluciones
Cuando la ficha está escrita, y antes de enseñármela, la skill /feature le pide al agente que la relea como un QA: buscándole los fallos, no defendiéndola. Busca cuatro cosas, que son las palabras ambiguas que cualquiera rellenaría a su manera (”rápido”, “válido”, “bien”), las contradicciones entre la ficha y el PRD, los casos límite sin cubrir y los choques con las reglas del proyecto.
Y aquí está la decisión que más me costó tomar: el agente presenta lo que encuentra como una lista numerada, sin proponer ninguna solución. Con el registro con email, la lista se parece a esto:
“Se registra” no dice si la cuenta queda activa al momento o después de confirmar el correo.
No está definido qué ve alguien que intenta registrarse con un email que ya existe.
No hay ningún criterio para la contraseña.
No se dice qué pasa si falla el envío del email de confirmación.
La razón es sencilla: si el agente propone la solución junto con el problema, acabas aceptando la suya sin pensar la tuya. Cada uno de esos puntos es una decisión de producto, y una decisión de producto que toma el agente por ti sigue siendo una decisión sin tomar.
Una lista de problemas sin soluciones te obliga a decidir; una lista con soluciones te invita a firmar.
Cada punto se cierra conmigo de una de tres formas: se corrige la ficha o el PRD, pasa a “Decisiones tomadas” con su motivo o pasa a “Fuera de esta feature”, para que no vuelva a discutirse a mitad de camino. Si el agente no encuentra nada, tiene que decirlo y explicar qué ha revisado.
4. Acordada, En construcción, Verificada: tres estados para poder retomar
Cada ficha lleva un estado, y se actualiza en el momento, no al final. Acordada significa que la ficha está escrita, revisada y validada conmigo, sin código todavía. En construcción significa que se está implementando y que la tabla ya no cambia sin avisar. Verificada significa que todos los requisitos tienen su validación hecha y pasando.
Sirve para retomar. Una sesión nueva que abre el proyecto sabe en dos segundos qué hay a medias y por dónde seguir, sin releer el repositorio entero ni fiarse de lo que recuerde de la conversación anterior.
Durante la construcción, cada fila de la tabla es una unidad de trabajo. El agente implementa un requisito, me dice qué ha cambiado y cómo verlo funcionando (qué abrir, qué hacer y qué debería aparecer) y se para hasta que le doy el visto bueno. Así reviso trozos que puedo comprobar, y un error en el segundo requisito no aparece cuando ya hay cinco construidos encima.
5. Cómo pasar tu primer Must a ficha, paso a paso
Si usas la plantilla, todo esto ya está montado. Si no, puedes copiar el formato de docs/features/README.md y seguir el mismo proceso:
Elige un Must que toque varias partes del proyecto. Si es un cambio pequeño, no lo conviertas en ficha.
Lanza
/featurecon el nombre de la feature. El agente lee el PRD para localizar qué requisitos cierra. Si no encaja con ninguno, te preguntará si es alcance nuevo, que va primero al PRD, o si queda fuera, que va amejoras/.Responde lo que no se puede deducir: qué tiene que poder hacer el usuario y qué queda explícitamente fuera.
Rellena la tercera columna de cada fila. Si no sabes cuál de las tres formas poner, pregúntalo. Y no uses la revisión humana para lo que un test cubriría bien: el test se repite solo en cada pull request, y la revisión depende de que alguien la haga.
Cierra uno a uno los puntos de la revisión, sin pedirle al agente que los resuelva por ti.
Da el visto bueno. La ficha pasa a En construcción, y a partir de ahí se construye una fila cada vez.
La semana que viene: los MODS de Claude Code
Estos tres estados van a aparecer otra vez dentro de dos semanas, en un panel que se colorea solo. Antes, el próximo número va de los mods de Claude Code: qué son, en qué se diferencian de una skill o de un MCP y cómo se pide uno sin escribir código.
Preguntas para seguir el hilo con Claude
Revisa el requisito [pega aquí un Must de tu PRD] como un QA: ¿qué palabras rellenarías a tu manera, qué casos límite no cubre y qué no se puede comprobar con un sí o un no? Dame solo la lista, sin soluciones.
Para cada requisito de esta ficha, ¿cuál de las tres formas de validación encaja mejor (test, revisión humana o excepción justificada) y por qué? ¿Hay alguno en el que haya puesto revisión humana y un test lo cubriría mejor?
Si escribo los tests después de implementar y no durante la planificación, ¿qué tengo que comprobar antes de escribir cada aserción para no acabar con un test que pasa sin comprobar nada?
Discusión sobre este post