Cómo dar instrucciones a un agente de IA para que sea útil

Un brief útil para un agente de IA tiene cinco partes: el objetivo en una frase, los insumos que puede usar, las restricciones que no debe cruzar, una definición de hecho con la que pueda comprobarse a sí mismo y una persona con nombre que revise el resultado antes de que nada se publique. Quita cualquiera de las cinco y obtendrás un resultado seguro de sí mismo, plausible y equivocado de una forma que nadie nota hasta más tarde. El brief se escribe en diez minutos y ahorra horas de rehacer.

Este artículo es la plantilla que usamos en Atrix para cada ejecución de nuestro propio agente y para los agentes de programación que manejan nuestros ingenieros, con un ejemplo real y los modos de fallo que hemos sufrido.

Por qué los agentes sin brief producen mal resultado

Un agente es un bucle: leer la tarea, elegir una herramienta, actuar, leer el resultado, repetir hasta que decide que ha terminado. Cada una de esas decisiones se toma contra el texto que le diste. Si el texto no dice qué aspecto tiene "hecho", el agente lo decide por su cuenta, y lo decide pronto, porque parar es más barato que seguir. Si el texto no dice qué no puede tocar, toca lo que tenga más cerca.

A mediados de 2026 el consenso entre practicantes ha llegado al mismo punto desde varias direcciones: los equipos que sacan valor de los agentes los instruyen como a un contratista y revisan el resultado como un pull request; los equipos que escriben una frase en un chat y aceptan lo que sale reciben un flujo de trabajo plausible que hay que rehacer. Las herramientas mejoraron; la necesidad de un brief no desapareció. Si acaso aumentó, porque los agentes ahora trabajan más tiempo y tocan más cosas.

Un brief no es un truco de prompts. Es el mismo documento que escribirías para una persona recién contratada que hiciera la tarea en su primer día, acortado porque el agente no necesita el contexto social.

Las cinco partes de un brief

Parte	A qué responde	Prueba de una línea
Objetivo	Qué resultado, para quién, por qué ahora	¿Un desconocido sabría cuándo se ha logrado?
Insumos	Qué puede leer y en qué puede apoyarse	¿Está cada fuente nombrada, con su ubicación?
Restricciones	Qué no debe hacer ni cambiar	¿Una violación sería evidente en la revisión?
Definición de hecho	Qué contiene y qué cumple el resultado final	¿Puede el agente comprobar cada punto por sí mismo?
Paso de revisión	Quién mira qué antes de que nada se publique	¿Hay una persona con nombre, no un rol?

Objetivo: una frase, con el resultado y no la actividad

"Escribir un documento de requisitos para recordatorios de reservas" es una actividad. "Producir los requisitos de los recordatorios de reservas para que ingeniería pueda estimarlos en la planificación del jueves" es un resultado con lector y fecha. La segunda versión le dice al agente cuánto detalle importa y quién lo juzgará.

Insumos: nombra las fuentes y di cuál manda

Enumera los documentos, incidencias, páginas y datos que el agente puede usar, dónde está cada uno y qué hacer cuando discrepen. "El PRD en /pages/booking-reminders es la base; el hilo de Slack es solo contexto; si chocan, manda el PRD y señala el conflicto". Sin esto, el agente mezcla fuentes y pierde el hilo.

Restricciones: qué no tocar, qué no asumir

Importan tres tipos. Alcance: "no propongas cambios en la sincronización del calendario". Hechos: "no inventes nombres de clientes, precios ni fechas; escribe 'desconocido'". Acciones: "solo lectura; no crees incidencias ni publiques actualizaciones". La última se corresponde directamente con los alcances que concedes al agente, y por eso brief y permisos deberían escribirse juntos.

Definición de hecho: una lista que el agente pueda ejecutar solo

No "un buen documento", sino "un documento con secciones de objetivo, historias de usuario, no-objetivos y preguntas abiertas; cada historia de usuario tiene criterios de aceptación; ninguna sección está vacía; menos de 1.200 palabras". El agente lo comprobará antes de parar, y tu revisor comprueba la misma lista, así que los dos miráis lo mismo.

Paso de revisión: una persona con nombre y un artefacto con nombre

"Moeid revisa la página de requisitos antes de que se cree ninguna incidencia". Un paso de revisión con un rol ("el PM") en vez de un nombre se salta. Un paso de revisión sin artefacto ("revisar el trabajo") se convierte en un vistazo.

Una plantilla de brief que puedes copiar

Objetivo: <resultado, lector, fecha límite>

Insumos:
- <fuente 1, ubicación, papel: base | contexto>
- <fuente 2 ...>
Si las fuentes chocan: <cuál manda; señalar el conflicto>

Restricciones:
- Alcance: <qué queda fuera>
- Hechos: no inventar <nombres, cifras, fechas>; escribir "desconocido"
- Acciones: <solo lectura | puede crear X | no puede Y>

Definición de hecho:
- [ ] <sección o salida 1 presente>
- [ ] <cada elemento tiene ...>
- [ ] <límite de longitud o formato>
- [ ] preguntas abiertas listadas, no resueltas adivinando

Revisión: <persona> revisa <artefacto> antes de <siguiente acción>.

