Intensivo Gratis 21–22.11Intensivo gratuito de 2 días en Vibecoding (21–22 nov, 16:00 MSK) · Cohorte 3 inicia 23.11Registrarse gratis →Cohorte 3 (23.11)
LanzamientoAnálisis · En radarHabr AI→ original

AGENTS.md ayudó a Codex a respetar las reglas del proyecto: 0 infracciones de 13 frente a 5 de 13

Una nueva sesión de un agente de IA no recuerda los acuerdos de ayer: coloca SQL directamente en el servicio, crea una columna extra cancelled_at y se olvida de registrar la acción en el registro de auditoría. El Tech Lead Serguéi Proshchaev ejecutó 18 sesiones de Codex sobre un pequeño servicio en Python. Sin reglas, el agente incumplió 5 de 13 decisiones del proyecto; con el archivo AGENTS.md o con un skill, ninguna de las 13. Por eso, en el archivo solo conviene escribir lo que el agente no haría bien por su cuenta.

Procesado por IA desde Habr AI; editado por Hamidun News
AGENTS.md ayudó a Codex a respetar las reglas del proyecto: 0 infracciones de 13 frente a 5 de 13
Fuente: Habr AI. Collage: Hamidun News.
Escuchar artículo
Ficha técnica y cifras clave
ParámetroDatos
Fuente originalHabr AI ↗
Editor jefe
El skill no superó a AGENTS.mdel archivo raíz simplemente quedó más corto
Vercelsin una referencia explícita en AGENTS.md, el skill no se invocó en el 56 % de los casos
ETH Zurichlos archivos generados por el modelo encarecieron las tareas entre un 20 % y un 23 %

Trabajas una semana con un agente de IA en un proyecto y acordáis que el SQL solo va en db.py, los errores se gestionan con AppError y la cancelación de una suscripción modifica el campo status y escribe un registro en el log de auditoría. La sesión se cierra.

Al día siguiente, una nueva sesión añade un informe de ingresos, coloca conn.execute directamente en el servicio, crea la columna cancelled_at y se olvida de la auditoría. Los tests están en verde, el informe calcula bien, pero las decisiones del equipo se quedaron en el chat de ayer.

El Tech Lead Serguéi Proshchaev comprobó en 18 sesiones de Codex si el archivo AGENTS.md soluciona esto. Es un archivo de texto normal con las reglas del proyecto que el agente lee al arrancar.

Resultado: sin reglas, el agente incumplió 5 de 13 decisiones verificables; con AGENTS.md o con un skill, es decir, un directorio aparte con instrucciones, incumplió 0 de 13.

Qué mostró el experimento

El autor ejecutó Codex CLI 0.166.0 sobre un pequeño servicio en Python. La tarea: suscripciones con precio en rublos, cancelación e informe de ingresos. Cada sesión arrancaba desde cero, en un directorio aislado y sin historial de conversaciones. Se compararon tres variantes: sin reglas, con AGENTS.md y con un skill independiente. Cada variante se ejecutó tres veces.

En la primera ronda hubo ocho comprobaciones. Sin reglas, el agente incumplió dos en cada sesión: llamó price_kopecks a la columna de importes en lugar del nombre acordado y colocó SQL en el servicio, aunque users.py accede a la base de datos a través de db.py. El resto lo dedujo del código por su cuenta: guardó el dinero en kopeks, obtuvo la hora mediante clock y lanzó AppError.

En la segunda ronda, el autor añadió cinco decisiones que chocan con los hábitos del modelo. Sin reglas, en las tres sesiones el agente creó cancelled_at en lugar de status, no llamó a db.add_audit, aunque la función existía en el proyecto, y escribió los códigos de error al estilo antiguo bad_price. Estas son las 5 infracciones de 13 comprobaciones. Con AGENTS.md y con el skill no hubo ninguna infracción. Los tests de aceptación pasaban en todas las variantes, incluida la de «sin reglas». Los tests habituales no detectan estos acuerdos, por lo que hizo falta un script aparte, check.py, que analiza el código con ast.

El autor descartó honestamente dos indicadores. El UUID lo generó el agente sin reglas, porque la firma requería un id de tipo cadena. El formato de los logs no se incumplió, porque en el nuevo módulo simplemente no había logs.

Cómo escribir las reglas

Paso 1: para cada decisión, pregúntate si el agente lo haría así por sí mismo. La respuesta no debe ser una suposición, sino una sesión sin reglas. Paso 2: cada regla debe tener un motivo y un indicio observable de incumplimiento, y lo prohibido debe nombrarse de forma explícita (cancelled_at, execute). Si el código antiguo no cumple la regla, indícalo en la propia regla; de lo contrario, el agente tomará como modelo lo que ve alrededor.

