AGENTS.md: dónde vive cada regla de tu agente de IA

Abres una sesión nueva. Le pides al agente un endpoint. Te lo escribe con let, con comillas dobles, sin test, y de paso te toca el fichero de migraciones que llevas tres meses pidiendo que nadie toque.

Y tú tienes un AGENTS.md de 180 líneas donde pone exactamente lo contrario.

La reacción natural es abrir el fichero y añadir una línea más. En mayúsculas. Con tres signos de exclamación. La reacción natural es casi siempre la equivocada, porque el problema rara vez es que la regla no esté escrita. El problema es que está escrita en la capa que no era.

Hay tres sitios donde puede vivir una instrucción y cada uno tiene una vida útil distinta. Confundirlos es lo que produce esa sensación de estar repitiéndote a una máquina que cobra por token.

Esto es lo que vas a encontrar aquí:

• La diferencia real entre un prompt, una regla y el contexto, y por qué mezclarlos te hace escribir ficheros que nadie lee
• La anatomía de un AGENTS.md que funciona y la autopsia de uno que estorba
• Dónde busca las reglas cada agente (Claude Code, Codex, Cursor, Copilot, OpenCode) y quién gana cuando dos se contradicen
• Qué sobrevive a una compactación y qué se evapora
• Un protocolo de auditoría de diez minutos para el fichero que ya tienes
• Tres plantillas copiables según el tipo de proyecto

¿Por qué tu agente se olvida de tus convenciones en cada sesión? ¶

Porque no se olvida. Nunca lo supo.

Cada sesión de un agente de código arranca con la ventana de contexto vacía. Lo dice la documentación de Claude Code sin rodeos: “cada sesión de Claude Code empieza con una ventana de contexto nueva”. No hay continuidad. No hay un cerebro que recuerde la bronca de ayer. Lo único que cruza de una sesión a la siguiente es lo que está escrito en disco y se vuelve a cargar al arrancar.

Así que cuando dices “se le olvida”, lo que está pasando es una de estas cuatro cosas:

1. La instrucción la diste en el chat de la sesión anterior y murió con ella.
2. La escribiste en un fichero que ese agente concreto no lee (le pusiste AGENTS.md a Claude Code, por ejemplo).
3. Está en un fichero que sí lee, pero enterrada entre otras 4.000 palabras que compiten por su atención.
4. Está escrita como deseo (“mantén el código limpio”) y no como algo verificable (“usa indentación de 2 espacios”).

Ninguno de esos cuatro casos se arregla escribiendo más. Tres de ellos se arreglan moviendo de sitio lo que ya escribiste.

🔑 Tu agente no tiene memoria. Tiene ficheros. Si una convención no está en un fichero que se carga al arrancar, esa convención no existe.

¿Qué diferencia hay entre un prompt, una regla y el contexto? ¶

Son tres cosas distintas con tres vidas útiles distintas, y todo el mundo las llama “contexto” de forma indistinta. Ese es el origen del lío.

La forma rápida de separarlas es preguntarte cuánto tiempo vive cada una:

El prompt es la tarea. “Añade paginación al listado de usuarios.” Vive un turno y se convierte en historial.

La regla es lo que sigue siendo verdad mañana. “Los precios van en céntimos, siempre.” No depende de la tarea. Si tienes que repetirla, es una regla mal colocada.

El contexto es lo que el agente ha ido metiendo en la ventana mientras trabaja: los ficheros que ha leído, la salida de los tests, tu conversación entera. Es lo único de los tres que crece solo y lo único que puedes gestionar durante la sesión.

Aquí hay un detalle técnico que se repite mal en muchos sitios, incluido un post anterior de esta misma casa. Se suele decir que el AGENTS.md entra en el system prompt del agente. La documentación oficial de Claude Code dice otra cosa: “el contenido de CLAUDE.md se entrega como un mensaje de usuario después del system prompt, no como parte del system prompt”.

No es una sutileza de manual. Tiene una consecuencia práctica que explica el 80% de las frustraciones: una regla no es una configuración, es una sugerencia muy bien colocada. El agente la lee y trata de seguirla, pero no hay garantía de cumplimiento estricto. Si necesitas que algo se cumpla sí o sí, no lo escribas en un markdown: escribe un hook. Los hooks se ejecutan como comandos de shell en momentos fijos del ciclo de vida y se aplican decida lo que decida el modelo.

