Especificar tareas para agentes

En el módulo 16 viste qué es un agente: un modelo con herramientas y un ciclo que decide el siguiente paso solo. Esa autonomía tiene un precio. Cuando un agente trabaja veinte minutos sin preguntarte, cada hueco de tu instrucción lo llena él, y lo descubres al final, con el trabajo hecho sobre una suposición.

Este módulo es sobre cerrar esos huecos antes de que el agente arranque: una especificación que una persona revisa, criterios de aceptación que se pueden comprobar, pruebas que funcionan como contrato y un plan de tareas pequeñas. Es la habilidad de Descripción del marco 4D, llevada de un prompt a un sistema.

¿Por qué un agente falla con una tarea vaga?

Por la razón que viste en el módulo 1: el modelo produce el texto más plausible, y cuando le falta un dato no se detiene, completa. En un chat eso se llama alucinación y la atrapas al leer. En un agente se llama "decisión de diseño que nadie tomó": no sabía si el formulario debía aceptar extranjeros sin cédula, asumió que no, y construyó media hora sobre esa suposición. El código funciona. Solo que resuelve otro problema.

La guía de buenas prácticas de Claude Code lo dice sin rodeos: Claude puede inferir la intención, pero no lee la mente; entre más precisa la instrucción, menos correcciones. Un prompt vago sirve cuando exploras y corregir es barato, no cuando el agente va a tocar archivos reales durante media hora. El módulo 4 te dio la anatomía de un prompt. Una especificación es esa misma anatomía para una tarea que dura horas, toca varios archivos y la lee alguien más antes de aprobarla. "Que el precio venga de Stays" deja abiertas cuatro preguntas (qué unidades, qué regla, qué pasa si Stays no responde, qué se elimina del sistema viejo), y cada una es una moneda al aire. La especificación existe para que esas monedas las lances tú, por escrito, antes.

¿Qué tiene que decir una especificación?

Una página basta para la mayoría de las tareas de un negocio, siempre que tenga todas las secciones, aunque alguna diga "no aplica". Son las que usamos en 77Rentals, y coinciden con lo que la guía de Claude Code llama una spec autocontenida: nombra archivos e interfaces, dice qué queda fuera de alcance y termina con una verificación de punta a punta.

1. 1Objetivo. Qué podrá hacer alguien cuando esto esté listo, en dos o tres frases, desde el punto de vista del usuario.
2. 2Contexto. Qué existe hoy, por qué se cambia y qué archivos debe leer el agente antes de empezar: el documento de contexto del módulo 2, el CLAUDE.md del módulo 12.
3. 3Alcance y no-objetivos. Qué entra y, con el mismo cuidado, qué no: "no hay pago en línea", "las páginas sin calendario no cambian". Es la sección que más trabajo ahorra.
4. 4Decisiones ya tomadas. Las que son tuyas y el agente no debe reabrir: qué enfoque se escogió, cuáles se descartaron y por qué. Si no están escritas, el agente las vuelve a decidir.
5. 5Restricciones. Qué no tocar, qué estilo seguir, qué datos nunca salen del servidor, qué debe seguir funcionando igual.
6. 6Interfaces y forma de los datos, en palabras. Qué entra y qué sale de cada pieza: "el navegador manda solo la clave de la unidad; la respuesta trae las noches ocupadas como rangos y, por cada noche libre, la estadía mínima y la tarifa".
7. 7Riesgos y casos límite. Qué puede salir mal y qué ve el usuario cuando pasa. Una tabla de dos columnas vale más que un párrafo.
8. 8Qué significa "terminado". Los criterios de aceptación y las pruebas, que vienen en las dos secciones siguientes.

Dos reglas de proceso. Primera: la especificación la aprueba una persona antes de construir. Es el humano en el ciclo del módulo 9 en el punto más barato: corregir una frase cuesta un minuto; una función ya construida, una tarde. Segunda: el agente puede ayudarte a escribirla. Para funciones grandes, la guía de Claude Code recomienda pedirle que te entreviste sobre detalles técnicos, casos límite y compromisos, que escriba la spec en un archivo y que la implementación arranque en una sesión nueva, con el contexto limpio. El modo plan del módulo 13 es la versión corta; la spec es la que sobrevive a la sesión.

Quiero construir esto: [DESCRIPCIÓN DE LA IDEA EN DOS O TRES FRASES].

