AGENTS.md: convenciones para coding agents en tu repo (2026)

Si cada dev pega el mismo bloque de “usa pnpm, no hagas push a main, corre los tests” en cada chat, el agente no aprende el repo: repite errores. AGENTS.md es el formato abierto (más de 60k repos, según agents.md) para dejar esas instrucciones en un solo sitio predecible. CLAUDE.md hace lo mismo en el ecosistema Anthropic. Cursor acepta AGENTS.md o rules en .cursor/rules. Esta guía ordena qué va en cada archivo, cómo evitar duplicar tres copias del mismo párrafo y un template que puedes commitear hoy.

No sustituye al system prompt del agente de producto ni a un skill SKILL.md con procedimiento largo. Es contexto del repositorio para quien edita código.

Tres capas, tres propósitos

Archivo	Quién lo lee	Qué guarda	Versionado
AGENTS.md	Codex, Cursor, Gemini CLI, Copilot, Aider…	Comandos, estilo, tests, seguridad del repo	Sí (raíz o subcarpetas)
CLAUDE.md	Claude Code (y reglas en .claude/rules/)	Mismas ideas + auto memory de Claude	Sí; CLAUDE.local.md en .gitignore
.cursor/rules/*.mdc	Cursor Agent	Rules con globs, alwaysApply, @-mention	Sí

agents.md lo define como “README para agentes”: lo que un humano no necesita en el README pero el agente sí (comandos exactos, filtros de monorepo, gotchas de CI). Claude Code pide menos de ~200 líneas por archivo, instrucciones verificables (“corre pnpm test”, no “prueba bien”) y path-scoped rules cuando el monorepo crece.

Cursor reconoce AGENTS.md como alternativa simple a .cursor/rules. Si necesitas reglas por glob (src/components/**/*.tsx) o invocación manual (@migration), usa .mdc con frontmatter. Si basta un markdown plano en la raíz, AGENTS.md alcanza.

Qué va en AGENTS.md (y qué no)

Sí:

• Comandos de setup: pnpm install, pnpm dev, pnpm test, pnpm build.
• Estilo verificable: comillas, linter, carpetas sagradas (dist/, generated/).
• Cómo correr un subpaquete en monorepo (pnpm --filter <pkg> test).
• Seguridad: nunca commitear .env, rotar keys, no --force en main.
• PR/commit: formato de mensaje, hooks que fallan, checklist pre-merge.

No:

• Procedimientos de 40 pasos → skill SKILL.md (carga on-demand).
• Rol de soporte al cliente → system prompt.
• Secretos o URLs privadas → variables de entorno o CLAUDE.local.md / .gitignore.

El estándar no exige campos obligatorios: markdown libre. La convención práctica es secciones cortas con bullets ejecutables.

Monorepos: el AGENTS.md más cercano gana

agents.md documenta AGENTS.md anidados: en el repo principal de OpenAI hay decenas de copias, una por paquete. Regla: el archivo más cercano al archivo editado tiene prioridad; el de la raíz es el default. Mismo criterio que anidar CLAUDE.md en subdirectorios (Claude los carga cuando trabaja ahí).

Patrón:

/
  AGENTS.md          # build global, CI, seguridad
  packages/
    api/
      AGENTS.md      # cómo testear solo la API, convenciones REST
    web/
      AGENTS.md      # Tailwind, Storybook, e2e del front

No copies el mismo bloque de “usa pnpm” en diez archivos: déjalo en la raíz y en los hijos solo lo específico del paquete.

AGENTS.md vs CLAUDE.md: ¿dos archivos o uno?

Muchos equipos mantienen solo AGENTS.md y un symlink o duplicado mínimo:

# Si ya tenías AGENT.md (singular), el estándar recomienda:
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Claude Code lee CLAUDE.md / .claude/CLAUDE.md por defecto, no AGENTS.md salvo que lo configures. Opciones:

1. Una fuente de verdad: contenido en AGENTS.md; CLAUDE.md con @AGENTS.md (import soportado en Claude) o un párrafo “sigue AGENTS.md”.
2. Dos audiencias: AGENTS.md = hechos del repo (todos los agentes); CLAUDE.md = extras solo Claude (auto memory, hooks, permisos deny/ask/allow).
3. Solo Claude en el equipo: CLAUDE.md completo y AGENTS.md para el resto del ecosistema (Codex en CI, Cursor en el IDE).

Evita contradecirte: si AGENTS.md dice “tabs” y CLAUDE.md “espacios”, el modelo elige al azar. Revisa tras cada incidente de code review.

Cursor: cuándo rules y cuándo AGENTS.md

Necesidad	Usa
Un markdown en la raíz, sin frontmatter	AGENTS.md
Regla solo en *.test.ts	.cursor/rules/tests.mdc con globs
Regla siempre activa	alwaysApply: true en .mdc
Playbook que solo invocas tú	rule manual + @nombre en el chat

Los .md sueltos en .cursor/rules/ no cargan (falta frontmatter .mdc). Para markdown simple, Cursor apunta a AGENTS.md.

Si el equipo mezcla IDE y CLI, comparte AGENTS.md en git y cada dev elige superficie con el mismo contrato (ver mejores agentes de código).

Template mínimo (copiar y adaptar)

# AGENTS.md

## Setup
- Install: `pnpm install`
- Dev: `pnpm dev`
- Tests: `pnpm test`
- Production build: `pnpm build`

## Code style
- TypeScript strict; match existing patterns in the file you edit.
- Run `pnpm run lint` before committing.

## Testing
- Add or update tests for behavior you change.
- Do not skip hooks (`--no-verify`).

## Security
- Never commit `.env` or API keys.
- Do not run destructive git commands unless the user explicitly asks.

## Pull requests
- Complete sentences in PR descriptions; focus on why, not only what.
- Do not merge to `main` from the agent unless asked.

Ajusta comandos a tu stack (npm, poetry, cargo). Si usas monorepo, añade sección “Working in a package” con --filter o equivalente.

Checklist de mantenimiento

• AGENTS.md en la raíz con comandos que funcionan (probados esta semana).
• Instrucciones verificables; nada de “código limpio” sin criterio.
• Monorepo: AGENTS.md por paquete solo con delta; raíz con lo global.
• Sin secretos; locales en .gitignore (CLAUDE.local.md, .env.local).
• Sin conflicto entre AGENTS.md, CLAUDE.md y .cursor/rules.
• Tras el segundo error repetido del agente, actualiza el archivo (no el chat).
• Procedimientos largos movidos a skills, no inflar el markdown.
• CI referenciada (.github/workflows/) para que el agente sepa qué debe pasar.

FAQ

¿El agente ejecuta los tests de AGENTS.md solo?
agents.md indica que sí intentará correr checks listados y corregir fallos antes de terminar. No es garantía: conviene hooks de pre-commit y CI.

¿Puedo tener AGENTS.md y CLAUDE.md distintos?
Sí, pero alinea lo crítico (comandos, ramas protegidas). Usa imports o un solo archivo maestro.

¿Reemplaza AGENTS.md al sandboxing?
No. Las reglas de texto no bloquean tools. Para permisos duros usa sandboxing y permisos o hooks.

¿Y Codex en CI?
OpenAI documenta AGENTS.md en la configuración del agente (docs). El mismo archivo que el IDE reduce sorpresas entre local y pipeline.

---

Siguiente paso: commitea un AGENTS.md de una pantalla, enlázalo desde tu README (“para agentes de código, lee AGENTS.md”) y recorre el curso gratis si aún no tienes un agente desplegado.