Nivel avanzado18 min de lectura · Revisado el 14 de noviembre de 2026

AGENTS.md y CLAUDE.md: qué son, diferencias y qué poner

Un agente de código empieza cada sesión sin recordar nada del proyecto. No sabe con qué comando se pasan los tests, qué carpeta no debe tocar ni por qué un campo de la API no se puede renombrar. Lo que no encuentre en el código lo tiene que leer en sus instrucciones, y si no está, lo adivina. AGENTS.md es el formato abierto que leen casi todos los agentes; CLAUDE.md, el fichero propio de Claude Code, que por defecto ignora AGENTS.md si existen los dos. Este artículo explica qué poner en esas instrucciones y qué no. Forma parte de la IA Limpia, el enfoque de esta web: IA que corre, código que dura.

La idea principal es esta: las instrucciones de un agente se tratan como código, aunque no se ejecutan como él: se versionan, se revisan, se quedan viejas y pueden tener errores. Por eso conviene que sean cortas, que cada regla tenga un motivo que se pueda comprobar y que lo que no se negocia no dependa de que el agente lo lea y lo cumpla, sino de una comprobación automática. Es el principio «La responsabilidad sigue siendo tuya» del método IA Limpia: el agente ejecuta, pero las reglas del proyecto las pones y las haces cumplir tú. En una frase: lo que se escribe, el agente lo tiene en cuenta; lo que importa, lo comprueba una máquina.

La nota para quien cuida tu casa

Si te vas de viaje y alguien se queda cuidando tu casa, le dejas una nota. No le explicas cómo se abre un grifo; eso ya lo sabe. Le escribes lo que no puede adivinar: «la llave del gas está detrás de la lavadora», «el perro come a las ocho», «no abras la puerta del patio, que se escapa».

Una buena nota es corta, concreta y explica lo que no se ve a simple vista. Pero lo que no puede fallar no lo confías a la nota: el armario de los papeles importantes lo cierras y te llevas la llave. Si quien cuida tu casa no lee la nota, el perro cena tarde; el armario sigue cerrado la lea o no.

Con un agente pasa lo mismo. AGENTS.md y CLAUDE.md son la nota. Los permisos, los hooks y los tests son la cerradura. El símil se queda corto en dos cosas. La nota de tu casa la lee una persona que razona igual que tú; el agente la lee entera en cada sesión, junto a todo lo demás que tiene en contexto, y cuanto más larga es, peor la sigue. Y la cerradura tiene sus límites: un permiso bloquea una forma de escribir un comando, no todas, como se ve más abajo.

Qué son AGENTS.md y CLAUDE.md y en qué se diferencian

• AGENTS.md es un formato abierto: un fichero Markdown en la raíz del repositorio, sin campos obligatorios, que su web describe como «un README para agentes». Lo mantiene la Agentic AI Foundation, dentro de la Linux Foundation, y lo leen muchas herramientas: Codex, Cursor, GitHub Copilot, Gemini CLI, Jules o Aider, entre otras (algunas, como Aider y Gemini CLI, necesitan una línea de configuración para leerlo). En un repositorio con varios proyectos puede haber uno por carpeta, y según el formato manda el más cercano al fichero que se edita.
• CLAUDE.md es el fichero de instrucciones de Claude Code. Funciona igual, pero con algo más: se puede poner en varios sitios (uno para todos tus proyectos, uno por proyecto y otro personal que no se sube) y puede importar otros ficheros con @ruta. Claude Code también expande esas importaciones dentro de un AGENTS.md, pero otras herramientas no las entienden. Y no sustituye un fichero por otro: suma todos los que encuentra, del más general al más cercano. Por qué el agente necesita estos ficheros se entiende mejor sabiendo cómo funciona un agente de IA para programar.

¿Claude Code lee AGENTS.md?

Sí, pero solo si no hay ningún CLAUDE.md ni CLAUDE.local.md en la carpeta de trabajo o por encima (desde la versión 2.1.277). Si hay los dos y no lo importas, por defecto AGENTS.md se ignora; basta un CLAUDE.local.md personal para que deje de leerse. Se puede cambiar en /config con el ajuste Project instructions (por ejemplo, al valor claude-md-and-agents-md), pero Claude Code lo ignora en la configuración del proyecto: solo vale en la de cada usuario o en la gestionada por la organización. Para un equipo, lo fiable es importarlo (comprobado con Claude Code 2.1.325).

Cómo usar AGENTS.md y CLAUDE.md a la vez

Si trabajas solo con Claude Code, basta con CLAUDE.md. Si en el equipo se usan varios agentes, lo práctico es escribir lo común una sola vez en AGENTS.md y que CLAUDE.md lo importe con una línea, @AGENTS.md, y añada debajo solo lo propio de Claude Code:

@AGENTS.md

## Solo para Claude Code

- Para crear una migración de base de datos, usa la skill `nueva-migracion`.

Los ejemplos de este artículo usan Claude Code porque documenta con detalle cada mecanismo; los principios valen para cualquier agente.

Qué poner en AGENTS.md y CLAUDE.md

La documentación de Claude Code lo resume en una frase: hechos que el agente debe tener en todas las sesiones, como los comandos de build, las convenciones, la estructura del proyecto y las reglas de «haz siempre X». En la práctica:

1. Los comandos que no se deducen. Cuáles hay que pasar antes de dar algo por terminado y en qué orden, y los que llevan opciones o variables que no están a la vista (por ejemplo, una variable que hay que poner para que los tests no envíen correos de verdad). Un agente que no sabe qué comando ejecutar lo inventa o se salta el paso.
2. Convenciones que se pueden comprobar. La documentación da ejemplos claros: «usa dos espacios de sangría» en lugar de «formatea bien el código»; «ejecuta npm test antes de hacer commit» en lugar de «prueba tus cambios». Si no puedes comprobar si el agente la ha cumplido, lo más probable es que esté mal escrita.
3. Dónde está cada cosa. Qué carpeta tiene el dominio, dónde están las decisiones de arquitectura, qué documento hay que leer antes de tocar algo. Basta una línea por cosa; el agente lee el documento cuando lo necesita.
4. Las reglas que no se negocian, con su motivo. «No renombres campos de la respuesta de /pedidos» se sigue mejor con su porqué: «la usan apps móviles ya publicadas, que no se actualizan a la vez». El motivo le sirve al agente para los casos que la regla no prevé, y te sirve a ti para saber, dentro de un año, si la regla sigue haciendo falta. Un ejemplo de instrucciones y lista de tests en un fichero, aplicado a una kata, está en TDD con IA y la kata Mars Rover.

Un ejemplo de AGENTS.md para un proyecto inventado, la API de una tienda online, con todo lo anterior en unas veinte líneas:

# API de pedidos

API REST de la tienda. La usan la web y las apps móviles ya publicadas.

## Comandos

- `npm test`: tests unitarios y de contrato. Pon `EMAIL_FALSO=1` para que no salgan correos.
- `npm run check`: tipos y lint. Pásalo, con los tests, antes de dar algo por terminado.

## Dónde está cada cosa

- `src/dominio/`: reglas de negocio. No importa nada de `src/infra/`.
- `doc/adr/`: decisiones de arquitectura. Lee la que toque antes de cambiar algo de ese tema.

## Reglas

1. No renombres ni quites campos de la respuesta de `/pedidos`: la usan apps
   móviles ya publicadas. Lo comprueba `test/contrato-pedidos.test.ts`.
2. Los importes van en céntimos, como enteros. Con decimales se pierden céntimos al redondear.
3. No subas `.env` ni claves. Un hook bloquea el commit que lo lleve.

Cada regla lleva su motivo y, cuando la hay, la comprobación que la respalda.

Qué no poner, y dónde va en su lugar

• Lo que el agente ya ve en el código. Si el package.json dice que el proyecto usa TypeScript, no hace falta repetirlo. Cada línea se lee en todas las sesiones y ocupa contexto.
• Procedimientos largos. «Para publicar un artículo, primero…, después…» no tiene que estar en cada sesión. En Claude Code va en una skill: en cada sesión solo está su descripción, y el procedimiento completo se carga cuando se usa.
• Lo que solo importa en una parte del proyecto. Las normas para escribir artículos no hacen falta cuando se toca el CSS. En Claude Code van en .claude/rules/, con un campo paths que indica a qué ficheros se aplican; la regla se carga cuando el agente lee o edita uno de ellos.
• Instrucciones vagas. «Escribe código limpio» no cambia nada: el agente ya cree que lo hace.
• Instrucciones que se contradicen. La documentación avisa de que, si dos se contradicen, el agente puede elegir cualquiera de las dos.
• Secretos. El fichero se sube al repositorio y lo lee todo el equipo.
• Lo que no puede fallar nunca. Esto merece su propio apartado.

Sobre el tamaño, la documentación de Claude Code recomienda menos de 200 líneas por fichero, porque los largos ocupan más contexto y se siguen peor. Y aclara un detalle que se olvida a menudo: importar otros ficheros con @ruta ayuda a ordenar, pero no ahorra contexto, porque lo importado se carga entero junto al fichero que lo importa.

Instrucciones, permisos, hooks y tests: de más suave a más firme

La documentación de Claude Code es clara en esto: trata los CLAUDE.md «como contexto, no como configuración obligatoria». Es decir, el agente los tiene en cuenta, pero nada garantiza que cumpla cada línea. Para bloquear una acción decida lo que decida el agente, remite a los hooks.