⚠️ Una regla en AGENTS.md orienta. Un hook obliga. Si llevas tres iteraciones peleando con una regla que el agente ignora, seguramente no era una regla.

Guía interactiva gratis

El fichero de instrucciones tiene su propia parada en el curso

Si esto de las tres capas te ha pillado a mitad de camino, la parada 11 del curso va justo de esto (agents.md, CLAUDE.md, /init) y la 10 de la ventana de contexto, que es donde se marca la diferencia. Son 17 paradas, eliges tú el camino y sales con una checklist a medida.

Entra en el curso gratis →

¿Qué lleva dentro un AGENTS.md que de verdad sirve? ¶

Lleva lo que el agente no puede deducir leyendo tu repositorio. Ese es el filtro entero, y es más exigente de lo que parece.

El formato AGENTS.md es un markdown normal sin estructura obligatoria, mantenido como especificación abierta bajo la Agentic AI Foundation de la Linux Foundation, y presente ya en más de 60.000 repositorios públicos de GitHub según los recuentos de mediados de 2026. No hay campos reservados ni frontmatter que memorizar: son encabezados y listas.

Lo que sí hay es un consenso bastante sólido sobre qué merece entrar:

Comandos de setup, build y test. Lo primero que un agente intenta adivinar y lo primero en lo que falla. Si tu proyecto usa pnpm y no npm, si los tests necesitan un Redis local levantado, si hay un make dev que hace tres cosas a la vez: eso va aquí. Es información barata de escribir y cara de descubrir.

Convenciones que se apartan del default de la herramienta. No escribas “usamos TypeScript” (lo ve en el tsconfig.json). Escribe “los tipos generados van en src/types/generated/ y no se editan a mano, se regeneran con pnpm types”. Lo primero es ruido. Lo segundo evita un desastre.

Decisiones de producto que el código no explica. Por qué los importes van en céntimos. Por qué hay dos sistemas de auth conviviendo. Por qué ese módulo feo sigue ahí. Esto es conocimiento tribal: lo que un compañero nuevo no sabría sin que alguien se lo cuente. Es, con diferencia, lo más valioso que puedes meter.

Qué no tocar. La sección que más gente se salta y la que más disgustos evita. Migraciones aplicadas, ficheros generados, el directorio vendor/, la rama main.

Un esqueleto que funciona ocupa esto:

# AGENTS.md

## Setup
- Instala con `pnpm install` (npm rompe el lockfile)
- Los tests de integración necesitan `docker compose up -d db` antes

## Comandos
- `pnpm dev` — servidor local en :3000
- `pnpm test` — unitarios (rápido, úsalo siempre antes de commitear)
- `pnpm test:e2e` — Playwright, tarda ~4 min, solo antes de abrir PR

## Convenciones no obvias
- Los importes se guardan en céntimos (enteros), nunca en decimales
- Los tipos de `src/types/generated/` se regeneran con `pnpm types`, no se editan
- Fechas siempre en UTC en la base de datos, se convierten en la capa de vista

## No tocar
- `migrations/` — las migraciones aplicadas no se editan, se añade una nueva
- `src/legacy/billing/` — sistema antiguo en congelación, hay un plan de retirada

Eso son 20 líneas. Cabe de sobra en el presupuesto que recomiendan las dos herramientas más usadas: Claude Code sugiere menos de 200 líneas por fichero y avisa de que los ficheros más largos consumen más contexto y reducen la adherencia; Codex corta directamente al superar project_doc_max_bytes, que por defecto son 32 KB.

Fíjate en la palabra “adherencia”. No es que el agente no pueda leer 500 líneas. Es que cuanto más le escribes, menos caso te hace a cada línea.

¿Cómo se ve un AGENTS.md que estorba? ¶

Se ve como el que genera /init y nadie revisa.

El estudio de la ETH de Zúrich que analizamos en el post sobre AGENTS.md y /init puso número a esto: los ficheros de contexto generados por IA redujeron la tasa de éxito un 3% de media, mientras que los escritos por humanos la mejoraron un 4%. En ambos casos el coste de inferencia subió más de un 20%. No repito aquí el debate (está entero allí), pero sí me interesa la autopsia: qué tiene dentro un fichero que hace daño.

