Cómo escribir AGENTS.md para que Codex entienda las reglas de tu proyecto

Codex dice “terminado”, ejecutas pnpm test y recién ahí descubres que nunca lanzó los tests. O, dentro de un monorepo, ejecuta desde la raíz los tests del package equivocado. Repetir esas instrucciones cansa: npm run build, pnpm test, no modificar generated, correr lint antes de cerrar. AGENTS.md es donde escribes esas reglas dentro del proyecto para que Codex no tenga que preguntarlas otra vez.

Si acabas de completar la guía de inicio de Codex y la elección de entrada, el siguiente paso no es pedirle que refactorice todo el proyecto. Primero deja por escrito las reglas que sueles repetirle.

Vamos con un esqueleto de 12 a 20 líneas. Después vemos el mecanismo de carga en tres capas, cómo verificar que surtió efecto, qué no conviene escribir, cómo convivir con CLAUDE.md o Cursor Rules y cuándo actualizar el archivo.

AGENTS.md no es README; es el manual de trabajo persistente de Codex

README.md está escrito para personas. Explica qué es el proyecto, cómo instalarlo y cómo empezar. AGENTS.md está escrito para Codex. Contiene las reglas que se cargan cada vez que empieza una tarea: cómo construir, cómo probar, qué directorios no tocar y qué revisar antes de dar algo por terminado.

Según la documentación oficial de OpenAI, Codex lee AGENTS.md antes de empezar a trabajar y lo incorpora al contexto. No es lo mismo que repetir “npm run build” o “pnpm test” en cada chat. AGENTS.md es una guía persistente del proyecto.

Hay un límite importante: AGENTS.md no es una memoria de largo plazo ni una base de conocimiento que aprenda sola. Es un archivo estático cargado al inicio. Si necesitas acumular conocimiento entre sesiones o gestionar memoria de agentes, la guía anterior sobre memoria de agentes IA explica la separación entre memoria persistente y reglas de proyecto.

Cómo encuentra Codex tu AGENTS.md: tres capas de carga

El orden de lectura de Codex se entiende en tres capas: global, proyecto y fusión. Comprenderlo ayuda a saber dónde aplica una regla y por qué a veces parece no aplicar.

Capa global: tus hábitos personales

Codex primero busca en tu directorio de usuario ~/.codex. Esta capa sirve para hábitos personales, como idioma de respuesta, preferencias de estilo o herramientas comunes. Importante: la capa global lee como máximo un archivo, en este orden: AGENTS.override.md -> AGENTS.md. No combina ambos.

Capa de proyecto: desde la raíz Git hasta el directorio actual

En la capa de proyecto, Codex escanea desde la raíz Git o del proyecto hasta el directorio de trabajo actual. En cada nivel también lee como máximo un archivo, en este orden: AGENTS.override.md -> AGENTS.md -> fallback filenames. Los nombres fallback pueden configurarse con project_doc_fallback_filenames, por ejemplo para incluir TEAM_GUIDE.md. Trata el nombre exacto de las opciones como parte de la documentación oficial.

Orden de fusión: cuanto más cerca, más específico

Todos los archivos encontrados se concatenan desde la raíz hasta el directorio actual. Cuanto más cerca está un archivo del directorio actual, más tarde aparece en el contexto. Eso hace que la regla local sea más fácil de priorizar para Codex.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Ejemplo: la raíz de un monorepo tiene AGENTS.md con “la prueba se ejecuta con pnpm test”. apps/web/AGENTS.md dice “la prueba se ejecuta con pnpm --filter web test”. Si Codex arranca en apps/web, lee primero las reglas de raíz y después las de apps/web. El comando de apps/web es más específico.

Resumen de las tres capas

La raíz debe contener reglas compartidas del equipo. Los subdirectorios deben contener reglas locales, por ejemplo un comando de test distinto para un package. AGENTS.override.md sirve para reemplazos temporales o locales. No lo conviertas en el estándar del equipo, porque oculta las reglas reales y complica la colaboración.

La plantilla mínima: ¿qué 6 bloques escribir primero?

OpenAI recomienda tratar AGENTS.md como un “open-format README for agents”. La clave es que sea corto, real y verificable. No copies de entrada una plantilla de 300 líneas. Empieza con 6 bloques básicos y amplía solo cuando haga falta.

El esqueleto inicial contiene estos 6 bloques:

1. repo layout: stack y estructura de directorios, para que Codex sepa dónde están frontend, backend y tests
2. Commands: comandos exactos de build, test y lint. Escribe pnpm test, no “ejecutar tests”
3. Constraints: directorios o acciones que Codex debe evitar, como src/generated/
4. PR expectations: qué revisar antes de enviar y qué espera la review
5. Done when: criterios verificables de finalización, como pnpm test y pnpm build
6. Convenciones especiales, como gestor de paquetes, estilo de código o reglas de nombres

Para un panel SaaS, el archivo inicial puede verse así:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review

