Un TASK_SPEC que se puede comprobar

"Haz una calculadora de cuánto debe cada uno en el restaurante". Una petición clara, hasta que uno empieza a darle vueltas. ¿Dividimos a partes iguales o cada uno paga lo suyo? ¿La propina ya está incluida en la cuenta? ¿Qué mostramos si el importe no se puede repartir por igual entre todos?

Vamos a elaborar el planteamiento junto con Claude Code: usted explica la tarea y toma las decisiones, el agente las escribe en un archivo y usted revisa lo que ha escrito. Empezaremos con una petición corta y poco a poco llegaremos a un TASK_SPEC con el que se pueda trabajar.

"Hazlo bien" no es una tarea

Imagine que quería dividir la cuenta rápidamente y el agente ha añadido un registro de usuarios y un historial de restaurantes. Para guardar los recibos necesitó un servidor. Usted contaba con abrir un solo archivo en el navegador, y ahora le toca averiguar cómo se pone en marcha todo eso y quitar lo que sobra. Cada añadido por separado parece útil, pero el resultado ya está lejos de lo que usted tenía en mente.

Cuando se trabaja con código, lo que queda sin decir puede convertirse en cambios reales en los archivos. La cadena es más o menos esta:

El esquema muestra cómo una decisión que falta acaba convirtiéndose en trabajo adicional. El agente puede preguntar, pero es mejor detectar la ambigüedad antes de que haya cambios. Para eso, ya la primera formulación puede marcar la dirección y los límites:

Todavía poco claro:
Haz una calculadora de cuánto debe cada uno en el restaurante.

Más concreto:
Necesito una sola página: introducimos el total de la cuenta y el número de personas,
y vemos el importe de cada uno. Dividimos a partes iguales.
Nada de cuentas de usuario, historial de recibos ni división por platos.

La segunda petición todavía no responde a todas las preguntas. Pero ya descarta varios productos distintos que se podrían haber construido a partir de la primera. A partir de aquí, el agente le ayudará a encontrar los huecos que quedan y a dejar por escrito sus decisiones.

La tarea en un archivo

Un TASK_SPEC es el registro de las condiciones de una tarea concreta: qué resultado se necesita, dónde termina el trabajo y cómo lo va a comprobar usted. Normalmente se guarda en un archivo Markdown, TASK_SPEC.md, junto al proyecto. Detrás de este nombre no hay ningún formato especial ni ningún comando específico. Las condiciones también se pueden pasar en un mensaje, pero un archivo es más cómodo de releer y actualizar.

No hace falta escribir el TASK_SPEC a mano. Es más cómodo elaborarlo junto con el agente y comprobar cómo ha anotado sus decisiones. Puede describir la tarea con palabras normales, responder preguntas y pedir que se corrijan las formulaciones. El agente lleva el archivo y usted comprueba su contenido.

1. usted describe lo que quiere obtener y comenta los puntos poco claros;
2. el agente propone opciones y usted elige la que le conviene;
3. el agente escribe la decisión en el TASK_SPEC y muestra el fragmento añadido o modificado;
4. usted lee ese fragmento en el archivo: el sentido se mantiene, no hay condiciones de más y no contradice lo anotado antes. Si algo no cuadra, pide que se corrija y vuelve a comprobar.

Después de cada decisión basta con revisar las líneas afectadas y las condiciones relacionadas con ellas. Antes de la implementación, relea el archivo entero: por separado, las entradas pueden parecer correctas y, juntas, exigir cosas incompatibles. Un mensaje del tipo "He actualizado la especificación" todavía no muestra qué ha quedado exactamente en el documento.

Lo que lo distingue de CLAUDE.md es su finalidad. "Todos los textos del proyecto están en español" es una regla general del proyecto. "En esta tarea añadimos el cálculo de la propina" es una condición de un trabajo concreto. Lo primero va en CLAUDE.md; lo segundo, en el TASK_SPEC.

El tamaño del documento depende de la tarea. Si en una página ya terminada hay que corregir una errata, basta con un planteamiento así:

En la página para dividir la cuenta, corrige el texto del botón:
"Calcluar" → "Calcular". No cambies nada más.
Comprueba que el nuevo texto se ve y que el botón sigue calculando.

Esto es un TASK_SPEC corto; a veces lo llaman tiny spec. Aquí casi no hay nada que discutir. En cambio, una calculadora nueva puede comportarse de varias maneras, así que dos líneas ya no bastan. Conviene anotar las decisiones que influyen en el resultado; el número de encabezados, por sí solo, no garantiza nada.