Estos son los seis síntomas, por orden de frecuencia:

1. Describe el árbol de directorios. Un mapa de carpetas que el agente reconstruye con un ls en dos segundos, ocupando 40 líneas de tu presupuesto en todas y cada una de las sesiones. La utilidad de /doctor en Claude Code hace exactamente este recorte: elimina lo que se puede derivar del propio código (layouts de directorios, listas de dependencias, resúmenes de arquitectura) y conserva las trampas, el porqué y las convenciones que se apartan del default.

2. Lista las dependencias. Están en el package.json. Con versiones. Que además se quedan obsoletas en tu markdown y no en el lockfile, así que además de inútil, miente.

3. Repite lo que el modelo ya sabe. “Escribe código legible.” “Sigue los principios SOLID.” “Usa nombres descriptivos para las variables.” Eso no es contexto de tu proyecto, es relleno motivacional. El modelo viene con eso de fábrica.

4. Se contradice consigo mismo. Es el más silencioso y el más dañino. La documentación de Claude Code lo dice con claridad: “si dos reglas se contradicen, Claude puede elegir una de forma arbitraria”. Y en un fichero que ha ido creciendo a base de parches durante ocho meses, las contradicciones son la norma, no la excepción. La línea 30 dice “no añadas comentarios”, la 140 dice “documenta cada función pública”.

5. Mete procedimientos de varios pasos. Si algo es un flujo de trabajo largo que solo aplica de vez en cuando, no es una regla: es una skill, que se carga bajo demanda y no te cuesta contexto el resto del tiempo.

6. Grita. MAYÚSCULAS, negritas, “IMPORTANTE”, “NUNCA JAMÁS”. Cuando todo está enfatizado, nada lo está. Y si de verdad ese comportamiento es innegociable, ya sabes: hook.

La prueba del algodón es sencilla. Coge tu fichero, ve línea por línea y pregúntate: ¿podría el agente averiguar esto solo, leyendo el repo, en menos de treinta segundos? Si la respuesta es sí, esa línea te está costando dinero en cada sesión a cambio de nada.

¿Dónde vive cada regla según el agente que uses? ¶

Aquí es donde se ponen interesantes las cosas, porque cada herramienta busca en sitios distintos y resuelve los conflictos con reglas distintas. Y casi nadie lo mira hasta que algo no funciona.

La división básica que existe en todas es la misma: reglas globales (tuyas, en tu $HOME, para todos tus proyectos, no van a git) y reglas de proyecto (del equipo, en el repo, sí van a git). Lo que cambia es dónde y quién gana.

Hay dos detalles de esta tabla que merecen que te pares.

El primero: Claude Code no lee AGENTS.md. Ni uno solo de los recopilatorios que circulan por ahí lo cuenta bien, y la documentación oficial no puede ser más explícita: “Claude Code lee CLAUDE.md, no AGENTS.md”. La solución recomendada no es duplicar el fichero (garantía de divergencia en tres semanas), sino importarlo:

@AGENTS.md

## Claude Code

Usa modo plan para los cambios bajo `src/billing/`.

O un symlink, si no necesitas añadir nada específico de Claude:

ln -s AGENTS.md CLAUDE.md

En Windows el symlink pide permisos de administrador o el modo desarrollador, así que ahí la importación con @ es la vía práctica. Y si vienes de Copilot con instrucciones repartidas por medio repo, el camino completo lo tienes en cómo migrar las instrucciones de GitHub Copilot.

El segundo: no todos “sobrescriben” igual. Y esta es la que rompe la intuición de la gente que viene de ficheros de configuración.

En Claude Code, todos los ficheros encontrados se concatenan, no se sobrescriben. Sube por el árbol de directorios desde donde lanzaste la sesión y va apilando: primero la política gestionada de la organización, luego tus reglas de usuario, luego las del proyecto, y dentro de cada directorio el CLAUDE.local.md al final. Lo que está más cerca de tu directorio de trabajo se lee el último. No hay un ganador declarado: hay un orden de lectura, y el modelo hace lo que puede con lo que le llega.

