Redacta las instrucciones de una tarea para un agente

Describe un cambio que se pueda evaluar

«Añade una exportación de clientes» deja varias decisiones abiertas. ¿Quién puede exportar registros? ¿Qué registros y campos se incluyen? ¿Qué ocurre si falla una solicitud? Un agente puede cubrir estos vacíos con decisiones plausibles. Aun así, pueden ser incorrectas para el negocio.

Empieza por el usuario y el problema. Después, describe el comportamiento necesario. Incluye las pruebas que permitirán determinar si el resultado es aceptable.

Las instrucciones deben reducir la incertidumbre sin fijar todas las decisiones internas de diseño. Especifica el límite de datos requerido. Deja que la implementación use los patrones existentes del repositorio, salvo que haya un motivo para cambiarlos.

Usa un ejemplo concreto

Las siguientes instrucciones corresponden a una aplicación ficticia de soporte. Son un ejemplo educativo, no una especificación completa para producción.

Resultado: Un responsable de soporte puede descargar una lista de clientes.
Actor: Un responsable de la organización actual.
Datos: Solo los clientes activos de esa organización.
Campos: Identificador del cliente, nombre de la empresa y estado de la cuenta.
Formato: CSV UTF-8 con una fila de cabecera.
Solicitud denegada: Devolver el error de autorización existente.
Resultado vacío: Devolver un CSV válido que solo contenga la cabecera.
Alcance: Usar la ruta de exportación y el patrón de auditoría existentes.
Exclusiones: No añadir roles ni dependencias, ni realizar despliegues.
Pruebas: Solicitudes permitidas, denegadas, vacías y entre organizaciones.

Estas instrucciones identifican un comportamiento útil y sus límites. También revelan nuevas preguntas. ¿Debe limitarse el tamaño de la exportación? ¿Puede un campo contener una fórmula de hoja de cálculo? ¿Quién puede acceder al registro de auditoría? Resuelve las preguntas con consecuencias importantes antes de implementar. No trates el ejemplo como una lista universal de comprobaciones.

Separa los requisitos de los supuestos

Un requisito indica un comportamiento que el cambio debe cumplir. Un supuesto es un dato que todavía no has verificado. Mantenlos separados.

Por ejemplo, «usa el patrón de auditoría existente» supone que existe un patrón adecuado. Pide al agente que lo encuentre. Si el repositorio no tiene ninguno, debe informar de esa dependencia ausente antes de inventar un sistema de auditoría nuevo.

Una restricción también puede entrar en conflicto con el resultado. La ruta existente podría devolver todas las organizaciones por diseño. El agente debe mostrar el conflicto y proponer una corrección limitada. No debe eliminar en silencio el límite de datos ni ampliar la tarea hasta reescribir la arquitectura.

Incluye las pruebas en la finalización

Pide un resumen de entrega que explique el comportamiento final, los cambios de alcance y las comprobaciones realizadas. Exige comandos y resultados exactos cuando sean relevantes. Distingue una comprobación superada de otra que no pudo ejecutarse.

La pull request debe conservar el motivo del cambio. Quien mantenga el sistema más adelante puede ver el código sin la conversación original. Incluye contexto suficiente para explicar por qué la exportación excluye determinados campos y cómo se aplica el control de acceso.

La guía de Google sobre descripciones de cambios sirve de referencia para este registro. La descripción debe explicar el cambio y su finalidad. Tras los cambios de revisión, mantén el registro alineado con la implementación final.

Ajusta el detalle a la tarea

Una corrección pequeña de texto puede tener instrucciones breves. Una exportación de datos necesita más detalle, porque sus fallos pueden exponer información. Un nuevo flujo de pagos exige aún más análisis y revisión.

No midas la calidad de las instrucciones por su longitud. Pregunta si una persona competente podría distinguir un resultado correcto de uno incorrecto al revisarlo. Si dos implementaciones razonables discreparían sobre un comportamiento importante, acláralo primero.