Cómo escribir un archivo AGENTS.md para agentes de programación
Escribe un AGENTS.md breve con comandos de instalación y pruebas, reglas y límites, haz que Claude Code y Gemini CLI lo carguen y pruébalo con una tarea pequeña.
Un archivo AGENTS.md es un archivo Markdown normal, en la raíz del repositorio, que explica a los agentes de programación cómo trabajar en el proyecto: qué comandos ejecutar, dónde está el código y qué no deben tocar. No tiene secciones obligatorias. Hazlo breve, escribe cada regla de forma que se pueda comprobar y confirma que cada agente lo carga.
Esta guía explica qué incluir, ofrece una plantilla, cuenta cómo encuentran el archivo Claude Code y Gemini CLI y propone una prueba rápida. Los mismos pasos sirven cuando inicias agentes desde el móvil con Mono de Reunified.
1. Decide qué va en el archivo
El sitio agents.md lo define como un README para agentes. Incluye lo que necesita cada sesión y omite lo que el agente puede averiguar leyendo el código.
| Va en AGENTS.md | Déjalo fuera |
|---|---|
| Comandos de instalación, pruebas y lint | Contraseñas, claves de API y tokens |
| Dónde está el código principal | Un árbol completo de archivos o la lista de dependencias |
| Convenciones que se apartan de lo habitual | Procedimientos largos (enlaza a un documento) |
| Archivos que nunca se editan, acciones que hay que consultar antes | Preferencias personales (usa el archivo de usuario de tu agente) |
En un monorepo, puedes añadir un AGENTS.md dentro de cada paquete. Tiene prioridad el archivo más cercano, y una instrucción directa en el chat prevalece sobre él.
2. Parte de una plantilla breve
Este es un ejemplo inventado para «tidy-recipes», una app web en TypeScript que usa pnpm:
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.Incluye solo comandos que hayas ejecutado en este repositorio. El agente se fiará igual de uno incorrecto.
3. Escribe reglas que se puedan comprobar
Una buena regla te permite comprobar después si el agente la ha seguido.
| Vaga | Concreta |
|---|---|
| Prueba tus cambios | Ejecuta pnpm test y pnpm lint antes de terminar |
| Mantén los archivos organizados | Los componentes van en src/components |
| Ten cuidado con la base de datos | No edites nunca db/migrations/ |
| Resume tu trabajo | Indica los archivos cambiados y los resultados de las pruebas |
Escribe los límites como reglas de «nunca» y de «pregunta antes», una por línea.
4. Haz que Claude Code y Gemini CLI lo lean
El sitio agents.md enumera Codex, Gemini CLI, opencode y otros agentes compatibles con el formato, pero algunos necesitan antes un ajuste.
Por defecto, las versiones recientes de Claude Code solo leen AGENTS.md cuando no hay ningún CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el directorio de trabajo ni por encima de él (consulta su documentación sobre la memoria). Si tienes uno de esos archivos o una versión anterior, importa AGENTS.md desde CLAUDE.md. El proyecto tidy-recipes tiene un CLAUDE.md antiguo, así que añade esta línea al principio y deja debajo las notas que solo son para Claude:
@AGENTS.md
Prefer small commits.Empieza una sesión nueva, ejecuta /context y comprueba que CLAUDE.md aparece en la sección de archivos de memoria (Memory files). Si no hay ningún CLAUDE.md, /memory muestra en su lugar la ruta de AGENTS.md.
Gemini CLI lee GEMINI.md por defecto. Para añadir AGENTS.md, pon esto en el .gemini/settings.json del proyecto (consulta su documentación de GEMINI.md):
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}Empieza una sesión nueva y ejecuta /memory show para ver qué se ha cargado. Para otros agentes, consulta su documentación.
5. Prueba el archivo con una tarea pequeña
En una sesión nueva, dale al agente esta tarea:
Primero enumera las reglas del proyecto que has cargado y el archivo del que viene cada una. Después cambia el texto del botón «Guardar receta» por «Guardar» en src/components/SaveButton.tsx. No cambies nada más.
Compara el resultado con el archivo:
- Ha nombrado AGENTS.md (o CLAUDE.md con la importación).
- Ha ejecutado
pnpm testypnpm linty ha informado de los resultados. - No ha tocado db/migrations/ ni ha añadido ninguna dependencia.
- Ha enumerado los archivos que ha cambiado.
Confirma el cambio por tu cuenta con git diff (consulta cómo revisar cambios de código generados por IA). Si el agente no sabe nombrar una regla, probablemente el archivo no se ha cargado, así que vuelve al paso 4. Si ha nombrado una regla y no la ha cumplido, hazla más concreta.
6. Mantenlo breve y al día
La documentación de Claude Code recomienda que CLAUDE.md tenga menos de 200 líneas, porque los archivos más largos ocupan más contexto y se siguen con menos fiabilidad. Aplica el mismo límite a AGENTS.md. La guía sobre la ventana de contexto explica qué pasa cuando se llena el contexto.
Actualiza el archivo cuando un agente repita un error, y borra los comandos obsoletos y las reglas que se contradicen. Haz commit del archivo y revisa sus cambios como si fueran código.
El archivo orienta al agente, pero no impone nada. Para bloquear una acción, usa los ajustes de permisos del agente o deniega su solicitud (consulta la guía de permisos de herramientas).
En Mono, el agente se inicia en el directorio de trabajo del proyecto en tu ordenador, donde busca estos archivos. Puedes abrir AGENTS.md, CLAUDE.md o .gemini/settings.json en el editor de Mono, también desde el móvil, y los cambios se guardan solos. Para crear el archivo, pídeselo al agente o abre una terminal desde la tarjeta del proyecto. Mono no revisa el archivo ni cambia cuál carga un agente. Mono aún no está disponible, pero puedes apuntarte a la lista de espera.