En Codex el resultado práctico se parece pero la mecánica es explícita: concatena desde la raíz hacia abajo, incluye como mucho un fichero por directorio, y “los ficheros posteriores prevalecen sobre los anteriores porque aparecen los últimos en el prompt combinado”. Traducido: la carpeta más específica manda.

La consecuencia operativa es la misma en las dos: si tu regla global y la del proyecto se contradicen, no estás configurando nada, estás metiendo ruido en el prompt. Las reglas globales tienen que ser preferencias que no chocan con ningún proyecto (“responde en español”, “no me pidas confirmación para leer ficheros”). En cuanto una regla global empieza a hablar de cómo se escribe el código, ya está invadiendo terreno del equipo.

💡 Regla práctica: en tu fichero global solo van cosas sobre cómo quieres que te hable el agente. Todo lo que sea sobre cómo se escribe el código va al repositorio, donde tu equipo puede verlo y discutirlo.

¿Qué sobrevive a una compactación y qué se pierde? ¶

Esta pregunta separa a quien ha leído la documentación de quien va probando.

Cuando la ventana se llena y el agente compacta, no todo se trata igual. En Claude Code, el CLAUDE.md de la raíz del proyecto sobrevive: tras el /compact, se relee de disco y se vuelve a inyectar en la sesión. Los CLAUDE.md anidados en subdirectorios no se reinyectan de forma automática; vuelven a cargarse la próxima vez que el agente lea un fichero de esa carpeta.

Y todo lo que le dijiste solo por el chat se resume, con la pérdida que eso implica.

Ahí tienes el diagnóstico exacto de la sensación con la que empezaba este post. Si una instrucción desapareció después de una compactación, o la diste solo en conversación, o vive en un fichero anidado que todavía no ha vuelto a cargarse. No es amnesia. Es arquitectura.

Esto también te da un criterio para decidir dónde poner una regla en un monorepo. Lo que tenga que estar presente en toda la sesión pase lo que pase va en el fichero raíz. Lo que solo importe cuando se toca packages/payments/ va en un fichero anidado ahí, y aceptas que solo estará cargado cuando el agente ande por esa zona. Que es justo lo que quieres. Si te interesa el fenómeno de fondo, lo desarrollamos entero en qué es el context rot.

¿Cómo se cura el contexto durante la sesión? ¶

Curar el contexto es decidir tres cosas: qué le das, qué le quitas y cuándo cortas por lo sano.

Qué le das. Menos de lo que crees. La tentación de empezar la sesión volcándole seis ficheros “por si acaso” es la vía rápida a un agente distraído. Dale la tarea y deja que él pida lo que necesite: los agentes modernos son buenos buscando. Lo que sí conviene darle explícito es el punto de partida (“el bug está entre src/api/orders.ts y el middleware de auth”) para que no se recorra medio repo antes de empezar.

Qué le quitas. Aquí es donde las reglas por ruta se ganan el sueldo. En lugar de un fichero monolítico que se carga siempre, Claude Code permite trocear en .claude/rules/ y marcar cada trozo con las rutas a las que aplica:

---
paths:
  - "src/api/**/*.ts"
---

# Reglas de la API

- Todos los endpoints validan la entrada con Zod antes de tocar la base de datos
- Los errores usan el formato estándar de `src/api/errors.ts`
- Cada endpoint nuevo lleva su bloque de OpenAPI

Ese fichero no ocupa nada hasta que el agente lee algo bajo src/api/. Conviene no confundir esto con seguridad: condicionar por rutas decide qué reglas se cargan, no qué ficheros puede abrir el agente. Para eso están las reglas de permisos, que es otra conversación distinta y bastante más seria. Copilot tiene su equivalente con applyTo en .github/instructions/, y Cursor con globs en el frontmatter de sus reglas. Es el mismo movimiento en las tres: pasar de “siempre cargado” a “cargado cuando toca”.

Un truco menos conocido: en Claude Code, los comentarios HTML de bloque (<!-- nota para humanos -->) se eliminan antes de inyectar el fichero en el contexto. Puedes dejar notas para tu equipo dentro del CLAUDE.md sin pagar tokens por ellas.

