AGENTS.md y HUMAN.md: qué son y cómo usarlos

Qué es AGENTS.md

AGENTS.md es un archivo Markdown simple ubicado en la raíz de un repositorio. Indica a un agente de programación cómo trabajar en ese proyecto. El sitio oficial lo describe como "un README para agentes: un lugar específico y predecible donde proporcionar el contexto y las instrucciones necesarios para ayudar a los agentes de programación de IA a trabajar en el proyecto". El formato está supervisado por Agentic AI Foundation bajo Linux Foundation. Más de veinte agentes lo leen, incluidos Codex, Cursor, Jules, Devin y GitHub Copilot (en julio de 2026).

La convención existe por una razón práctica. Una persona nueva en el equipo lee el README, supone cuál es el comando de compilación y pregunta a alguien cuando la suposición es incorrecta. Un agente no puede preguntar. Supone, ejecuta npm test en un proyecto que usa pnpm test, lee el error e intenta otra cosa. Cada uno de esos tokens tiene un coste. Escribir el comando correcto una sola vez elimina toda esa clase de errores.

No hay campos obligatorios. El sitio lo indica claramente: "AGENTS.md es simplemente Markdown estándar. Usa los encabezados que quieras; el agente analiza el texto que proporciones". Esa es toda la especificación. El valor no está en el formato. Está en que el archivo se encuentra en una ruta que todas las herramientas ya comprueban.

Dónde va el archivo y qué archivo prevalece

Coloca el primero en la raíz del repositorio. En un monorepo puedes añadir más archivos dentro de cada subproyecto. La regla es simple: "agents lee automáticamente el archivo más cercano en el árbol de directorios, por lo que el más próximo tiene prioridad". Si dos archivos entran en conflicto, prevalece el archivo que está más cerca del archivo que editas. Todo lo que escribas en el chat prevalece sobre ambos.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Conviene usar esta estructura anidada porque es la única forma de definir algo que sea válido en una carpeta y no en la siguiente. Una regla como "cada endpoint valida sus datos de entrada" debe estar junto a los endpoints. En un archivo raíz se carga en todas las tareas no relacionadas y no aporta nada.

Qué debe incluir un AGENTS.md

Escriba lo que un agente no puede deducir al leer el código. Los comandos exactos para compilar, probar y ejecutar el lint tienen prioridad y deben aparecer en el formato que pegaría en un terminal. Añada el comando para ejecutar una sola prueba, porque un agente que solo sabe ejecutar toda la suite la ejecutará cuarenta veces. Indique las convenciones que difieren de la configuración predeterminada de las herramientas, ya que el agente ya conoce esa configuración y solo necesita conocer su desviación. Añada el formato de los mensajes de commit y las reglas de las pull requests, si existen.

Sea lo bastante concreto para que cada afirmación pueda comprobarse. "Use una indentación de 2 espacios" es una instrucción útil porque puede verificarse si se cumplió o no. "Formatee el código correctamente" no lo es, porque no se puede comprobar nada específico. Lo mismo se aplica a las ubicaciones: "Los controladores de la API están en src/api/handlers/" es mejor que "mantenga los archivos organizados".

Las reglas negativas también merecen espacio. "Nunca edite archivos en dist/; los genera npm run build" evita un error específico y, como indica la causa, permite que el agente deduzca el caso equivalente que no se documentó.

Lo que nunca debe incluirse

Nunca incluya un secreto en estos archivos. El archivo se confirma en git, se carga en el contexto al inicio de cada sesión y se envía a un proveedor de modelos en cada solicitud. Una clave de API en AGENTS.md queda en el historial de su repositorio y en los registros de terceros. Haga referencia al secreto en lugar de pegarlo: "la contraseña de la base de datos está en .env, que está excluido de git; pida permiso antes de leerlo". Esta práctica se explica con más detalle en mantener las credenciales fuera del alcance de un agente.

Omita todo lo que el agente pueda obtener mediante inspección. Un listado de directorios pegado, una copia de la lista de dependencias o una descripción de la arquitectura que repita los nombres de las carpetas: todo queda obsoleto la semana posterior a su redacción y, mientras tanto, consume contexto en cada sesión. Conserve los problemas frecuentes y sus motivos. Elimine el inventario.

CLAUDE.md es la instancia de Claude Code de la misma idea

Claude Code lee CLAUDE.md y no lee AGENTS.md por sí solo. Un archivo del proyecto se encuentra en ./CLAUDE.md o ./.claude/CLAUDE.md, las preferencias personales para todos los proyectos se guardan en ~/.claude/CLAUDE.md y una organización puede distribuir un archivo para todo el equipo en /etc/claude-code/CLAUDE.md en Linux. Los archivos detectados se concatenan desde la raíz del sistema de archivos hasta el directorio de trabajo, por lo que el archivo más cercano al directorio desde el que inició la sesión se lee en último lugar.

Si su repositorio ya tiene un AGENTS.md, no mantenga una segunda copia. Impórtelo y añada solo lo específico de Claude:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Un enlace simbólico funciona si no tiene nada más que añadir:

ln -s AGENTS.md CLAUDE.md

El comando no muestra ninguna salida si se ejecuta correctamente. En la siguiente sesión, ejecute /context y confirme que CLAUDE.md aparece en Archivos de memoria. Si no aparece en esa lista, el archivo nunca se cargó y nada de su contenido se aplicó. Para generar un primer borrador en lugar de escribirlo manualmente, ejecute /init: lee el código base y produce un archivo inicial. Si ya existe un CLAUDE.md, sugiere mejoras en lugar de sobrescribirlo.