Contexto: [QUÉ EXISTE HOY, QUIÉN LO USA, QUÉ ARCHIVOS O DOCUMENTOS DEBERÍAS LEER PRIMERO].

Antes de escribir nada, entrevístame. Pregúntame una cosa a la vez sobre alcance, casos límite, qué no debe cambiar, qué datos entran y salen, qué pasa cuando algo falla y qué decisiones ya tomé. No me preguntes lo obvio; pregunta lo difícil que probablemente no pensé. Sigue hasta que no queden huecos importantes.

Después escribe una especificación de máximo dos páginas con estas secciones, todas, aunque alguna diga "no aplica": objetivo, contexto, alcance y no-objetivos, decisiones ya tomadas, restricciones, interfaces y forma de los datos (en palabras, sin código), riesgos y casos límite (tabla: situación, qué ve el usuario), y qué significa "terminado".

Marca al final, en una lista aparte titulada "Decisiones abiertas", todo lo que asumiste porque no te lo dije. No construyas nada todavía.

¿Cómo se escriben criterios de aceptación que sirvan?

Un criterio de aceptación es una frase sobre el resultado que cualquiera puede comprobar con un sí o un no, sin haber visto el código. Le dice al agente cuándo parar y a ti qué mirar. La guía de Anthropic sobre criterios de éxito pide que sean específicos, medibles, alcanzables y relevantes: en vez de "buen desempeño", "clasificación precisa", con una cifra sobre un conjunto de casos definido. La prueba más simple: si dos personas leen el criterio y el resultado, ¿llegan a la misma respuesta? Los buenos nombran un caso concreto, un dato observable y un número cuando hay número, y cubren el camino feo (qué pasa cuando falla), no solo el feliz.

• Malo: "El extractor de facturas funciona bien." Bueno: "Con las 20 facturas del set de pruebas, los campos fecha, NIT, subtotal, IVA y total coinciden con los valores verificados en al menos 19; en la que falle, el campo queda vacío, nunca inventado."
• Malo: "El formulario valida los datos." Bueno: "Rechaza un correo sin arroba y una cédula con letras, muestra el error en español debajo del campo y no envía nada hasta que los dos sean válidos."
• Malo: "La respuesta al huésped es amable." Bueno: "Usa el nombre del huésped, responde lo que preguntó, no promete nada que no esté en la biblia del apartamento y cabe en 120 palabras."
• Malo: "El sistema es rápido." Bueno: "Con la caché caliente, la página muestra el calendario sin esperar una llamada externa; sin caché, el usuario ve el precio estático mientras carga."

¿Por qué las pruebas son el contrato?

Un criterio que se puede convertir en una prueba automatizada es un criterio que el agente comprueba solo. La guía de Claude Code lo pone como primera recomendación: dale a Claude una comprobación que pueda ejecutar (pruebas, un build que pasa o falla, un script que compara la salida contra un archivo esperado, una captura para comparar). Sin eso, "parece terminado" es la única señal que tiene, y tú te conviertes en el ciclo de verificación. Con una comprobación que devuelve pasa o falla, el ciclo agéntico se cierra solo: el agente trabaja, corre la prueba, lee el resultado y corrige hasta que pasa.

De ahí el orden que recomendamos: primero las pruebas, después la construcción. Si el agente escribe el código y luego las pruebas, las pruebas describen lo que construyó. Si existen antes, describen lo que tú querías, y el código tiene que alcanzarlas. La misma guía sugiere incluso dos sesiones: una escribe las pruebas y otra el código que las haga pasar, para que quien construye no sea quien califica.

1. 1Escribe o describe las comprobaciones. Para código, pruebas que fallan hoy. Para un flujo con IA, el set de pruebas del módulo 9: casos reales con la respuesta conocida y una rúbrica.
2. 2Confirma que fallan antes de construir. Una prueba que pasa antes de que exista la función no prueba nada.
3. 3Deja que el agente construya hasta que pasen. En un solo prompt ("implementa y corre las pruebas hasta que pasen") o como condición de parada, con los hooks del módulo 14.
4. 4Pide evidencia, no afirmaciones: la salida de las pruebas, el comando que corrió y lo que devolvió.
5. 5Revisa las pruebas con más cuidado que el código. Son el contrato; si están flojas, el contrato está flojo.

Aquí está la especificación aprobada: [PEGA LA SPEC O INDICA EL ARCHIVO].