Cuándo compactas. Antes de que lo haga solo, y en una frontera limpia. El peor momento para compactar es a mitad de una tarea compleja, porque el resumen se lleva por delante los matices que estabas construyendo. El mejor es cuando acabas de cerrar algo: el test pasa, el commit está hecho, y lo siguiente es un tema distinto. Ahí compactas o directamente abres sesión nueva, que sale más barato y más limpio.

Y ojo con una trampa: partir el AGENTS.md en imports con @ organiza pero no ahorra. La documentación lo dice sin ambigüedad: los ficheros importados se expanden y se cargan en el contexto al arrancar, igual que si estuvieran pegados. Si quieres ahorrar de verdad, el mecanismo es el condicionamiento por rutas, no la importación. (Por si acaso: la profundidad máxima de importaciones encadenadas es de cuatro saltos.)

Domina la herramienta a fondo

Cuando la regla ya no basta y toca bajar a los hooks

Todo este post se apoya en una frontera: lo que orienta va en markdown, lo que obliga va en un hook. En esta masterclass de dos horas y media se cruza esa frontera con las manos: CLAUDE.md, hooks, agentes, MCP y workflows reales, con el contexto que la documentación oficial no termina de explicar bien.

Ver la masterclass entera →

Masterclass en directo · 2h30 · Acceso con Web Reactiva Premium

¿Cómo auditar tu propio fichero de reglas en diez minutos? ¶

Vamos a lo práctico. Abre tu AGENTS.md o tu CLAUDE.md y pásale estos siete controles. Puedes hacerlo a mano o pedírselo al propio agente, pero hazlo con el fichero delante.

1. Cuenta las líneas. wc -l AGENTS.md. Si pasa de 200, tienes trabajo. No es un límite sagrado, es el umbral a partir del cual la propia herramienta te avisa de que la adherencia empieza a caer.

2. Comprueba qué se ha cargado de verdad. Este control descarta la mitad de los problemas de un plumazo y casi nadie lo ejecuta. En Claude Code, /context lista los ficheros de memoria que están efectivamente en la sesión. Si tu fichero no aparece ahí, deja de reescribirlo: el agente no lo está viendo. Para depuración fina existe el hook InstructionsLoaded, que registra qué ficheros de instrucciones se cargan, cuándo y por qué.

3. Marca lo derivable. Recorre línea a línea con la pregunta de antes: ¿esto lo averigua solo en treinta segundos? Todo lo que sea sí (árboles de directorios, dependencias, versiones, resúmenes de arquitectura) se va fuera. En Claude Code, /doctor propone este recorte automático desde la versión 2.1.206.

4. Busca contradicciones. Es lo más difícil de ver a ojo porque tu fichero lo escribiste tú, en trozos, a lo largo de meses. Pídeselo al agente en frío: “lee este fichero y dime qué pares de instrucciones se contradicen o se solapan”. Y recuerda revisar también los anidados y los globales: la contradicción puede estar entre tu ~/.claude/CLAUDE.md y el del repo.

5. Reclasifica lo que no es una regla. Los procedimientos de varios pasos van a skills. Lo innegociable va a hooks. Lo que solo aplica a una carpeta va a un fichero por rutas. Lo que quede después de esos tres filtros es tu AGENTS.md de verdad.

6. Convierte los deseos en comprobables. “Escribe tests” no se puede verificar. “Ejecuta pnpm test antes de commitear y no abras PR con tests en rojo” sí. La documentación oficial insiste en esto con ejemplos casi idénticos: específico gana a bonito.

7. Prueba el recorte. La metodología que mejor funciona es la inversa a la que usa todo el mundo: en vez de añadir cuando algo falla, quita y comprueba. Recorta un bloque, repite una tarea que antes salía bien y mira si sigue saliendo bien. Si sale, el bloque sobraba. Es lento, pero es el único método que produce ficheros pequeños de verdad.

Si prefieres delegar el trabajo pesado, en el catálogo de skills tienes agent-md-refactor, que aplica progressive disclosure a ficheros AGENTS.md, CLAUDE.md o COPILOT.md en cinco fases (analizar, extraer, categorizar, estructurar, podar) y saca una jerarquía con un fichero raíz ligero y referencias enlazadas. No sustituye tu criterio, pero te ahorra la primera pasada.

