AGENTS.md y HUMAN.md: guía y plantilla

Qué es AGENTS.md

AGENTS.md es un archivo Markdown simple situado 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 basados en IA a trabajar en el proyecto». El formato está gestionado por Agentic AI Foundation bajo Linux Foundation, y más de veinte agentes lo leen, incluidos Codex, Cursor, Jules, Devin y GitHub Copilot (a fecha de julio de 2026).

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

No hay campos obligatorios. El sitio lo indica explícitamente: «AGENTS.md es simplemente Markdown estándar. Use los encabezados que quiera; el agente analiza el texto que proporcione». 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 buscan.

Dónde va el archivo y qué archivo prevalece

Coloque el primero en la raíz del repositorio. En un monorepo puede añadir más archivos dentro de cada subproyecto. La regla es sencilla: «los agentes leen automáticamente el archivo más cercano en el árbol de directorios, por lo que prevalece el más próximo». Si dos archivos entran en conflicto, prevalece el archivo que corresponde al elemento que se está editando. Todo lo que escriba 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 expresar algo que es 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. Si el archivo raíz ya tiene una sección por servicio, dividirlo en una estructura anidada es la solución. Ahí se explica qué reglas deben pasar a niveles inferiores y cuáles deben permanecer en la raíz.

Qué debe contener un AGENTS.md

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

Sea concreto para que cada afirmación se pueda comprobar. «Use una indentación de 2 espacios» es una instrucción útil porque se puede verificar si se cumplió. «Formatee correctamente el código» no lo es, porque no se puede comprobar nada a partir de esa indicación. Lo mismo se aplica a las ubicaciones: «Los gestores de API están en src/api/handlers/» es mejor que «Mantenga los archivos organizados».

Las reglas negativas también justifican su espacio. «No edite nunca los archivos de dist/; los genera npm run build» evita un error concreto y, como indica la causa, el agente puede deducir el caso equivalente que no se documentó. Aquí también debe incluirse una regla sobre el alcance, porque un agente al que se deja decidir por su cuenta reescribirá más de lo solicitado: una habilidad muy copiada sólo insiste en aplicar el cambio mínimo que funcione.

Lo que nunca debe contener uno

Nunca incluya un secreto en uno de 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 un tercero. En lugar de pegar el secreto, indique dónde está: «la contraseña de la base de datos está en .env, que está excluido de git; solicite permiso antes de leerlo». Esta disciplina se explica con más detalle en mantener las credenciales fuera del alcance de un agente.

Omitan todo lo que el agente pueda deducir al inspeccionarlo. 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 durante la semana posterior a su redacción y, mientras tanto, consume contexto en cada sesión. Conserve los problemas potenciales y sus motivos. Elimine el inventario. Conviene separar los motivos, porque un agente que no puede ver por qué existe una estructura inusual la refactorizará silenciosamente y la eliminará. Ese es el motivo para mantener un DESIGN.md junto a este archivo.

CLAUDE.md es la versión de Claude Code del mismo concepto

Claude Code lee CLAUDE.md y no lee AGENTS.md por sí solo. El 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 instalar un archivo para todo el equipo en /etc/claude-code/CLAUDE.md en Linux. Los archivos descubiertos 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. Todas las sesiones que inicie en ese directorio cargan la misma pila. Esto permite ejecutar dos sesiones en paralelo en una misma máquina, y esas sesiones pueden pasarse trabajo mientras se ejecutan.

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

@AGENTS.md

## Claude Code

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

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

ln -s AGENTS.md CLAUDE.md

El comando no muestra nada si termina correctamente. En la siguiente sesión, ejecute /context y confirme que CLAUDE.md aparece en Memory files. 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, propone mejoras en lugar de sobrescribirlo.

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

Hay un punto que requiere especial atención. Un AGENTS.md contiene directrices, no es un sistema de permisos. El contenido llega como contexto ordinario. El modelo lo lee y normalmente lo cumple, pero nada impide una acción que lo contradiga. Si se omite silenciosamente una regla que escribió y no puede determinar el motivo, revise los motivos por los que se descarta una instrucción antes de reescribirla por tercera vez. Para una regla que deba cumplirse siempre, como "never push to main", use un hook o un ajuste de permisos. Se ejecutan como código y no dependen de que el modelo decida obedecer.

Herramientas que escriben estos archivos por usted

Dos proyectos de la lista de tendencias de GitHub del 30 July 2026 muestran hacia dónde evoluciona esta convención.

agent0ai/dox (1,368 estrellas en July 2026) es un framework para mantener actualizado un árbol de archivos AGENTS.md. No incluye ningún paquete ni runtime. Debe copiar el contenido de su AGENTS.md en el archivo AGENTS.md raíz propio; esa es toda la instalación. En un proyecto que ya existe, indique a su agente:

Initialize DOX tree for this project now.

A continuación, el agente crea los archivos AGENTS.md secundarios y sus índices, recorre ese árbol 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 consecuencia 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 permiso a macOS y expone el resultado a los agentes mediante MCP (model context protocol). El proceso de instalación breve 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 abrir, y cuánta explicación quieres recibir. Evita las mismas explicaciones repetidas que evita un archivo de proyecto, pero en un nivel superior.

Una precaución. Un HUMAN.md es un perfil de una persona, por lo que es información sensible por definición. No lo guardes en un repositorio público. Ponlo 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 puede copiar

Esto es breve a propósito. Elimine las secciones que no correspondan y evite añadir contenido que no pueda mantener actualizado.

# 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íbalo y corríjalo en el mismo archivo. La señal para añadir una línea es que haya 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, el archivo permanece junto al repositorio. Esto es especialmente importante cuando el agente se ejecuta en un lugar distinto de su portátil: ejecutar un agente de programación en su 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 solo archivo como fuente de verdad y vincule el otro con él, ya sea mediante una línea con el contenido @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 siga?

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 imprecisas se siguen con menos fiabilidad, y si dos archivos proporcionan indicaciones opuestas, el agente elegirá 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.

¿Debe incluirse AGENTS.md en git?

Sí, si contiene información verdadera sobre el proyecto: comandos de compilación, estructura y convenciones. Ese es el objetivo del archivo, porque los agentes de sus compañeros empiezan con el mismo contexto que el suyo. Todo lo personal o específico de una máquina debe estar en un archivo separado e ignorado por git. 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 sobre una persona, no sobre 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 aportan la mayor parte del valor. Trátelo como datos personales y no lo incluya en ningún repositorio que publique.