Primero, escribe los criterios de aceptación: una lista de frases que cualquiera pueda comprobar con un sí o un no sin ver el código. Cada criterio nombra un caso concreto, un dato observable y un número cuando lo haya. Incluye al menos un criterio por cada fila de la tabla de riesgos (qué pasa cuando falla), no solo el camino feliz. Si un criterio no se puede comprobar, reescríbelo hasta que se pueda o márcalo como "no verificable" y dime por qué.

Después, para cada criterio, di cómo se verifica: prueba automatizada (describe la entrada y la salida esperada), comprobación manual (los pasos exactos) o revisión de una persona (qué debe mirar). Para las automatizadas, escribe las pruebas en [LENGUAJE O HERRAMIENTA DE PRUEBAS DEL PROYECTO] usando [UN ARCHIVO DE EJEMPLO REAL O UNA MUESTRA GRABADA] como dato de entrada, y confirma que hoy fallan.

No implementes nada. Termina con la lista de criterios que quedaron sin prueba automática y por qué.

¿Cómo paso de la especificación a un plan de tareas?

Una spec aprobada todavía es demasiado grande para un solo turno. El paso siguiente es un plan: tareas en orden, cada una lo bastante pequeña para que el agente la termine en una sesión y tú la verifiques sin leer todo lo demás. Lo que hace una tarea "del tamaño correcto" no es el número de líneas, sino que tenga su propia comprobación y su propio commit.

1. 1Cada tarea dice qué archivos toca y qué recibe y entrega, en palabras.
2. 2Cada tarea tiene su comprobación: la prueba que debe pasar, el comando que debe correr sin errores o los pasos manuales exactos.
3. 3Las tareas van en orden de dependencia: primero la pieza pura que se prueba sola (una transformación de datos, un cálculo), después lo que la usa, al final lo que se elimina.
4. 4Cada tarea termina en un commit. Si algo sale mal en la tarea 4, vuelves a la 3.
5. 5El plan lista los riesgos de revisión: los tres a cinco errores que más te preocupan y qué prueba los cubre. Si un riesgo no tiene prueba, falta una tarea.
6. 6Lo que no es código va aparte: qué hace una persona antes o después (agregar una clave, aprobar algo, apagar lo viejo).

El agente puede escribir el plan a partir de la spec, porque las decisiones difíciles ya están tomadas. Tú lo revisas como un cronograma de obra: ¿está todo lo de la spec?, ¿hay algo que no estaba?, ¿cada tarea se verifica sola? Y guarda spec y plan en el repositorio: en seis meses, el documento que explica por qué se decidió así vale más que el código.

Y una idea que ya viste sin nombre: el brief es la spec de un agente que escribe. Las instrucciones de los redactores del blog del módulo 14, y el brief con el que se escribió este curso, tienen las mismas secciones: objetivo, contexto (qué leer primero), alcance, decisiones tomadas (la voz, qué hechos de 77Rentals se pueden usar), restricciones (sin guiones largos, sin cifras inventadas), formato de salida y criterios de terminado (bloques obligatorios, pruebas que deben pasar).

Lee la especificación en [ARCHIVO O TEXTO] y los criterios de aceptación en [ARCHIVO O TEXTO]. Explora el proyecto lo necesario para saber qué archivos existen y cómo están organizados.

Escribe un plan de implementación con estas partes:
1. Objetivo y arquitectura en cinco líneas, con enlace a la spec.
2. Restricciones globales: lo que ninguna tarea puede violar.
3. Riesgos de revisión: los tres a cinco errores más probables y qué tarea y qué prueba cubre cada uno.
4. Tareas en orden de dependencia. Cada tarea tiene: archivos que crea o modifica, qué recibe y qué entrega (en palabras), pasos numerados que empiezan por escribir o correr la prueba que debe fallar y terminan con la prueba pasando y un commit con su mensaje.
5. Lo que debe hacer una persona antes o después, fuera del código.

Reglas: cada tarea debe poder terminarse en una sesión y verificarse sola; si una tarea no tiene comprobación, divídela o agrégale una. No implementes nada: entrega el plan y espera mi aprobación.

¿Qué sigue?

Con una spec, criterios y pruebas, ya puedes encargar una tarea a un agente. El paso siguiente es encargar varias a la vez: el módulo 18, "Orquestación: varios agentes a la vez", muestra cómo se reparte un plan entre subagentes en paralelo, cómo se revisan entre sí y cuándo es complejidad de más. La spec que escribiste hoy es lo que cada uno de ellos va a necesitar.