Empezamos por el resultado

Supongamos que todavía no hay proyecto. Un grupo de amigos quiere abrir una página en el navegador, introducir el importe de la cuenta y saber cuánto paga cada uno. Le pediremos al agente que cree un borrador:

Crea TASK_SPEC.md para una página que divida la cuenta.
Todavía no hay proyecto. Introducimos el importe de la cuenta y el número de personas,
y al pulsar "Calcular" vemos la parte de cada uno.
El resultado debe ser un index.html que se abra en el navegador sin instalar nada.
Anota las condiciones acordadas y marca lo desconocido como preguntas.
Muéstrame el texto que has escrito. Todavía no escribas el código de la página.

Este es un ejemplo didáctico del primer fragmento del archivo:

## CONTEXTO
Un grupo en un restaurante quiere dividir rápidamente la cuenta total.
Todavía no hay proyecto, la carpeta de trabajo está vacía.

## COMPORTAMIENTO DESEADO
El usuario introduce el importe de la cuenta y el número de personas.
Al pulsar "Calcular" ve el importe de cada participante.
Resultado del trabajo: una página index.html
que se puede abrir en el navegador sin instalar nada.

Abra TASK_SPEC.md en el editor y compare lo escrito con su petición: están los dos campos, la acción y el resultado para cada participante. Si el agente ha añadido la introducción de nombres o un registro obligatorio, eso ya son condiciones no acordadas. Pida que las quite del archivo y compruebe la corrección.

Ahora está claro quién usa la página y qué obtiene. De paso, hemos nombrado el artefacto, es decir, el resultado concreto del trabajo del agente: el archivo de la página. Para otra tarea podría ser el análisis de un error o un plan de cambios sin código. Mejor decirlo de forma explícita.

Fíjese en que todavía no hemos elegido funciones de JavaScript ni hemos dictado cómo guardar a los participantes. Esas decisiones son de la implementación. En el planteamiento importa más fijar lo que verá la persona: la entrada, la acción y el resultado.

Dónde termina la tarea

Ahora fijemos dónde termina la primera versión. Le pediremos al agente que anote los límites acordados y que muestre el bloque actualizado:

## SCOPE
Una sola página: introducir el importe y el número de personas,
dividir el total a partes iguales, mostrar la parte de cada uno.

## NON-GOALS
Sin cuentas de usuario ni historial de recibos: no hace falta guardar datos.
Sin división por platos: en la primera versión dividimos a partes iguales.
Restricción de implementación: un solo archivo HTML con los estilos y el script
dentro, sin servidor ni bibliotecas externas.
La página debe abrirse con un doble clic.

En este fragmento no solo comprobamos que las exclusiones estén ahí: la división a partes iguales debe quedar dentro del alcance de la tarea y la división por platos, fuera. Si el agente las ha confundido, corregimos el documento antes de ponernos con la página.

El scope describe el alcance del trabajo. Se puede definir a través de una pantalla y un escenario, como aquí. Las rutas exactas ayudan cuando se conocen, pero no es obligatorio empezar por una lista de archivos. Si está modificando un proyecto existente y no sabe dónde está la página que necesita, pida a Claude Code que primero la encuentre sin hacer cambios y que explique por qué ha elegido precisamente ese archivo. Después añada la ruta al planteamiento. Lo desconocido se admite; lo inventado, no.

Los non-goals son lo que se ha excluido a propósito. "Sin historial de recibos" explica el límite mejor que "no hagas nada de más". Una razón breve también le sirve a usted: dentro de una semana se verá que se pensó en guardar los datos y se descartó.

Las restricciones de implementación responden a otra pregunta: qué formas de hacerlo nos sirven. Las cuentas de usuario son una función de más, mientras que el servidor es una forma de construir la solución que aquí hemos descartado. En un documento corto, estas condiciones pueden ir en un mismo bloque, siempre que las restricciones estén marcadas de forma explícita.

Los límites tienen que permitir llegar al resultado. Si más adelante hacen falta cuentas de usuario compartidas con historial en distintos dispositivos, habrá que revisar el requisito de "un único archivo HTML local". No se puede pedir una capacidad nueva y a la vez mantener una prohibición que la hace imposible.

El centavo que se olvidó