## PR expectations
- Add tests for new features
- Run `pnpm test` before marking done

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Esta plantilla es lo bastante corta para no ensuciar el contexto. Empieza con esos 6 bloques y amplía cuando aparezca un problema repetido. No metas de entrada visión de producto, listas de dependencias, diagramas de arquitectura ni índices de API docs. Un archivo enorme entierra las reglas que importan.

Cómo confirmar que Codex leyó de verdad tu AGENTS.md

Después de escribir AGENTS.md, verifica que funcione. La documentación de OpenAI recomienda:

codex --ask-for-approval never "Summarize the current instructions."

Ese comando hace que Codex resuma las instrucciones cargadas. Si la salida contiene tus reglas, como el comando de test o el directorio que no debe tocar, está funcionando. Si no aparece nada, o aparecen otras reglas, toca depurar la cadena de carga.

Checklist de diagnóstico

Si sigue sin funcionar, revisa la documentación de OpenAI Custom instructions o actualiza Codex. No lo trates como magia: ruta, versión, configuración y directorio actual afectan el resultado.

Qué no debería entrar en AGENTS.md

AGENTS.md no es un almacén universal. Algunas cosas generan riesgos de seguridad, mantenimiento o ruido de contexto. Mantén fuera lo siguiente.

1. Secretos, API keys y contraseñas de producción

No escribas secretos, contraseñas de producción ni API tokens en AGENTS.md. Codex lee el archivo en el contexto y también puede quedar visible para el equipo o commiteado en Git. Usa variables de entorno, archivos .env sin commit o un sistema dedicado de secrets. Si Codex necesita secrets dentro de una sandbox, trátalo como un problema de capa de ejecución.

2. Listas grandes que caducan

No listes todas las dependencias, cifras del ecosistema, precios, cuotas, rutas o campos de base de datos. Una lista como “React 18.2, Vue 3.4, TypeScript 5.0…” envejece rápido. Escribe el proceso para añadir una dependencia, no todo el inventario actual.

3. Lemas abstractos

“Mantener alta calidad”, “escribir código elegante” o “asegurar mantenibilidad” no se ejecutan. Cámbialos por checks: pnpm test pasa, pnpm lint no tiene errores, las nuevas features tienen tests o Lighthouse no baja del umbral acordado.

4. Comandos vagos

“Ejecutar tests” y “comprobar el build” son demasiado vagos. Escribe comandos exactos: pnpm test, pnpm build o lighthouse --preset=desktop.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

5. Requisitos no verificables

“Garantizar mejor rendimiento” o “mejorar la UX” no tiene un límite de cierre. Usa checks medibles, como una API por debajo de 200 ms o un objetivo de Lighthouse.

6. Preferencias personales en la raíz del repo

“Responder en chino”, “respuestas de menos de 100 palabras” o “usar VS Code por defecto” son preferencias personales, no reglas compartidas del proyecto. Ponlas en ~/.codex/AGENTS.md. La raíz del repo debe contener estándares del equipo.

La regla es simple: corto, real y verificable. AGENTS.md reduce instrucciones repetidas. No es un lugar para pegar toda la documentación del proyecto.

Si ya tienes CLAUDE.md o Cursor Rules

Si usas Claude Code o Cursor, puede que el repositorio ya tenga CLAUDE.md o Cursor Rules. No hace falta mantener tres copias. Usa importación o coexistencia.

AGENTS.md vs CLAUDE.md: importar reglas compartidas

Claude Code lee CLAUDE.md, no AGENTS.md. Si el repo ya tiene AGENTS.md, puedes crear un CLAUDE.md pequeño que lo importe:

@AGENTS.md

## Claude-specific
- Prefer Chinese responses
- Keep responses concise (under 100 words unless requested)

@AGENTS.md es la sintaxis de importación. Claude Code lee AGENTS.md y luego la sección Claude-specific. Así las reglas compartidas quedan en AGENTS.md y las preferencias propias de Claude quedan en CLAUDE.md.

AGENTS.md vs Cursor Rules: Cursor tiene su propio sistema

Cursor tiene su propio sistema de Rules, con reglas de proyecto, equipo y usuario. La documentación oficial y los resúmenes de búsqueda de Cursor mencionan soporte para AGENTS.md, pero los detalles de carga conviene verificarlos en la documentación actual de Cursor. Si usas Cursor y Codex, pon las reglas comunes en AGENTS.md y deja el comportamiento propio del editor Cursor en Cursor Rules.

AGENTS.md vs config.toml, Rules, Skills y MCP

AGENTS.md es la capa de instrucciones. Le dice a Codex cómo trabajar. Los controles de ejecución viven en otro lado: permisos, sandbox, política de comandos e integraciones de herramientas.

AGENTS.md resuelve explicaciones repetidas de reglas del proyecto. Rules, config, sandbox y permisos controlan ejecución. Skills encapsula workflows reutilizables. MCP conecta herramientas externas. Mantener esas fronteras claras evita confusión.

Cuándo actualizar AGENTS.md