Mantenlo por debajo de 200 palabras. Un brief largo es señal de que la tarea son dos tareas.

Ejemplo real: una ejecución Develop en Atrix

Nuestro propio agente de IA toma un brief y devuelve tres cosas en una ejecución Develop: un documento de requisitos, un documento de arquitectura y un conjunto de incidencias planificadas, todo para que una persona lo apruebe antes de que nada se convierta en trabajo real. Una ejecución consume una de las ejecuciones de IA del plan (100 al mes en Builder, 500 en Studio); chatear con el agente no. El brief que le dimos la semana pasada, ligeramente editado:

Objetivo: Requisitos, arquitectura e incidencias planificadas para
"recordatorios de reservas" para poder planificar el próximo ciclo el viernes.

Insumos:
- Página "Recordatorios de reservas: notas" (base)
- Incidencias con la etiqueta "recordatorios" en el producto Calendario (contexto)
Si las fuentes chocan, manda la página; listar el conflicto en preguntas abiertas.

Restricciones:
- Alcance: solo correo e in-app; nada de SMS este ciclo.
- Hechos: no inventar tasas de entrega ni citas de clientes.
- Acciones: es una ejecución de planificación; crear solo incidencias
  planificadas, sin cambios de estado en las existentes.

Definición de hecho:
- [ ] Requisitos con historias de usuario y criterios de aceptación
- [ ] Arquitectura que nombre los componentes tocados y los no tocados
- [ ] Incidencias planificadas lo bastante pequeñas para una persona en un
      ciclo, cada una enlazada al requisito que implementa
- [ ] Preguntas abiertas listadas

Revisión: Moeid aprueba la página de requisitos, y luego las incidencias
planificadas, antes de que entren en el backlog.

Lo que volvió fueron once incidencias planificadas, dos preguntas abiertas (una de ellas un conflicto real entre la página de notas y una incidencia antigua) y un documento de arquitectura que dejó correctamente en paz la capa de sincronización. La auditoría de requisitos comparó después las incidencias entregadas con esa base congelada e informó de la cobertura; comprueba requisitos contra el plan, no código, así que la parte de "el documento de arquitectura es honesto" seguía siendo cosa nuestra.

Dónde se quedó corto el agente: dimensionó dos incidencias demasiado grandes y resolvió una pregunta abierta adivinando pese a la restricción. Ambas cosas se detectaron en la revisión, que es para lo que sirve tener una.

Errores que producen mal resultado

Objetivo escrito como actividad. El agente hace la actividad y para.
Sin base nombrada. Mezcla tres fuentes y el resultado no coincide con ninguna.
"Usa tu criterio" con los hechos. Inventa una cifra. Di que "desconocido" es aceptable.
Definición de hecho en la cabeza del revisor. El agente no puede comprobar lo que no le dijeron.
Revisión por rol. Nadie la asume; se publica.
Un brief para dos tareas. Divídelo. Dos ejecuciones cortas ganan a una larga.
Escribir el brief después de la ejecución para justificar el resultado. El brief es el contrato; va primero.

Preguntas frecuentes

¿Qué debe incluir el brief de un agente de IA?

Cinco cosas: un objetivo de una frase con el resultado y el lector, los insumos que puede usar y cuál manda, las restricciones de alcance, hechos y acciones, una definición de hecho que pueda comprobar por sí mismo y un revisor con nombre con un artefacto con nombre. Menos de 200 palabras.

¿En qué se diferencia instruir a un agente de escribir a un chatbot?

Un chatbot responde una vez y tú lo lees. Un agente actúa muchas veces antes de que veas nada, así que el brief tiene que cubrir qué puede tocar y cuándo parar, no solo qué decir. Las restricciones y la definición de hecho importan más que la redacción.

¿Cuán detallada debe ser la definición de hecho?

Lo bastante para que el agente marque cada punto sin preguntarte, y lo bastante corta para que tu revisor la compruebe de verdad. Lo habitual son entre cinco y ocho líneas.

¿Debería el agente poder resolver las preguntas abiertas?

No. Pídele que las liste. Un agente que resuelve la ambigüedad adivinando produce un resultado que parece terminado y está equivocado en los detalles que más importan.

¿Qué es una ejecución de agente?

Una ejecución de un agente contra un brief, con un inicio, un final y un artefacto que revisar. En Atrix, una ejecución Develop devuelve requisitos, arquitectura e incidencias planificadas; consulta la entrada del glosario sobre ejecuciones de agente y la definición de agente de IA.

¿Un buen brief elimina la necesidad de revisar?

No. Un buen brief hace la revisión más rápida, porque el revisor comprueba la definición de hecho en vez de leerlo todo en frío. El paso de revisión es el que detecta las dos o tres cosas que el agente hizo mal de todos modos.

Siguiente paso

Toma la próxima tarea que ibas a encargar a un agente y escribe las cinco partes antes de lanzarla. Si la definición de hecho cuesta de escribir, la tarea aún no está lista para un agente. Para ver qué devuelve en la práctica una ejecución con brief, la página del agente de IA muestra los requisitos, la arquitectura y las incidencias planificadas que produce una ejecución Develop.

Cómo dar instrucciones a un agente de IA para que haga trabajo útil: objetivo, insumos, restricciones, definición de hecho y revisión