De momento todo parece bastante definido. Pongamos a prueba el planteamiento antes de escribir código: un grupo de tres personas, una cuenta de 1000. ¿Qué importe le mostramos a cada uno?

333,33 + 333,33 + 333,33 = 999,99

Falta un centavo. Se le puede sumar al primer participante, al último o dejar que el usuario elija. La frase "dividimos a partes iguales" no lo resuelve. Y esto ya es una pregunta para usted, no una cuestión de saber JavaScript.

Para nuestra página elegimos este criterio: las partes se diferencian como mucho en un centavo; el resto se reparte de centavo en centavo entre los primeros participantes de la lista. Así, 1000 entre tres da 333,34; 333,33; 333,33. Y con 1000,01 sobran dos centavos: 333,34; 333,34; 333,33. Todo el dinero queda repartido y la suma de las partes coincide con la cuenta.

Ahora le pedimos al agente que pase la decisión elegida al documento:

Añade la regla de redondeo al comportamiento deseado en TASK_SPEC.md.
Muéstrame las líneas modificadas. Todavía no cambies el código.

Comprobamos que en el archivo ha aparecido una entrada como esta:

La suma de las partes es exactamente igual al total.
Las partes se diferencian como mucho en 0,01.
Los centavos sobrantes los reciben los primeros participantes, uno cada uno;
la página incluye una explicación de esta regla.

Leemos con especial atención las palabras "los primeros participantes, uno cada uno". Si el agente ha escrito "todo el resto para el primero", ha cambiado la decisión: con dos centavos sobrantes, el primero pagaría 0,02 más que los demás. Pedimos que corrija esa línea y volvemos a mirar el archivo. Lo que comprobamos es el sentido; no hace falta que la redacción coincida palabra por palabra.

Para eso sirve meter números en el planteamiento. Hemos encontrado la decisión que faltaba antes de que el agente eligiera su propia opción y escribiera código a partir de ella. Por ahora solo hemos corregido unas pocas líneas.

Deje que Claude haga las preguntas

No todos los huecos los va a ver usted solo. Pásele el borrador al agente y pídale ayuda precisamente con el planteamiento:

Lee @TASK_SPEC.md. Ayúdame a encontrar las condiciones que faltan.
Hazme las preguntas de una en una y propón una respuesta para cada una.
No des tu propuesta por acordada hasta que yo responda.
Después de cada decisión acordada, actualiza TASK_SPEC.md
y muéstrame el fragmento modificado para que pueda revisarlo.
Todavía no escribas código.

A continuación, un ejemplo de una conversación así. En su sesión las preguntas pueden ser otras; aquí lo importante es seguir cómo las respuestas van cambiando el documento.

Claude: "¿La propina está incluida en el importe de la cuenta o se añade aparte? Propongo un campo aparte con el porcentaje, 0 por defecto".
Usted: "Aparte. El porcentaje se calcula sobre el importe de la cuenta, la propina se suma encima y se divide todo junto. Muestra en la página el importe de la propina y el total".

Claude: "Si la propina sale con una fracción de centavo, ¿cómo redondeo? Propongo al centavo más cercano, y el medio centavo exacto hacia arriba".
Usted: "Sí. Primero redondeamos el importe de la propina y luego lo sumamos a la cuenta. Después dividimos el total según nuestra regla".

Claude: "¿Qué valores aceptamos? Propongo un importe positivo con punto o coma, un número entero de personas a partir de uno y un porcentaje entero no negativo. Si hay un error, mostrar una indicación junto al campo".
Usted: "De acuerdo. En el importe, hasta dos cifras después del separador, sin espacios entre los miles. Si un campo está vacío o el valor no es válido, ocultamos el resultado, aunque ya se hubiera calculado antes".

No solo hemos aclarado la propina. Ahora están definidos la entrada válida, el orden del redondeo y el comportamiento ante un error. Una vez anotadas las respuestas, cotejamos el fragmento actualizado del archivo:

Propina: campo aparte con un porcentaje entero desde 0, valor inicial 0.
El importe de la propina se calcula sobre la cuenta y se redondea al centavo más cercano;
el medio centavo exacto se redondea hacia arriba.
A la cuenta se le suma la propina redondeada y después se divide el total.
Mostramos el importe de la propina, el total y la parte de cada uno.
Si un valor está vacío o no es válido, el resultado se oculta
y el campo correspondiente muestra una indicación.

