Cómo funcionan las rules y el AGENTS.md en distintos Coding Agents
Serie de artículos sobre funcionalidades para inyectar contexto en los coding agents:
En esta artículo nos centramos en cómo funcionan las rules en distintos coding agents.
El AGENTS.md es equivalente a una regla de Siempre y en la documentación de algunas herramientas lo tratan en conjunto, así que también lo haremos así en este artículo.
Las herramientas en general llaman rules a archivos markdown con un frontmatter que controla bajo que condiciones se inyecta en el contexto:
- Siempre.
Always on,loaded unconditionally. Equivalente (en algunas herramientas) a referenciar documentos con@desde elAGENTS.md. - Bajo criterio del modelo.
Apply Intelligently,model_decision,lazy loading. Equivalente a una regla en elAGENTS.mdestilo:Read docs/python-guidelines.py when working with python code. - Manual. Equivalente chat referenciar un documento con
@en la conversación. - glob. Cuando se trabaje en un fichero que cumpla el glob el markdown es inyectado. Lo más parecido serían las herramientas que leen
AGENTS.mden subcarpetas y lazy loading.
¿Qué significa equivalente?
- Los modelos son cajas negras estocásticas. Dada la misma entrada no tienen porqué producir la misma salida. Sólo se puede decidir cual la mejor entrada para obtener la salida deseada a base de prueba y error.
- El harness es tan relevante cómo el modelo en sí. En las herramientas que tienen el código fuente disponible es más fácil tomar decisiones informadas. Las técnicas tipo Man in the Middle también ayuda.
- Harness y Modelos cambian a menudo, se debería estar haciendo una evaluación continua y eso no está al alcance de todos los equipos. De hecho, ni siquiera es viable para muchos equipos leer los "resúmenes".
Así que hay que tomarse equivalente, o cualquier artículo de internet con mucho cuidado.
Por ejemplo, la documentación de Claude indica específicamente que una regla tiene la misma prioridad en el contexto que él CLAUDE.md. Pero no tiene porqué ser así en otras herramientas. Cuando poner un documento en la parte de arriba o bajo del prompt, puede modificar en un 30% la calidad del resultado, la forma en que el harness wrapee e inyecte el contexto al modelo puede tener mucho impacto.
Es decir. Qué @path desde el AGENTS.md se envíe siempre al llm, al igual que una regla de Always on, no tiene porqué significar que se fuerce la misma atención del modelo sobre los dos métodos.
Antigravity
Antigravity maneja dos conceptos similares, en la misma sección de la documentación: rules y workflows.
Los workflows:
- Son ficheros markdown con un frontmatter (propiedad
description) - Se almacenan en
~/.gemini/antigravity/global_workflowso.agents/workflows. - Parece que sólo se puede invocar de forma manual, usando:
/my-workflow. Y unos workflows pueden llamar a otros - Los definen así:
- While Rules provide models with guidance by providing persistent, reusable context at the prompt level, Workflows provide a structured sequence of steps or prompts at the trajectory level, guiding the model through a series of interconnected tasks or actions.
Las rules:
- Son ficheros markdown con un frontmatter
- Se almacenan en
.agents/rules - No hay reglas globales. A nivel global, coge el documento que se haya definido para gemini-cli
~/.gemini/GEMINI.md - Se pueden invocar manualmente con
@my-rule.md. Y siguen los criterios de: siempre, manual, el modelo decide, glob.
El frontmatter sería:
trigger: manual | always_on | glob | model_decision
# Sólo cuando trigger = 'glob'
globs: \*.py
# Sólo cuando trigger = 'model_decision'
description: "foo"
WTF
- rules y workflows se pueden crear mano, o desde la GUI. Cuando en Antigravity se abre un fichero en esas carpetas, el editor no es el de texto normal, si no, uno con widgets pensado para la edición de estos documentos.
- Reglas y Workflows están limitados a 12.000 caracteres.
- Por estimación gruesísima, 12.000 caracteres de lorem-ipsum son 1.753 palabras, 3.716 tokens.
- Aunque según un LLM la documentación técnica en inglés tiene de media 5 caracteres por palabra más un espacio. Eso serían unas 2.000 palabras, 2.666 tokens. En castellano los números salen un poco peor.
- O de otra forma asumiendo 1 token = 4 caracteres (inglés) serían 2.500 tokens.
- La documentación no tiene buscador y no he encontrado ninguna mención a
AGENTS.md
OpenCode
En el caso de OpenCode bajo la sección rules hacen referencia directa al uso de AGENTS.md.
Un único fichero en el root del proyecto o uno global en ~/.config/opencode/AGENTS.md. También permite definir la lista de ficheros que se añadirán automáticamente al contexto. Es una funcionalidad interesante porque permite usar globs (para los ficheros a leer no para cuando se leen) y urls.
{
"$schema": "https://opencode.ai/config.json",
"instructions": [
"CONTRIBUTING.md",
"docs/guidelines.md",
".cursor/rules/*.md",
"https://myurl.com/style.md"
]
}
Al contrario que otras herramientas no siguen automáticamente referencias @path. Recomiendan el uso de lazy loading a través del AGENTS.md: For testing strategies and coverage requirements: @test/testing-guidelines.md
gemini-cli
Tampoco tiene rules. Lo más parecido es el AGENTS.md que engloban bajo Manage Context and Memory. Por defecto usan el fichero GEMINI.md pero se puede usar otro mediante configuración.
Se pueden poner en la raíz del proyecto, o en ~. También en subdirectorios de modo que sólo cargue cuando se trabaje con ficheros en bajo ese árbol.
gemini tiene además una tool de save_memory. Un prompt cómo remember that by database is at port 5433 añadirá una línea a ~/.gemini/GEMINI.md
Si se usa @path en un documento lo carga automáticamente.
Tiene también un comando /memory show que permite ver las instrucciones que se están usando. Muy útil para depurar.
WTF
- Tienen dos páginas donde cuentan prácticamente lo mismo "Manage Context and Memory" y Project Context.
- Permite modificar el System Prompt.
OpenAI Codex CLI
Codex no tiene rules y hay que ir directamente a la documentación sobre el AGENTS.md. Cómo el resto admiten ficheros a nivel de proyecto y de ~. Tiene además una funcionalidad curiosa, si existe un fichero AGENTS.override.md lee ese en lugar de AGENTS.md
Incluye el AGENTS.md de subdirectorios.
La documentación explica varios puntos interesantes
Merge order: Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.
La forma de premiar la atención de un AGENTS.md sobre otro anidado, es simplemente ponerlo más abajo en el prompt.
Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default). For details on these knobs, see Project instructions discovery. Raise the limit or split instructions across nested directories when you hit the cap.
Asumiendo UTF8 (de 1 byte para la mayoría de letras hasta 4 bytes para los emojis), pongamos un cálculo grueso de 32k caracteres en inglés, 1 token = 4 caracteres, unos 8.000 tokens.
En la documentación dan varios trucos para depurar las instrucciones.
WTF
- Codex CLI maneja el concepto de rules pero con un significado totalmente distinto al resto de herramientas. Se usa para definir los permisos de los comandos que Codex puede ejecutar. Muy feo que no se alineen con el resto en cómo llamar a las cosas.
- No he encontrado en la documentación si sigue automáticamente
@path
Claude
La documentación de Claude llama a este tipo de funcionalidades extension layer. En la página resumen hablan muy poco de rules, lo que seguramente significa que no quieren darle mucha relevancia.
En la sección de Memory se extienden tanto en lo referido al AGENTS.md cómo a las rules.
El AGENTS.md:
- Va en el proyecto,
~o subdirectorios. - Recomiendan que no sea de más de 500 líneas. Y ya tenemos una tercera forma distinta de limitar o recomendar el tamaño de este fichero: caracteres, KiB y líneas
- Por decir algo 50 caracteres por lína, 4 caracteres por token, serían 6250 tokens.
- Carga automáticamente las referencias
@path - Una funcionalidad interesante es que comentarios estilo
<!-- maintainer notes -->son eliminados antes de inyectar el fichero en el contexto.
Las rules:
- Son ficheros markdown con un frontmatter
- Se almacenan en home (
~/.claude/rules/) y el proyecto (.claude/rules/). Admitiendo organizarlas en subdirectorios. - Se pueden:
- invocar manualmente con
@.claude/rules/my-rule.md - Siempre. Si no tiene frontmatter se cargará automáticamente con la misma prioridad que el
CLAUDE.md. - Con globs. Cuando en el frontmatter hacia una propiedad paths (ie:
paths: *.py), sólo cargan cuando se cumple el glob.
- invocar manualmente con
WTF
- La documentación de Claude es de largo la mejor. Esta visualización interactiva del Context Window es un lujo.
- Tiene un comando
/memorypara ayudar a depurar. También recomiendan usar un hook para depurar: "Use the InstructionsLoaded hook to log exactly which instruction files are loaded, when they load, and why" - Claude usa
CLAUDE.mden lugar deAGENTS.mdy no hay posibilidad de configuración. - Claude tiene además una funcionalidad de "Auto Memory", que se puede deshabilitar en la configuración.
En una parte de la documentación hablan de las 500 líneas, mientras que en otra escriben:
Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. If your instructions are growing large, split them using imports or .claude/rules/ files.
A esta frase no le acabo de ver el sentido. Si los imports (@path) se incluyen automáticamente, y las rules tienen la misma prioridad que el AGENTS.md. No sé porqué cinco ficheros de cien líneas es mejor que un AGENTS.md de 500 líneas. Otra cosa sería usar globs y lazy loading.
200 líneas a 50 caracteres por línea son 2.500 tokens.
Cursor
La documentación de Cursor incluye en la sección de reglas tanto lo que estamos llamando rules cómo el AGENTS.md
El AGENTS.md:
- Va en el proyecto, o en subdirectorios. No se puede usar a nivel global.
- En las pruebas que he hecho no parecen seguir automáticamente los
@pathen elAGENTS.mdpero si en las rules
Admiten Team Rules para las cuentas de equipo y Enterprise que se configuran a través del dashboard.
Admiten User Rules:
- No se usan en Tab ni Inline Edits. No definen si funcionan en modo Plan o Debug, pero asumo que sí.
- Sólo se pueden gestionar a través de la UI. Lo lógico sería almacenarlas
~/.cursor/rules, pero no. Muy mal Cursor.
Admiten project rules:
- Son ficheros markdown con un frontmatter
- Se almacenan en
.cursor/rules. Admitiendo organizarlas en subdirectorios. - Se pueden invocar manualmente con
@my-rule.md. Y siguen los criterios habituales (siempre, manual, el modelo decide, glob) - Recomiendan mantenerlas por debajo de las 500 líneas.
El frontmatter no está bien definido.
description. No se aclara si se usa para algoglobs.- Hay otras propiedades:
Always Apply,Apply Manually,Apply Intelligently. Pero la documentación de cómo se usan es mala. ¿Se supone que son propiedades con ese nombre y valortruefalse?. ¿Cómo gestionan la prioridad si hay dos a true por error?
El caso más claro parece ser con glob scope:
---
glob: *.py
alwaysApply: false
---
**MUST** use modern (3.13+) type hints for all function signatures in Python code (parameters and return values)
WTF
-
Una visita al foro de ayuda de Cursor sobre reglas o los bug reports, está llena de gente diciendo que las reglas rompen de una versión a otra, no hacen lo esperado, o pidiendo explicaciones de cómo funcionan.
-
La documentación de Cursor sobre reglas empieza mal y luego no mejora.
Rules provide system-level instructions to Agent. They bundle prompts, scripts, and more together, making it easy to manage and share workflows across your team.
When applied, rule contents are included at the start of the model context. This gives the AI consistent guidance for generating code, interpreting edits, or helping with workflows.
¿scripts?. Este concepto es de las skill no de las rules. En el resto de la documentación no se vuelve a hacer referencia a scripts
-
En Cursor Settings, hay una (mala) UI de creación de reglas. No permite introducir la
description, ni el subdirectorio, y el combo de cuando aplicar tiene opciones distintas a la documentación. Escribir un fichero markdown en unTextFieldteniendo un IDE no tiene sentido. -
La idea de definir workflows en algo llamado rules, cómo sugiere la documentación no parece tener mucho sentido. No tendría más sentido los commands (ahora las skills) para esto.
Conclusiones
Sobre las reglas
-
Las reglas no son un estándar. Si se quiere usar varias herramientas a la vez es un problema.
-
Las rules parecen una buena idea que apareció en su día, pero que no acaba de funcionar o ser correctamente implementada cómo para ser usada correctamente. A menos que se limiten al glob scope
- Y, aún así, no tengo claro cuando se ejecuta la regla. En modo plan, si no accede a un fichero
*.pypara planificar tiene en cuenta las reglas, o sólo cuando pasa a escribir el código.
- Y, aún así, no tengo claro cuando se ejecuta la regla. En modo plan, si no accede a un fichero
-
Hay alternativas a las reglas, que al final son un mecanismo un poco oscuro y no estándar:
- lazy loading aunque consuma más tokens va a funcionar en todos las herramientas.
- Para las de "Siempre", varias admiten
@pathy se puede usar lazy loading cómo fallback - Skills para workflows y especialización, o incluso comandos para tareas más acotadas cómo
/git-commit
Sobre las herramientas
- Cursor, Antigravity y Claude, manejan el concepto de reglas.
- Codex no especifica si sigue
@path. OpenCode no sigue automáticamente@path. Cursor no parece seguirlo en elAGENTS.mdpero si en las rules. Los demás los siguen tanto en reglas como enAGENTS.md. - Excepto Antigravity (que no lo he probado y no pone nada en la documentación), y OpenCode (que necesita personalizarlo en las
instructions), todos los demás permitenAGENTS.mden subdirectorios. No hacen override si no merge. Generalmente poniendo más abajo en el prompt elAGENTS.mdmás cercano al trabajo que se esté haciendo para darle prioridad. - No hay consenso en las recomendaciones sobre el tamaño de las reglas de Always apply y el AGENTS, más allá de que las mantengas pequeñas y se usen skills o reglas con scope para instrucciones que no necesiten estar permanentemente en el contexto.