Por eso, cada regla importante debería tener detrás una comprobación. De más suave a más firme (las dos primeras filas son instrucciones; la segunda solo cambia cuándo se cargan):

Las dos primeras filas dependen de que el agente lea y obedezca. Las cuatro últimas, no, aunque cada una tiene sus límites, que están al final del artículo. Los permisos se configuran en .claude/settings.json; para la API de pedidos podrían ser estos:

{
  "permissions": {
    "ask": ["Bash(git push *)", "Bash(npm publish *)"],
    "deny": [
      "Read(./.env)",
      "Bash(git push --force *)",
      "Bash(git push -f *)",
      "Bash(git reset --hard *)"
    ]
  }
}

Claude Code evalúa primero las reglas deny, después ask y después allow, y gana la primera que coincide. Una regla allow más concreta no abre una excepción en una deny más general.

Un hook que bloquea un commit con secretos

Un hook es un comando que Claude Code ejecuta en momentos concretos; su documentación dice que da «control determinista»: la acción ocurre siempre, en lugar de depender de que el modelo decida hacerla. Un hook de tipo PreToolUse se ejecuta antes de cada llamada a una herramienta (con "matcher": "Bash", solo antes de los comandos de terminal) y, si termina con código de salida 2, la acción se bloquea y el agente recibe el motivo, que es lo que el script escribe en la salida de errores. Cualquier otro código distinto de 0, incluido el 1, es un error que no bloquea: la acción sigue adelante (es el comportamiento por defecto; se puede cambiar con onFailure).

Este ejemplo bloquea un git commit si hay un fichero .env que git podría subir. Lo primero es tener .env en .gitignore; el hook cubre el descuido. Se registra en .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/sin-secretos.sh" }
        ]
      }
    ]
  }
}

Y el script, en .claude/hooks/sin-secretos.sh, que tiene que ser ejecutable (chmod +x .claude/hooks/sin-secretos.sh):

#!/usr/bin/env bash
# PreToolUse (Bash): bloquea un git commit si hay un .env que git podría subir.
set -uo pipefail
entrada=$(cat)
[[ "$entrada" == *commit* ]] || exit 0
command -v jq >/dev/null || { echo "sin-secretos.sh necesita jq." >&2; exit 2; }
comando=$(jq -r '.tool_input.command // ""' <<<"$entrada")
[[ "$comando" == *commit* ]] || exit 0
cd "$(jq -r '.cwd // "."' <<<"$entrada")" 2>/dev/null || exit 0
git rev-parse --git-dir >/dev/null 2>&1 || exit 0
# Lo versionado y lo nuevo sin ignorar: lo que un `git commit -a` o un
# `git add -A && git commit` en la misma orden llegaría a subir.
ficheros=$(git ls-files -z --cached --others --exclude-standard | tr '\0' '\n')
# Las plantillas (.env.example, .env.sample, .env.template) no llevan secretos.
if grep -E '(^|/)\.env(\.[^/]*)?$' <<<"$ficheros" |
   grep -vE '\.(example|sample|template)$' >/dev/null; then
  echo "Commit bloqueado: hay un fichero .env que git puede subir. Añádelo a .gitignore o sácalo del índice con git rm --cached." >&2
  exit 2
fi
exit 0

Un detalle importante: el hook se ejecuta antes del comando. Si el agente escribe git add .env && git commit en una sola orden, cuando el hook mira, .env aún no está en el índice. Por eso no basta con mirar lo preparado para el commit: el script busca en todo lo versionado y en los ficheros nuevos que no están ignorados, que es lo que un git commit -a o ese git add llegarían a subir. La opción -z evita que git ponga entre comillas las rutas con tildes, que si no se escaparían.

El hook recibe por la entrada estándar un JSON con la herramienta, su comando y la carpeta en la que trabaja el agente (cwd). Se puede probar sin el agente, pasándole ese JSON a mano. Con un .env sin ignorar:

echo '{"tool_input":{"command":"git add .env && git commit -m \"Añade config\""}}' | .claude/hooks/sin-secretos.sh; echo "salida: $?"

Commit bloqueado: hay un fichero .env que git puede subir. Añádelo a .gitignore o sácalo del índice con git rm --cached.
salida: 2

Con .env en .gitignore, o con un comando que no es un commit, el hook no objeta nada:

echo '{"tool_input":{"command":"git add -A && git commit -m \"Añade README\""}}' | .claude/hooks/sin-secretos.sh; echo "salida: $?"

salida: 0