🛡️ Antes de tocar nada, haz commit del fichero actual. Vas a querer comparar y a lo mejor vas a querer volver.

Tres plantillas copiables según tu tipo de proyecto ¶

Las reglas cambian mucho según la forma del proyecto. Estas tres cubren la mayoría de casos.

Aplicación de producto con un equipo detrás ¶

El caso más común. Aquí lo caro es el conocimiento tribal: las decisiones que se tomaron hace dos años y que nadie ha documentado.

# AGENTS.md

## Setup
- `pnpm install` && `docker compose up -d` (postgres + redis)
- Copia `.env.example` a `.env`; las claves de staging están en 1Password

## Comandos
- `pnpm dev` · `pnpm test` (antes de cada commit) · `pnpm test:e2e` (antes del PR)
- `pnpm db:migrate` para aplicar migraciones; nunca edites una ya aplicada

## Decisiones que el código no explica
- Los importes van en céntimos (enteros). Nunca float.
- Conviven dos sistemas de auth: el nuevo en `src/auth/`, el antiguo en
  `src/legacy/auth/`. Todo lo nuevo usa el nuevo.
- Las fechas se guardan en UTC y se convierten en la capa de vista.

## No tocar
- `migrations/` aplicadas · `src/types/generated/` (usa `pnpm types`)
- La rama `main` — todo pasa por PR

Librería open source ¶

Aquí lo que importa es la superficie pública y la compatibilidad. Un cambio inocente rompe a gente que no conoces.

# AGENTS.md

## Setup
- `pnpm install` · Node 20+ · sin dependencias de runtime, es intencionado

## Comandos
- `pnpm test` (vitest) · `pnpm build` (tsup) · `pnpm size` (limita el bundle)

## Reglas de API pública
- Cualquier cambio en `src/index.ts` es breaking hasta que se demuestre
  lo contrario. Si no estás seguro, pregunta antes de escribir.
- Nada de dependencias nuevas sin discutirlo: el bundle está en 8 KB
  y `pnpm size` falla si lo superamos.
- Cada cambio de comportamiento lleva su entrada en `CHANGELOG.md`
  con formato Keep a Changelog.

## No tocar
- `dist/` · `docs/api/` (se genera desde los tipos)

Monorepo ¶

El único de los tres donde la clave no es qué escribes, sino dónde. Fichero raíz mínimo y ficheros anidados por paquete.

# AGENTS.md (raíz)

## Setup
- `pnpm install` en la raíz instala todos los workspaces
- `pnpm --filter <paquete> <comando>` para trabajar en uno solo

## Reglas de todo el monorepo
- Los paquetes no se importan por ruta relativa entre sí, siempre por nombre
- Los cambios que tocan más de un paquete llevan changeset (`pnpm changeset`)

## Dónde está el contexto específico
Cada paquete tiene su propio AGENTS.md con sus reglas. Léelo antes de tocar
nada dentro de `packages/`.

Y dentro de cada paquete, un fichero de diez líneas con lo suyo. Recuerda lo de la compactación: el anidado no se reinyecta solo, así que en el raíz merece la pena dejar escrito que existen y que hay que leerlos.

Si trabajas con OpenCode, la mecánica de reglas y la configuración concreta las tienes desarrolladas en la guía de OpenCode. Y si quieres ver dónde encaja AGENTS.md dentro del panorama completo de estándares, está en el repaso de protocolos de IA junto a MCP, ACP, A2A y compañía.

Escribir un buen fichero de reglas no es un ejercicio de documentación. Es un ejercicio de recorte. La versión buena de tu AGENTS.md es la que queda después de quitar todo lo que el agente ya sabía.

Ahora abre el tuyo y cuenta las líneas. ¿Cuántas de esas sobreviven a las siete preguntas?

Preguntas frecuentes ¶

¿Qué es AGENTS.md? ¶

Es un fichero markdown en la raíz de un repositorio con las instrucciones que un agente de código lee al empezar una sesión: comandos de setup, convenciones del proyecto y decisiones que no se deducen del código. Es una especificación abierta mantenida bajo la Agentic AI Foundation de la Linux Foundation y está presente en más de 60.000 repositorios públicos de GitHub.

