Mis agentes de Codex también se despistan: así los organizo con AGENTS.md

En el vídeo de ChatGPT Voice hay un momento en el que tengo que parar y redirigir una tarea al especialista. Está alrededor del minuto 16:34, por si quieres ir directamente al fallo.

Tengo proyectos separados, instrucciones y un coordinador al que le voy pidiendo cosas por voz. Aun así, toca corregir el recorrido. Y después hay que volver a mirar qué se ha hecho.

Tras publicar el vídeo me preguntaron si podía compartir mis AGENTS.md. He preparado una versión reducida para que puedas adaptar esa organización a tu trabajo, con un coordinador, dos especialistas y una prueba sin conectar ninguna cuenta. Mi configuración completa incluye detalles privados e integraciones que aquí he dejado fuera.

Ver las plantillas en GitHub

Puedes pasarle ese repositorio a tu agente y pedirle que lea las instrucciones y proponga cómo adaptarlas a tus proyectos. El README incluye un prompt para hacerlo sin sustituir tus archivos ni activar cambios antes de que los apruebes.

Cuando le pido algo a Content, quiero encontrarlo en Content

Trabajo con cinco áreas: Development, Content, Operations, Communication y Education. Cada una tiene su proyecto y sus instrucciones. Por ejemplo, Content se ocupa de los borradores y la publicación de contenido; Education, del trabajo relacionado con alumnos y formación.

Desde la conversación que coordina el trabajo puedo encargar algo a un especialista y volver a consultar el resultado sin tener que pasar continuamente de una conversación a otra. En el vídeo lo hago por voz.

En el minuto 4:52 del vídeo enseño cómo lo tengo montado. Para seguirlo, basta con separar tres cosas:

• Proyecto: el área donde están los archivos y las instrucciones de ese trabajo.
• Tarea: un encargo concreto dentro de ese proyecto.
• Coordinador: la conversación desde la que reparto encargos y reviso qué ha ocurrido con ellos.

Con esta organización, pedirle algo a Content significa abrir una tarea en su proyecto. Quiero poder encontrar después ese encargo, sus materiales y su resultado. La plantilla lo pide expresamente para evitar que el coordinador lo sustituya por un subagente en su propia carpeta.

Para probarlo, te propongo empezar con Coordinación y Content. Copiar mis cinco áreas de golpe te dejaría configurando cosas que quizá no necesitas.

Qué va en cada AGENTS.md

En las instrucciones comunes tengo acuerdos que se repiten: conservar el trabajo existente, avanzar sin preguntarme cosas que se pueden comprobar y distinguir un borrador de una publicación.

En las de cada proyecto explico qué le corresponde hacer, qué fuentes debe utilizar y cómo debe entregar el resultado. El kit separa esas piezas:

Archivo	Qué contiene
global.fragment.md	Acuerdos comunes para revisar e incorporar, si te encajan.
Coordinator.AGENTS.md.template	Destinos, delegación y seguimiento.
Content.AGENTS.md.template	Un especialista que redacta sin publicar.
Development.AGENTS.md.template	Otro ejemplo, orientado a repositorios y pruebas.

Los archivos están guardados como plantillas para que descargarlos no active nuevas instrucciones. En el README tienes dónde colocarlos y cómo comprobar que se han cargado. Si ya tienes un AGENTS.md, conserva sus reglas y revisa los posibles conflictos antes de incorporar otras.

También conviene separar organización y acceso: asociar una carpeta a un proyecto no equivale a aislarla mediante permisos. La documentación de proyectos explica esa diferencia.

Que espere antes de decirme que ha terminado

Es fácil acabar con varios encargos en marcha y una respuesta del coordinador que suena a «todo listo», cuando todavía faltan cosas. Por eso tengo esta instrucción:

Espera el resultado del especialista y lee su respuesta y la evidencia
disponible antes de dar el encargo por terminado.

No presentes una tarea iniciada, un mensaje enviado o una operación
en cola como resultado verificado.

Quiero que me diga qué se ha hecho de verdad y qué sigue pendiente.

En desarrollo esto obliga a distinguir un cambio local, una PR y un despliegue. En contenido, un texto preparado y un texto publicado. Las instrucciones también dejan claro que aprobar el borrador no da permiso para publicarlo.

Una prueba antes de darle trabajo real

El paquete incluye un encargo ficticio: redactar un anuncio para una actividad de una biblioteca. Tiene fecha, horario y límites. Content debe guardar entre 80 y 120 palabras en un archivo; el coordinador debe esperar y comprobarlo.

El texto completo está en PRUEBA.md. La parte de coordinación dice:

Crea una nueva tarea en el proyecto Content [...]

Espera la entrega de Content y comprueba el archivo: extensión y ruta,
80–120 palabras, fecha y horario correctos, aviso sobre las fotografías
de prueba, y ausencia de enlace inventado.

No lo des por terminado solo porque hayas enviado el encargo.

Prueba primero por texto. Comprueba que aparece una tarea real en Content y que el archivo se guarda en la carpeta correcta. Si el coordinador dice que lo ha enviado pero no puedes encontrar el encargo, todavía no tienes ese paso funcionando.

Si faltan las herramientas para trabajar entre proyectos, el ejemplo debe decirlo. Puedes pasar el encargo manualmente, pero conviene conservar esa diferencia al evaluar el resultado.

La plantilla pública se ha revisado contra la configuración de origen y la documentación; no se ha probado de extremo a extremo en una cuenta limpia. Por eso incluye esta comprobación pequeña y no empieza pidiéndote acceso al correo o a un repositorio de producción.

Las tareas que esperan por mí

Uso dos secciones en la barra lateral: Human review y Blocked.

La primera contiene entregas que necesitan que yo revise o decida algo. La segunda, trabajos que realmente no pueden continuar por una dependencia. También tengo indicado que saquen una tarea de esas secciones cuando se reanuda.

La plantilla del coordinador incluye esta organización como opción. Solo se aplica si has creado las secciones y tu app dispone de herramientas para gestionarlas. Si no, puede informar del estado en texto. No necesitas montar esa parte para hacer la primera prueba.

¿Y Voice?

En la sesión que grabé lo utilizo para encargar y revisar trabajo. Además del desvío del principio, aparecen problemas con herramientas y permisos. Los AGENTS.md no evitan todos esos fallos.

Puedes probar los mismos encargos por voz si la función está disponible en tu app. La documentación actual describe cómo consultar trabajo y pasar instrucciones entre conversaciones; revisa allí la disponibilidad, que puede cambiar. Documentación de Voice.

Esta guía se limita al escritorio. No configura la continuidad entre Voice en el móvil y las carpetas locales del Mac, ni incluye las skills e integraciones que uso en mi trabajo. Eso requiere comprobar otras piezas aparte.

Empieza con el encargo ficticio. Si consigues localizar la tarea, leer el archivo y recibir una revisión que corresponde con lo que ha ocurrido, ya tendrás algo concreto sobre lo que adaptar tu configuración.