Comprobamos el orden: primero se redondea la propina, luego se suma a la cuenta y luego se divide el total. Las mismas palabras en otro orden darían otro requisito. También le pedimos al agente que actualice el scope: a la primera versión se han añadido el campo de la propina y el cálculo del total. Miramos que de verdad haya cambiado los dos bloques y no solo lo haya confirmado en el chat.

El resultado y cómo comprobarlo

"La suma de las partes es igual al total" es un requisito sobre el resultado. "Introducir 1000, tres personas y 0% de propina; pulsar el botón; ver 333,34, 333,33 y 333,33" es una comprobación. Define una acción y la observación esperada.

Pidamos al agente que añada ahora al archivo unas cuantas comprobaciones de este tipo, antes de la implementación. Los números esperados los verificaremos nosotros. Si no, es fácil darse por satisfecho con lo que haya salido y, sin darse cuenta, ajustar las expectativas a la página ya hecha.

La fila con 10,05 comprueba el orden de las operaciones: el 10% da 1,005, que tras redondear queda en 1,01. Si se redondea en otro punto, el total puede salir distinto. Para comprobar el formato, repítala con punto: 10.05 debe dar el mismo resultado. Aparte, pruebe un importe negativo, un número de personas con decimales, un porcentaje negativo o con decimales y el campo de la propina vacío: no debe haber cálculo.

Cada condición importante tiene su propia observación. "La página se ha abierto" todavía no demuestra que los importes sean correctos, igual que una dirección de enlace correcta no demuestra que se haya cargado la página que se necesitaba. Compruebe el comportamiento que era el motivo de la tarea.

Montamos el TASK_SPEC

El agente ha ido reuniendo las decisiones en el archivo a medida que avanzaba la conversación. Ahora lo releemos entero: ¿están recogidas las respuestas?, ¿coinciden las comprobaciones con los requisitos?, ¿no quedan condiciones antiguas? Así queda el documento final de nuestro ejemplo. Tiene seis pilares: contexto, comportamiento deseado, scope, non-goals, plan de verificación e inicio seguro. Los nombres ayudan a encontrar rápido la parte que se busca, y el contenido ha salido del análisis de la tarea.

# TASK_SPEC.md

## CONTEXTO
Un grupo quiere dividir la cuenta de un restaurante.
Todavía no hay proyecto nuevo; la carpeta de trabajo está vacía, salvo TASK_SPEC.md.

## COMPORTAMIENTO DESEADO
Resultado del trabajo: un index.html que se abre con doble clic,
y una breve descripción de la comprobación.
En la página hay tres campos y un botón "Calcular":
- importe de la cuenta mayor que 0, hasta dos decimales;
  el separador es punto o coma, sin separadores de miles;
- número de personas: entero, desde 1;
- porcentaje de propina: entero, desde 0, valor inicial 0.
La propina se calcula sobre la cuenta y se redondea al centavo más cercano;
el medio centavo exacto se redondea hacia arriba.
A la cuenta se le suma la propina redondeada y después se divide el total.
Se ven la propina, el total y las partes numeradas de los participantes.
La suma de las partes es igual al total, la diferencia entre partes no pasa de 0,01.
El resto se reparte de centavo en centavo entre los primeros participantes;
la página incluye una explicación de esta regla.
Valor vacío o no válido: el resultado se oculta
y el campo mal rellenado muestra una indicación.

## SCOPE
Una sola página: tres campos, cálculo, indicaciones y los importes mostrados.
Dividimos el total a partes iguales con el reparto del resto descrito.

## NON-GOALS
No hacen falta cuentas de usuario ni historial de recibos: no guardamos datos.
No dividimos por platos: eso es otra versión de la calculadora.
Restricción: estilos y script dentro de index.html,
sin servidor ni bibliotecas externas, para abrir el archivo en local.

## PLAN DE VERIFICACIÓN
Abrir index.html con doble clic. Pulsar "Calcular":
- 1000 / 3 personas / 0% → 333,34; 333,33; 333,33;
- 1000,01 / 3 / 0% → 333,34; 333,34; 333,33;
- 1000 / 3 / 10% → propina 100,00, total 1100,00,
  partes 366,67; 366,67; 366,66;
- 10,05 / 3 / 10% → propina 1,01, total 11,06,
  partes 3,69; 3,69; 3,68; al introducir 10.05 el resultado es el mismo;