Paso 3: en el AGENTS.md raíz incluye las decisiones que afectan a cualquier cambio. Codex lee el archivo global y, después, un archivo por directorio desde la raíz hasta el directorio de trabajo. El límite total project_doc_max_bytes es, por defecto, de 32 KiB. Las reglas de un módulo conviene guardarlas en el AGENTS.md de su directorio.

Paso 4: lo extenso va a un skill, pero enlázalo desde AGENTS.md. El agente solo ve la cabecera del skill y decide por sí mismo si carga el resto. En la medición de Vercel con la documentación de Next.js 16, el skill no se invocó en el 56 % de los casos y la tasa de tareas resueltas se quedó en el 53 %, igual que sin documentación. Una frase explícita en AGENTS.md la elevó al 79 %, y un índice comprimido directamente en el archivo dio el 100 %. En el experimento de Proshchaev la referencia siempre estuvo presente, y el skill se abrió en seis de seis sesiones.

Paso 5: verifica las reglas en un entorno limpio. El autor tiene en su AGENTS.md global 62 KB de reglas personales y cerca de cien skills, así que la variante «sin reglas» no habría sido realmente sin reglas sin aislamiento. Para la prueba, HOME y CODEX_HOME apuntan a un directorio temporal. Paso 6: convierte las decisiones en comprobaciones automáticas y prueba las propias comprobaciones con código deliberadamente roto.

Limitaciones y coste

El experimento es pequeño: un modelo, una tarea y tres sesiones por variante. La tasa de infracciones de otros agentes no puede deducirse de aquí. El skill no aportó una mejora medible frente a AGENTS.md; su ventaja es solo organizativa. El script check.py solo detecta formas de infracción conocidas de antemano: el SQL a través de otro helper pasaría desapercibido.

El archivo de contexto cuesta dinero. Según el estudio de ETH Zurich «Evaluating AGENTS.md», los archivos generados por el modelo no aumentaron la tasa de tareas resueltas, pero el coste subió entre un 20 % y un 23 %. Los archivos escritos por desarrolladores aportaron +2,4 % de tareas resueltas, una diferencia estadísticamente no significativa, con un aumento de coste de hasta el 19 %. Los agentes empiezan a investigar y a probar más, y eso también consume tokens.

Conclusión práctica: toma las tres últimas correcciones que hiciste a mano tras el agente, escríbelas como reglas con un indicio de incumplimiento y ejecuta una sesión en un entorno limpio. Las reglas que el agente incumple sin el archivo y cumple con él son las que deben formar tu AGENTS.md. Lo demás solo añade costes. El soporte de formatos depende de la herramienta: Claude Code lee CLAUDE.md, Gemini CLI lee GEMINI.md por defecto, así que conviene revisar la documentación de tu agente.

Historia

Preguntas frecuentes sobre la noticia

¿Qué se sabe sobre Qué mostró el experimento?

El autor ejecutó Codex CLI 0.166.0 sobre un pequeño servicio en Python. La tarea: suscripciones con precio en rublos, cancelación e informe de ingresos. Cada sesión arrancaba desde cero, en un directorio aislado y sin historial de conversaciones. Se compararon tres variantes: sin reglas, con AGENTS.md y con un skill independiente. Cada variante se ejecutó tres veces. En la primera ronda hubo ocho comprobaciones.

Cómo escribir las reglas?

Paso 1: para cada decisión, pregúntate si el agente lo haría así por sí mismo. La respuesta no debe ser una suposición, sino una sesión sin reglas. Paso 2: cada regla debe tener un motivo y un indicio observable de incumplimiento, y lo prohibido debe nombrarse de forma explícita (cancelled_at, execute). Si el código antiguo no cumple la regla, indícalo en la propia regla; de lo contrario, el agente tomará como modelo lo que ve alrededor.

¿Qué se sabe sobre Limitaciones y coste?

El experimento es pequeño: un modelo, una tarea y tres sesiones por variante. La tasa de infracciones de otros agentes no puede deducirse de aquí. El skill no aportó una mejora medible frente a AGENTS.md; su ventaja es solo organizativa. El script check.py solo detecta formas de infracción conocidas de antemano: el SQL a través de otro helper pasaría desapercibido. El archivo de contexto cuesta dinero.

ZK
Zhemal Khamidun — CPO de Alpina Digital, product manager de AlpinaGPT. Crea productos de IA desde 2019. Hamidun News es un proyecto personal que creció hasta ser un agregador en producción con más de 6.000 lectores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
¿Qué te parece?
Cargando comentarios…