Mantenga cada archivo por debajo de unas 200 líneas. Los archivos más largos consumen una mayor parte de la ventana y reducen el cumplimiento de las instrucciones. Si quiere ver qué más compite por ese espacio, qué ocupa realmente la ventana de contexto de un agente lo desglosa.

Hay un punto que merece especial atención. Un AGENTS.md contiene directrices, no es un sistema de permisos. El contenido llega como contexto ordinario, por lo que el modelo lo lee y normalmente lo cumple, pero nada bloquea una acción que lo contradiga. Para una regla que deba cumplirse siempre, como "no hacer push a main", use un hook o una configuración de permisos, porque se ejecutan como código y no dependen de que el modelo decida obedecer.

Herramientas que escriben estos archivos por ti

Dos proyectos de la lista de tendencias de GitHub del 30 de julio de 2026 muestran hacia dónde se dirige la convención.

agent0ai/dox (1,368 estrellas en julio de 2026) es un framework para mantener actualizada una jerarquía de archivos AGENTS.md. No incluye ningún paquete ni runtime. Copias el contenido de su AGENTS.md en tu propio AGENTS.md raíz, y esa es la instalación. Para un proyecto que ya existe, indícale a tu agente:

Initialize DOX tree for this project now.

A continuación, el agente crea los archivos AGENTS.md secundarios y sus índices, recorre esa jerarquía antes de editar cualquier elemento y actualiza la documentación afectada después de aplicar un cambio. La premisa es que la documentación que un agente mantiene como efecto secundario de su trabajo sigue siendo correcta, mientras que la documentación que una persona actualiza manualmente no.

HUMAN.md, el mismo enfoque aplicado a ti

Intuition-Lab/personal-model (1,260 estrellas en julio de 2026) aplica el patrón a una persona en lugar de a un repositorio. El proyecto presenta tu HUMAN.md como el resultado del sistema, no como un archivo que escribes: «un modelo vivo de lo que importa ahora, de cómo sueles tomar decisiones y de hacia dónde se dirige tu atención». Se ejecuta localmente en macOS 13 o posterior, captura la actividad después de que concedas los permisos de macOS y expone el resultado a los agentes mediante MCP (model context protocol). La instalación básica es:

uv tool install personal-model
persome onboard
persome model open --after 30

No necesitas nada de eso para obtener la mayor parte del beneficio. Un HUMAN.md escrito manualmente ocupa unas veinte líneas: tu función, tu zona horaria, la pila tecnológica que realmente usas, las decisiones que ya has tomado y no quieres volver a discutir, y cuánta explicación quieres recibir. Evita las mismas explicaciones repetidas que evita un archivo del proyecto, pero en un nivel superior.

Una advertencia. Un HUMAN.md es un perfil de una persona, por lo que es sensible por definición. No lo guardes en un repositorio público. Colócalo en ~/.claude/CLAUDE.md o en un CLAUDE.local.md excluido mediante gitignore en la raíz del proyecto. Este último se carga junto con el archivo versionado y se trata de la misma forma.

Una plantilla inicial que puedes copiar

Es breve a propósito. Elimina las secciones que no correspondan y evita añadir otras que no puedas mantener actualizadas.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Escríbela y corrígela en el mismo lugar. La señal para añadir una línea es que hayas escrito la misma corrección dos veces en el chat. Esta única regla mantiene útil el archivo y evita que crezca hasta convertirse en un documento que nadie lee, incluidas las máquinas. Cuando se estabiliza, acompaña al repositorio. Esto es especialmente importante cuando el agente se ejecuta en un lugar distinto de tu portátil: ejecutar un agente de programación en tu propio servidor explica esa configuración.

FAQ

¿AGENTS.md es el mismo archivo que CLAUDE.md?

Son la misma idea con dos nombres de archivo. Claude Code lee CLAUDE.md e ignora AGENTS.md a menos que los conecte. Mantenga un archivo como fuente de verdad y vincule el otro con él, ya sea mediante una línea @AGENTS.md al principio de su CLAUDE.md o mediante ln -s AGENTS.md CLAUDE.md. Dos copias completas mantenidas por separado dejarán de coincidir en menos de un mes.

¿Escribir un AGENTS.md garantiza que el agente lo seguirá?

No. El contenido se entrega como contexto, por lo que el modelo lo lee y normalmente lo cumple, pero nada impide una acción que lo contradiga. Las instrucciones vagas son las que se siguen con menos fiabilidad, y si dos archivos proporcionan indicaciones opuestas, el agente elige una de forma arbitraria. Para una regla que deba cumplirse siempre, use un hook o una regla de permisos. El cliente las aplica independientemente de lo que decida el modelo.

¿Se debe incluir AGENTS.md en git?

Sí, para todo lo que sea cierto sobre el proyecto: comandos de compilación, estructura y convenciones. Ese es el objetivo del archivo, porque los agentes de sus compañeros comienzan con el mismo contexto que el suyo. Todo lo personal o específico de una máquina debe estar en un archivo separado excluido mediante gitignore, y las credenciales no deben estar en ninguno de los dos.

¿Qué es HUMAN.md y necesito uno?

HUMAN.md es un perfil legible por máquinas de una persona, no de un proyecto. Contiene su función, sus restricciones y las decisiones que ya ha establecido, para que no vuelvan a abrirse en cada sesión. No necesita ninguna herramienta para empezar: veinte líneas escritas manualmente en su archivo de instrucciones a nivel de usuario proporcionan la mayor parte del valor. Trátelo como datos personales y no lo incluya en ningún repositorio que publique.