- 1000 / 1 / 0% → una sola parte de 1000,00.
En cada caso, sumar las partes y cotejarlas con el total.
Probar cero y decimales en el número de personas, importe negativo,
porcentaje negativo y con decimales, más de dos decimales
en el importe y, uno por uno, cada campo vacío:
indicación junto al campo, resultado oculto, también después de un cálculo.
Comprobar la numeración de las partes y la explicación del reparto de centavos.

## INICIO SEGURO
Leer el planteamiento y mirar el contenido de la carpeta de trabajo.
Si ya hay archivos del proyecto, detenerse y aclarar la tarea;
no sobrescribir ni borrar los archivos existentes.
Primero preguntas y un plan sin código, después esperar la aprobación.
Si la implementación requiere cambios fuera del scope,
aclarar el planteamiento antes de hacerlos.

El documento ha crecido con las decisiones que de verdad hacían falta. No contiene una receta paso a paso para escribir el JavaScript, pero se ve qué hacer con la propina y cómo comprobar los centavos. En su tarea puede haber menos detalles.

Cuando prepare su propio planteamiento, le será útil repasar esta pequeña guía rápida:

Si las condiciones cambian

Ahora, una pequeña prueba para usted. El usuario ha visto el planteamiento y dice: "El porcentaje es incómodo. Quiero introducir la propina como importe, por ejemplo 100". ¿Qué partes del TASK_SPEC habrá que actualizar? Intente nombrarlas antes de leer el análisis.

En el comportamiento deseado, el campo del porcentaje se sustituye por el importe de la propina: no negativo, con punto o coma y como máximo dos decimales. El valor inicial sigue siendo 0. La fórmula del porcentaje y el redondeo de la propina calculada se eliminan: el importe introducido simplemente se suma a la cuenta. En el scope cambia el cálculo; en el plan de verificación, los datos de entrada y los casos de entrada no válida. La división del total y los non-goals se quedan como estaban.

La comprobación "cuenta de 1000, propina de 100, tres participantes" dará los ya conocidos 366,67; 366,67; 366,66. Pero con estos números por sí solos no se distingue la versión nueva de la antigua con un 10% de propina. Añada otra cuenta: 500 más 100 fijos, dos participantes. Deben salir 300 por cabeza; el 10% de antes daría 275 a cada uno. Esa sí es una comprobación que detecta el cambio de regla.

Encárguele al agente que actualice el comportamiento deseado, el scope y las comprobaciones, y que después muestre todos los fragmentos modificados. Abra el archivo y asegúrese de que la antigua fórmula del porcentaje se ha eliminado y de que las nuevas comprobaciones corresponden a la introducción de un importe. No deje a la vez la fórmula antigua y una nota nueva del tipo "ahora como importe": el planteamiento debe dar una sola respuesta. En el ejemplo principal de arriba hemos mantenido la versión original con porcentaje; aquí hemos analizado un cambio aparte sobre ella.

Cómo encaja todo esto con Claude Code

Cuando haya revisado los cambios uno a uno, relea todo el TASK_SPEC antes de lanzar la implementación. Asegúrese de que el objetivo, los límites y las comprobaciones describen la misma tarea. Después, pásele el archivo al agente de forma explícita:

Lee @TASK_SPEC.md. Primero comprueba si hay contradicciones
o condiciones que todavía haya que aclarar.
Muéstrame un plan breve y la lista de archivos que vas a crear o modificar.
No cambies el código hasta que el plan esté aprobado.

Ahora hay algo que comprobar incluso antes de la implementación. Si en el plan aparece un servidor para guardar los recibos, devuélvalo para que lo rehaga: el historial está excluido y la página tiene que abrirse en local. Si el plan le parece bien, autorice la implementación. Luego abra el archivo resultante y recorra los escenarios anotados, incluida la entrada no válida después de un cálculo correcto.

Los non-goals siguen siendo condiciones escritas en texto; técnicamente no bloquean ningún cambio. Por eso importan tanto la revisión del plan como la comprobación del resultado. El mensaje "listo" del agente ayuda a entender qué ha hecho, pero no sustituye a sus propios números de control.

Si guarda el TASK_SPEC en el proyecto una vez terminado, marque la tarea como cerrada. Y mientras el trabajo sigue en marcha, mantenga al día las decisiones del archivo. Encárguele al agente las formulaciones y la escritura, y compruebe las decisiones en el propio documento: el fragmento modificado después de cada conversación, el archivo entero antes de la implementación.