CLAUDE.md y AGENTS.md: qué escribo tras 42 proyectos

Actualización (9 de noviembre de 2026): ya han salido Claude Fable 5.2 y Mythos 5.2 - precios, acceso y benchmarks en mi guía de Claude Fable 5.2.

👁 114 lecturas

En mi disco tengo 42 archivos con instrucciones para agentes de IA: 16 archivos CLAUDE.md y 26 archivos AGENTS.md, cada uno en la carpeta de un proyecto distinto. El más corto tiene una línea y el más largo, 402. Este último duplica la extensión que recomienda Anthropic. Empiezo por él porque muestra bien qué acaba entrando realmente en uno de estos archivos.

Qué es CLAUDE.md

Es un archivo Markdown normal que Claude Code lee al comienzo de cada sesión. Cada conversación con el agente empieza sin memoria, así que hay que volver a explicarle todo lo que no pueda deducir del código. CLAUDE.md lo hace por ti: incluye comandos de pruebas, reglas del proyecto, cosas que el agente no debe hacer y trampas con las que ya te has encontrado.

La documentación de Claude Code lo dice claramente: es contexto, no una configuración estricta. El agente suele seguir el archivo, pero no está obligado a hacerlo. Si algo debe quedar bloqueado siempre, como borrar archivos o desplegar en un servidor, para eso están los hooks y los permisos de la configuración, no una frase en CLAUDE.md.

Dónde está y qué se carga

Puede haber varios archivos a la vez. Claude Code no elige uno: combina todos los que encuentra, desde el más general hasta el más cercano a la carpeta en la que trabajas.

Los archivos de las carpetas que están por encima del lugar desde el que inicias el agente se cargan de inmediato. Los de las subcarpetas, solo cuando el agente empieza a leer o modificar archivos en ellas. Así, en un repositorio grande, las instrucciones del frontend no ocupan espacio cuando el agente trabaja en la base de datos.

Puedes generar una primera versión con el comando /init. Claude revisará el código y guardará los comandos y convenciones que detecte. Es un buen comienzo, pero siempre añado el resto a mano: las líneas más valiosas son las que no se pueden deducir del código.

Mi archivo más largo: 402 líneas

La documentación recomienda que cada CLAUDE.md tenga menos de 200 líneas, porque un archivo más largo consume contexto y el agente lo sigue peor. El archivo de mi proyecto Jantaris tiene 402 líneas y 46 095 bytes. De mis 16 archivos CLAUDE.md, solo este supera el límite; la mediana es de 35 líneas.

No apareció de golpe. Fue creciendo con las trampas que añadía después de cada error: cómo almacena en caché las imágenes el servidor y por qué sustituir un archivo por otro con el mismo nombre hace que la gente tarde una semana en ver el cambio, cuántos registros por hora permite el sistema de protección y cómo deben reiniciarlo las pruebas, dónde está el servidor y cómo se envía el correo. Cada línea es la huella de un problema concreto. Al final, el archivo se hizo demasiado largo.

Para mí, CLAUDE.md no es la documentación del proyecto, sino un mapa de minas. El agente puede encontrar en el código y en el README cómo funciona la aplicación. En CLAUDE.md debe estar lo que no se ve en el código y ya ha causado un problema. Cuando el archivo supera las 200 líneas, lo divido en archivos temáticos dentro de .claude/rules/. Importar con @archivo.md solo ayuda a organizarlo, porque el archivo importado se carga entero de todos modos.

El archivo que enseño en el curso: 34 líneas

Un buen ejemplo es el CLAUDE.md del proyecto «Base de reparaciones», una aplicación para un taller de coches que estamos construyendo desde cero en mi curso SaaS en un fin de semana con Claude Code. Aquí está el archivo completo, sin recortes:

# Base de reparaciones - notas para el agente

Producto, pantallas y reglas: @SPEC.md
Construye solo la sección DEBE ESTAR de ALCANCE.md. Añade las ideas
que queden fuera a MÁS ADELANTE, con una condición para retomarlas, y consúltamelo.

## Stack
- Node 22.13 o superior, sin dependencias de npm: node:http, node:sqlite, node:test, fetch.
- SQLite en data/app.db; migraciones en migrations/NNN_nombre.sql.
- HTML renderizado en el servidor; en el navegador, JavaScript sin frameworks.

## Comandos
- npm run dev                 servidor en el puerto 8080, se reinicia al cambiar un archivo
- npm test                    node --test "test/*.test.js" (glob entre comillas)
- npm run reset               base de datos desde cero + datos de prueba + cuentas de prueba
- python tools/zrzuty.py URL  capturas a 1440 px y 390 px en data/shots/

## Reglas
- Importes en céntimos como INTEGER. Nunca uses números de coma flotante.
- El servidor comprueba los límites de los planes (R1-R3). El navegador solo los muestra.
- Cada regla R de SPEC.md debe tener una prueba con su número en el nombre.
- Guarda los archivos de texto con finales de línea LF.
- En el contenido, usa solo el guion corto "-". Hay una prueba que revisa todas las plantillas.

## Prohibiciones
- No leas .env. No despliegues. No ejecutes git push, git reset ni git clean.
- No ejecutes pruebas sobre data/app.db (las pruebas usan una base en memoria).
- No importes datos de fabricantes (Autodata, HaynesPro, portales de fabricantes):
  licencias de fabricantes y protección de bases de datos en la UE.

## Trampas
- Git Bash modifica las rutas: usa MSYS_NO_PATHCONV=1 antes de un comando con /...
- Guarda los archivos con expresiones regulares con una herramienta de escritura de archivos,
  no con un heredoc en bash (se pierden las barras invertidas).

Cada sección tiene un motivo:

• Referencia a la especificación. La descripción del producto está en SPEC.md y CLAUDE.md solo la importa. La instrucción de limitarse a la sección DEBE ESTAR mantiene al agente dentro del alcance. Sin ella, al cabo de una hora aparecen funciones que nadie ha pedido.
• Comandos con la sintaxis exacta. Poner entre comillas el glob de las pruebas es un detalle fácil de pasar por alto, pero de él depende que se ejecuten todos los archivos de prueba.
• Reglas que se pueden comprobar. Importes en céntimos, límites en el servidor y una prueba para cada regla. Nada de «escribe código limpio», porque no se puede verificar.
• Prohibiciones. Las más importantes también las duplico en la configuración de permisos, porque el archivo solo expresa una petición.
• Trampas del entorno. Windows y Git Bash estropean las rutas que empiezan por una barra. El agente no lo sabe hasta que falla un comando.

La línea que me costó una ronda de edición

Se ve muy bien con un ejemplo. El 30 de octubre, mientras editaba textos para la revista DYGOT, ejecuté un script que descarga el estado actual del servidor entre una tanda de cambios y la subida. Sobrescribió los cambios locales y perdí la primera ronda de edición. Desde ese día, el archivo de instrucciones de ese proyecto incluye esta frase: «Ejecútalo SOLO antes de empezar a trabajar: si lo ejecutas entre la edición y la subida, sobrescribirá tus cambios». Ningún generador la habría escrito, porque el código del script no indica cuándo se puede ejecutar.

AGENTS.md: el mismo concepto para otros agentes

AGENTS.md es un archivo de instrucciones equivalente, pero con un nombre que entienden distintas herramientas: Codex de OpenAI, Cursor, Gemini CLI, el agente de GitHub Copilot y otras muchas. Agentic AI Foundation, dentro de Linux Foundation, mantiene el formato. Tengo 26 archivos AGENTS.md y son cortos: la mediana es de 8 líneas, porque la mayoría describen tareas gráficas concretas para Codex.

Claude Code también puede leer AGENTS.md desde la versión 2.1.277. De forma predeterminada, solo lo hace cuando el proyecto no tiene un archivo CLAUDE.md. Si están los dos, Claude lee el suyo y omite AGENTS.md. Para que ambas herramientas reciban las mismas reglas, lo más sencillo es guardarlas en AGENTS.md y añadir una línea de importación @AGENTS.md en CLAUDE.md. En el artículo cómo pasar de Claude Code a Codex explico cómo trasladar el conjunto completo, incluidas las skills y los servidores MCP.

En los proyectos en los que se alternan Claude y Codex, tengo otra regla al final del archivo: después de trabajar, añade una entrada al registro compartido de agentes con la fecha, el nombre del agente y una lista de cambios. El siguiente agente lee el registro antes de empezar y sabe qué modificó el anterior. Es más sencillo que sincronizar la memoria de ambas herramientas.

Qué no incluyo

• Claves ni contraseñas. El archivo del proyecto suele acabar en el repositorio. En los míos es más habitual encontrar la prohibición de leer .env que su contenido.
• Estructuras de carpetas. El agente puede verlas en unos segundos, y cualquier descripción del archivo quedará desactualizada en cuanto haya un cambio.
• Generalidades. «Cuida la calidad» no cambia nada. «Cada regla debe tener una prueba con su número» sí.
• Reglas contradictorias. La documentación advierte de que, si encuentra dos instrucciones contradictorias, Claude puede elegir cualquiera. De vez en cuando reviso mis archivos y elimino lo que ya no sea válido.
• Notas para personas. Si tienen que quedarse, las pongo en un comentario HTML <!-- -->. Claude Code elimina esos comentarios antes de cargar el archivo, así que no consumen contexto.

Por dónde empezar

Si estás empezando con Claude Code, no escribas CLAUDE.md por adelantado. Ejecuta /init, conserva lo que tenga sentido y añade una línea cada vez que el agente repita un error. Después de una semana tendrás un archivo que describe tu proyecto, no el proyecto de una guía. En mi guía explico la instalación de Claude Code y, en este artículo, cuánto cuesta Claude Code.

En el curso SaaS en un fin de semana con Claude Code escribimos paso a paso la especificación y CLAUDE.md: son 30 lecciones, desde comprobar la demanda de una idea hasta desplegarla en tu propio servidor, pasando por la base de datos, el inicio de sesión y los pagos. El curso también está incluido en el paquete kombAIn, junto con otros 27 cursos del laboratorio.

Fuentes y fecha de consulta

Información actualizada a 6.11.2026.

• Archivos CLAUDE.md y AGENTS.md de mis proyectos: 42 archivos tras eliminar copias y repositorios ajenos, contabilizados el 6.11.2026.
• Claude Code - documentación: How Claude remembers your project (CLAUDE.md, AGENTS.md, importaciones y límite de 200 líneas)
• AGENTS.md - descripción del formato

// sigue leyendoBlack Friday 2026 y suscripciones de IA: ChatGPT, Gemini, ClaudeGuíasClaude Duet en España: situación y alternativasGuíasClaude API: cómo conseguir una clave y cuánto cuestaGuías

Kinetyra