Es una heurística sobre el texto del comando: puede bloquear de más (cualquier comando que contenga «commit» con un .env sin ignorar) y no cubre un git add -f .env && git commit ni un commit en otro repositorio con git -C. Si falta jq, bloquea los commits en lugar de dejarlos pasar; el resto de comandos sigue funcionando. Lo que de verdad protege es el .gitignore y, en la integración continua, una herramienta que busque secretos.

Probado el 14 de noviembre de 2026 con bash 5.3.9, git 2.53.0 y jq 1.8.1 en doce casos:

• Se bloquean: git add .env && git commit, git commit -a con un .env versionado, git -C . commit, un .env.local en una carpeta con tildes o con espacios, un repositorio de 20 000 ficheros y un commit sin jq instalado.
• Pasan: un .env ignorado, las plantillas (.env.example), un repositorio limpio, un comando que no es un commit y ese mismo comando sin jq instalado.

El formato de configuración es el de la documentación de Claude Code 2.1.325.

Un test que hace cumplir una regla

La regla 1 del ejemplo («no renombres ni quites campos de la respuesta de /pedidos») no se queda en una frase. Un test de contrato pide un pedido de prueba y compara los campos de la respuesta con los que esperan las apps: si falta uno o cambia de nombre, falla. Lo mismo da que el cambio lo haga un agente o una persona: si la regla se incumple, npm test lo dice.

Esto tiene una ventaja que no tiene ningún fichero de instrucciones: funciona con cualquier agente, con cualquier modelo y también cuando no hay agente.

Cómo mantenerlas

Unas instrucciones que nadie revisa acaban como un manual viejo: con comandos que ya no existen y reglas que se contradicen. Algunas costumbres que ayudan:

• Cuando el agente se equivoque, pregúntate primero si una máquina lo puede comprobar. Si sí, escribe el test, el permiso o el hook. Si no, añade la instrucción, con su motivo.
• Cada regla con su porqué. Así, cuando el motivo desaparece, sabes que la regla sobra.
• Revisa de vez en cuando. Claude Code tiene una auditoría, /doctor prompt-audit (desde la versión 2.1.283), que busca referencias a ficheros que ya no existen e instrucciones que se contradicen, y propone cambios sin aplicarlos.
• Mide el tamaño. Si el fichero pasa de 200 líneas, mueve a reglas por ruta o a skills lo que no haga falta en todas las sesiones.

Límites

• Una instrucción no es una garantía, por bien escrita que esté. Es la razón de este artículo, pero conviene repetirlo. Y aceptar lo que hace el agente sin leerlo tiene nombre: vibe coding. Qué mirar al revisarlo está en cómo revisar código generado por IA.
• Los permisos tienen huecos. Una regla de Bash compara el texto del comando, y la documentación avisa de que no es una frontera de seguridad: Bash(git push --force *) no detiene git push origin main --force, y Bash(git push *) no detiene git -C . push origin main. En el ejemplo de permisos de arriba, el primer caso lo frena la regla ask de git push *, que pide confirmación. Además, una regla deny sobre Read no impide que un script de Python o de Node abra el fichero por su cuenta. Para un bloqueo a nivel del sistema operativo está el sandbox.
• Los hooks se pueden desactivar desde la configuración, y solo actúan cuando el agente es Claude Code. Un hook pre-commit de git funciona con cualquier agente y con las personas, pero se salta con --no-verify. Un test en la integración continua (CI) es la última red, porque no depende de la herramienta. Esa red, con linters, hook pre-commit y CI, se explica en linters, hooks y CI para agentes.
• Los detalles cambian deprisa. Los nombres de ficheros, los mecanismos de carga y las versiones de este artículo son los de noviembre de 2026. El principio, que lo importante lo compruebe una máquina, no caduca.

Tu siguiente paso

Abre el fichero de instrucciones de tu proyecto y, para cada regla:

1. Comprueba que se puede verificar. Si es vaga, reescríbela o bórrala.
2. Añade su motivo en media frase.
3. Pregúntate qué pasa si el agente la incumple. Si la respuesta es grave, busca qué test, permiso o hook lo impediría.

Si las decisiones de arquitectura del proyecto no están escritas, empieza por ahí: con un registro de decisiones de arquitectura (Architecture Decision Records), el agente sabe dónde mirar antes de cambiar algo.

Y antes de aceptar lo que entregue, revísalo: cómo revisar código generado por IA.

El contenido sobre IA envejece rápido. Última revisión: 14 de noviembre de 2026.

Fuentes

Consultadas el 14 de noviembre de 2026.

• AGENTS.md: web oficial del formato (Agentic AI Foundation, Linux Foundation).
• Documentación de Claude Code, versión 2.1.325: How Claude remembers your project (CLAUDE.md, AGENTS.md, importaciones y .claude/rules/), Automate actions with hooks y Configure permissions.