AGENTS.md no necesita cambiar cada vez que cambia el proyecto. Actualízalo cuando se repita la misma fricción.

Desencadenantes de actualización

La documentación de OpenAI recomienda actualizarlo en estos casos:

1. Codex repite el mismo error: edita dos veces el directorio equivocado o siempre ejecuta el test del package incorrecto. Añade una restricción concreta, como “Do NOT edit src/generated/” o “Use pnpm --filter web test for web changes”.

2. La PR review repite el mismo comentario: reviewers insisten en “esta modificación necesita tests”, “no modifiques generated code” o “evita default export”. Añade ese patrón a PR expectations.

3. Codex lee demasiados documentos para encontrar la respuesta: si cada vez debe buscar en varias capas para encontrar el test correcto o el flujo de build, añade esa información esencial arriba.

Actualiza el directorio más cercano

Pon la regla donde ocurre el error. No todo debe ir a la raíz. En un monorepo, distintos packages pueden tener reglas distintas, así que cada package puede tener su AGENTS.md local.

Si Codex ejecuta el test equivocado trabajando en apps/web, añade la regla en apps/web/AGENTS.md. Una regla de raíz puede terminar aplicando demasiado.

🔥 ¡No pierdas meses en productos sin demanda! Valida los puntos fuertes de tu SaaS con Adsterra y poco presupuesto →

Probar ahora →Anuncio

Diferencia con memoria de largo plazo

AGENTS.md es un archivo estático cargado al inicio. No es una memoria que aprenda automáticamente. Codex no lo actualizará a partir de tus correcciones salvo que se lo pidas de forma explícita.

Si necesitas conocimiento entre sesiones o gobernanza de memoria, la guía sobre memoria de agentes IA es el siguiente punto de referencia.

Hacer crecer la plantilla: de semilla a versión extendida

No empieces con una plantilla de 300 líneas. Empieza con 12 a 20 líneas y amplía solo cuando aparezca un desencadenante repetible.

Versión semilla: solo los 6 bloques centrales

La versión semilla cubre repo layout, comandos comunes, restricciones, expectativas de PR y done/verify. Puede ser así de pequeña:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)

## PR expectations
- Add tests for new features

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Desencadenantes de expansión: cuándo añadir un bloque

Después de algunas ejecuciones, amplía solo por problemas concretos:

1. La primera vez que Codex edita el directorio equivocado: si toca migrations/ o generated/, añade en Constraints “Do NOT commit migrations/ without team review” o “Do NOT edit any file in src/generated/”.

2. La primera observación repetida en PR review: si los reviewers piden tests o named exports una y otra vez, añade “Add tests for new features” o “Use named exports, not default exports”.

3. El primer error con el gestor de paquetes: si un proyecto pnpm recibe comandos npm, añade “Always use pnpm, not npm or yarn”.

4. El primer olvido de lint: si Codex termina sin lint, añade “pnpm lint passes with no errors” bajo Done when.

Versión extendida: 30 a 50 líneas

Una versión extendida puede sumar restricciones, expectativas de PR, reglas de gestor de paquetes y requisitos de lint:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Always use pnpm, not npm or yarn

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT modify .env files (use .env.example as template)

## PR expectations
- Add tests for new features
- Run `pnpm test` and `pnpm lint` before marking done
- Use named exports, not default exports
- Keep components under 200 lines; split if larger

## Done when
- `pnpm test` passes
- `pnpm build` succeeds
- `pnpm lint` passes with no errors
- New features have corresponding tests

La idea central: crecer por desencadenantes, no por anticipación. AGENTS.md vale por reducir explicaciones repetidas, no por mostrar todos los documentos del proyecto.

Conclusión

AGENTS.md es guía persistente del proyecto. No es un almacén universal ni un sistema de memoria de largo plazo. Resuelve un problema concreto: no tener que repetir las mismas reglas cada vez que Codex empieza a trabajar.

Pasos prácticos:

1. Empieza con una semilla de 12 a 20 líneas: repo layout, comandos, restricciones, expectativas de PR y done/verify. No empieces con una plantilla gigante.

2. Verifica que Codex la cargó: ejecuta codex --ask-for-approval never "Summarize the current instructions." y busca tus reglas en la respuesta.

3. Amplía por desencadenantes repetidos: Codex repite un error, la PR review repite una observación o Codex debe buscar demasiado para encontrar la información.

4. Mantén fuera lo peligroso y lo perecedero: nada de secretos, inventarios caducos, lemas, comandos vagos, objetivos no verificables ni preferencias personales en la raíz.

5. Usa importación y coexistencia con CLAUDE.md o Cursor Rules: reglas compartidas en AGENTS.md y comportamientos específicos en los archivos de cada herramienta.

AGENTS.md le da a Codex un contexto de proyecto estable. Otros artículos de esta serie Codex pueden mover workflows repetibles a Skills, tratar límites de permisos y secretos, y hacer más fiable done/verify con failure reviews y PR checks.