¿Cuál es la diferencia entre AGENTS.md y CLAUDE.md? ¶

El contenido es el mismo tipo de cosa; cambia qué herramienta lo lee. AGENTS.md es el formato común que soportan Codex, Cursor, Copilot, OpenCode y otros. Claude Code lee CLAUDE.md y no AGENTS.md, así que la práctica recomendada es tener el AGENTS.md como fuente única e importarlo desde CLAUDE.md con @AGENTS.md, o crear un symlink.

¿Cuánto debe ocupar un AGENTS.md? ¶

La documentación de Claude Code recomienda menos de 200 líneas por fichero y avisa de que los más largos consumen más contexto y reducen la adherencia a las instrucciones. Codex corta el contenido al superar project_doc_max_bytes, 32 KB por defecto. En la práctica, un fichero útil suele quedarse entre 30 y 100 líneas.

¿Por qué el agente ignora las reglas de mi AGENTS.md? ¶

Por cuatro motivos habituales: el fichero no se está cargando (compruébalo con /context en Claude Code), la herramienta que usas no lee ese nombre de fichero, la instrucción es demasiado vaga para verificarla, o hay dos reglas que se contradicen y el modelo elige una de forma arbitraria. Además, una regla en markdown orienta pero no obliga: si necesitas cumplimiento estricto, usa un hook.

¿Dónde van las reglas globales y dónde las del proyecto? ¶

Las globales van en tu directorio personal (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.config/opencode/AGENTS.md) y no se comparten con nadie. Las del proyecto van en el repositorio y sí se versionan. El criterio práctico: en las globales solo va cómo quieres que el agente te hable; todo lo que sea cómo se escribe el código va al repositorio.

¿Qué pasa si mi regla global y la del proyecto se contradicen? ¶

En Claude Code todos los ficheros se concatenan en orden, desde el más general al más cercano a tu directorio de trabajo, sin que ninguno anule al otro. En Codex también se concatenan desde la raíz hacia abajo, y los ficheros más específicos prevalecen por aparecer los últimos. En ambos casos, dos reglas contradictorias no configuran nada: solo añaden ruido.

¿Sirve de algo ejecutar /init para generar el fichero? ¶

Como punto de partida sí, como versión final no. El estudio de la ETH de Zúrich midió que los ficheros de contexto generados por IA reducen la tasa de éxito un 3% de media mientras suben el coste de inferencia más de un 20%. El valor aparece al revisarlo a mano y quitar todo lo que el agente puede deducir solo del repositorio.

¿Cómo evito que el fichero se cargue entero en cada sesión? ¶

Con reglas condicionadas por rutas, no con imports. En Claude Code se hace con ficheros en .claude/rules/ y el campo paths: en el frontmatter; en Copilot con applyTo en .github/instructions/; en Cursor con globs. Los imports con @ organizan el contenido pero se expanden y cargan al arrancar igual, así que no ahorran contexto.

¿Las instrucciones sobreviven a un /compact? ¶

El CLAUDE.md de la raíz del proyecto sí: tras compactar se relee de disco y se reinyecta en la sesión. Los ficheros anidados en subdirectorios no se reinyectan de forma automática, sino que vuelven a cargarse cuando el agente lee algún fichero de esa carpeta. Lo que diste solo por chat se resume y pierde detalle.

¿Cuándo debería usar una skill en lugar de una regla? ¶

Cuando es un procedimiento de varios pasos que solo aplica de vez en cuando. Una regla se carga en todas las sesiones y cuesta contexto siempre; una skill se carga bajo demanda, cuando la invocas o cuando el agente detecta que viene al caso. Convenciones y comandos van al fichero de reglas; flujos de trabajo largos, a skills.

Fuentes ¶

• Claude Code Docs, “How Claude remembers your project”
• OpenAI Developers, “Custom instructions with AGENTS.md” (Codex)
• AGENTS.md, especificación abierta
• Cursor Docs, “Rules”
• GitHub Docs, “Adding repository custom instructions for GitHub Copilot”
• OpenCode Docs, “Rules”
• Gloaguen, T. et al., “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?” ETH Zürich

🧨 Última oportunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter