Skip to content

AGENTS.md y CLAUDE.md: deja para la IA un manual del proyecto ​

Lectura previa: Manual avanzado: haz que la IA entienda mejor tu proyecto

AGENTS.md es un manual del proyecto que se coloca en la raíz del directorio: Claude Code, Codex y OpenCode lo leen automáticamente antes de empezar a trabajar, sin que tengas que explicarles de viva voz el stack tecnológico y las reglas cada vez.

El archivo de memoria de Claude Code se llama CLAUDE.md: el mecanismo es el mismo, solo cambia el nombre del archivo. En esta página configuramos ambos archivos juntos para que las tres herramientas lean el mismo contenido.

Qué podrás hacer al terminar ​

  • Escribir un AGENTS.md colocado en la raíz del proyecto que los tres agentes de codificación de IA leerán automáticamente
  • Explicar qué cuatro bloques de contenido debe llevar AGENTS.md y por qué no conviene escribirlo como un largo discurso
  • Configurar bien Claude Code con CLAUDE.md y garantizar que los dos archivos nunca entren en conflicto
  • Abrir una nueva sesión para verificar que la IA, sin que le expliques, puede responder cómo iniciar el proyecto y qué convenciones seguir

Tu situación actual ​

  • Cada vez que abres una nueva sesión, tienes que repetir lo de «usamos pnpm, no npm» y «las pruebas se ejecutan con pnpm test».
  • Las reglas acordadas en la sesión anterior se le olvidan por completo a la IA en esta, y de repente te vuelve a hacer un npm install de instalación desordenada.
  • Las convenciones del proyecto solo existen en tu cabeza: si cambias de sesión, de herramienta o traes a un compañero a colaborar, hay que explicarlas todo de nuevo.

Cuándo usar esta técnica ​

Cuando necesitas:

  • Que la IA sepa automáticamente en cada nueva sesión el stack tecnológico, los comandos habituales y las convenciones de código del proyecto
  • Subir las reglas a git para que todos en el equipo y todas las IA compartan la misma versión
  • Hoy usas Claude Code, mañana cambias a Codex o OpenCode, y el manual sigue funcionando igual

Y no quieres:

  • Pegar un gran bloque de «contexto del proyecto» en el cuadro de diálogo antes de cada sesión de trabajo
  • Configurar el mismo conjunto de reglas por separado en tres herramientas, y además de forma distinta

🎒 Preparativos antes de empezar ​

Idea central ​

El «mecanismo de manual» de las tres herramientas se parece mucho; la diferencia está en el nombre del archivo y en cómo lo buscan:

HerramientaQué archivo leeDónde va el de nivel de proyectoArchivo global (preferencias personales)
Claude CodeCLAUDE.md; si no existe, también puede leer directamente AGENTS.md (requiere v2.1.277+)Raíz del proyecto ./CLAUDE.md o ./.claude/CLAUDE.md~/.claude/CLAUDE.md
CodexAGENTS.md, lo lee antes de empezar a trabajarRaíz del proyecto~/.codex/AGENTS.md
OpenCodeAGENTS.md; desde v2.3.1, si no hay AGENTS.md en el directorio, se pasa a leer CLAUDE.mdel directorio raíz del proyecto~/.config/opencode/AGENTS.md (si falta, retrocede a leer ~/.claude/CLAUDE.md)

La idea se resume en una frase: tomar AGENTS.md como única fuente de verdad. Codex y OpenCode lo leen directamente; Claude Code usa un CLAUDE.md que referencia su contenido y añade las indicaciones exclusivas de Claude. Si cambias las reglas, solo las cambias en un lugar y las tres herramientas se actualizan a la vez.

CLAUDE.md además se divide por ámbito: nivel de empresa (gestión unificada de la organización), nivel de usuario (~/.claude/CLAUDE.md, para preferencias personales, aplica a todos tus proyectos) y nivel de proyecto (entra en el control de versiones, compartido por el equipo). En esta página configuramos principalmente el nivel de proyecto.

Hazlo conmigo ​

Paso 1: crea AGENTS.md en la raíz del proyecto ​

Por qué: cuanto más concreto sea el manual, menos tiene que adivinar la IA. Los ejemplos de la guía oficial de Codex también son instrucciones de una línea y ejecutables directamente, no frases como «el código debe estar bien formateado».

Crea AGENTS.md en la raíz del proyecto (al mismo nivel que el README) y escribe cuatro bloques de contenido:

markdown
# Descripción del proyecto

- Una frase: qué hace este proyecto (ej.: un sitio web de reserva de cursos)
- Stack tecnológico: Next.js + TypeScript, gestión de paquetes con pnpm
- Comandos habituales: pnpm install / pnpm dev / pnpm test / pnpm build
- Convenciones de código: los componentes van en src/components, ejecuta pnpm test antes de cada commit, no modifiques directamente los archivos generados por el build

Escribe cada regla como una instrucción verificable: «usar sangría de 2 espacios» es mejor que «el formato debe ser correcto», «ejecutar pnpm test antes de cada commit» es mejor que «recuerda probar».

Deberías ver: el archivo en la raíz del directorio, de unas pocas decenas de líneas como máximo, con una regla por línea.

  • Pequeña comprobación: pide a alguien que no conoce tu proyecto que mire durante 30 segundos; debe poder decir qué stack usa el proyecto y cómo iniciarlo

Paso 2: coloca el manual en el lugar correcto ​

Por qué: las tres herramientas buscan el manual de formas distintas, pero todas reconocen el directorio raíz del proyecto: Codex busca desde la raíz del proyecto hasta el subdirectorio donde te encuentras; OpenCode primero lee el archivo global y luego recopila desde el directorio actual subiendo nivel por nivel; Claude Code lee el CLAUDE.md del directorio actual y de los niveles superiores. Si lo colocas en la raíz, los tres métodos de búsqueda lo encuentran.

Operación:

  1. Confirma que AGENTS.md esté en el directorio raíz del proyecto; no lo metas en subdirectorios como src/ ni lo dejes en el escritorio.
  2. Súbelo a git. La documentación de OpenCode recomienda explícitamente confirmar el archivo de directrices del proyecto en el repositorio para que cada colaborador reciba la misma guía.
  3. Las preferencias personales (por ejemplo, «responde en chino») no las escribas en el manual del proyecto; ponlas en el archivo de prompts global de cada herramienta: Codex usa ~/.codex/AGENTS.md, OpenCode usa ~/.config/opencode/AGENTS.md, Claude Code usa ~/.claude/CLAUDE.md.

Deberías ver: git status muestra que AGENTS.md está siendo rastreado; en el directorio raíz, ls te deja verlo junto al README. Después, sin importar si inicias el agente desde la raíz o desde un subdirectorio, encontrará este manual.

Paso 3: darle a Claude Code un CLAUDE.md ​

Por qué: Claude Code lee CLAUDE.md por defecto. Mientras exista un CLAUDE.md a nivel de proyecto en el directorio de trabajo o en un nivel superior, deja de leer AGENTS.md; si no conectas ambos archivos, Claude Code «no verá» tu manual.

Método A (recomendado): CLAUDE.md importa AGENTS.md ​

Crea un CLAUDE.md nuevo en el directorio raíz:

markdown
@AGENTS.md

## Exclusivo de Claude Code

- (Opcional) Indicaciones adicionales solo para Claude

@AGENTS.md es la sintaxis de importación de Claude Code: el contenido de AGENTS.md se carga expandido, y las indicaciones exclusivas para Claude se escriben debajo de la importación. Las reglas se mantienen en un solo lugar.

Método B: enlace simbólico ​

bash
ln -s AGENTS.md CLAUDE.md

Un solo comando y los dos archivos quedan siempre sincronizados; si tiene éxito, no produce salida. Pero en Windows crear enlaces simbólicos requiere permisos de administrador o modo de desarrollador, y Git podría extraerlo como texto plano: mientras alguien del equipo use Windows, elige el método A.

Método C: copiar el contenido ​

Copia el contenido de AGENTS.md en CLAUDE.md. Es lo más intuitivo, pero el costo es que al cambiar las reglas hay que editar dos lugares; cuando los dos dicen cosas distintas, la IA puede creer cualquiera de las dos sin más.

Deberías ver: ejecuta claude en el directorio del proyecto, escribe /context, y en la lista de Memory files aparece CLAUDE.md, con el contenido importado de AGENTS.md cargándose a continuación.

  • Comprobación rápida: CLAUDE.md aparece en los Memory files de /context

💡 ¿Qué pasa si no creas un CLAUDE.md?

Las versiones nuevas de Claude Code (desde la v2.1.277) leen AGENTS.md directamente cuando no hay CLAUDE.md, y al inicio de la sesión se muestra una línea similar a no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. Pero algunas sesiones no lo admiten (por ejemplo, la primera sesión tras actualizar desde una versión antigua), así que lo más seguro es configurar un CLAUDE.md.

Paso 4: abrir una sesión nueva para verificar que el manual surte efecto ​

Por qué: las tres herramientas leen el manual al iniciar la sesión: Claude Code carga los archivos de memoria al comienzo de cada sesión, Codex construye la cadena de instrucciones en cada ejecución, y OpenCode también necesita una sesión nueva para que los cambios en archivos de directrices anidados surtan efecto. Si pruebas en una sesión antigua, lo que pruebas son las reglas antiguas.

Operación:

  1. Abre una sesión completamente nueva: Claude Code ejecuta claude en el directorio del proyecto, Codex ejecuta codex.
  2. Pregunta directamente: «¿Cómo se inicia este proyecto? ¿Qué convenciones de código hay?»
  3. Los usuarios de Codex pueden ejecutar el comando de verificación que da la guía oficial:
bash
codex --ask-for-approval never "Summarize the current instructions."

Deberías ver: la IA, sin ninguna explicación adicional tuya, responde con el comando de inicio y las convenciones escritas en el archivo; Codex recita las directrices de los archivos global y de proyecto según el orden de carga.

  • Comprobación rápida: inicia de nuevo desde otro subdirectorio y la IA sigue encontrando el manual

Punto de control ✅ ​

  • AGENTS.md está en el directorio raíz del proyecto e incluye cuatro bloques: introducción del proyecto, stack tecnológico, comandos habituales y convenciones de código
  • El archivo está confirmado en git; cualquiera que clone el repositorio obtiene la misma guía
  • En una sesión de Claude Code ejecutas /context y los Memory files listan CLAUDE.md
  • Abres una sesión nueva y preguntas «¿cómo se inicia el proyecto?»; la IA acierta sin que tengas que explicar nada
  • AGENTS.md y CLAUDE.md tienen contenido coherente (por importación o sincronización), sin reglas contradictorias entre sí

Advertencias sobre errores comunes ​

❌ Escribir un texto interminable ​

Cuanto más largo el manual, menos capta la IA lo esencial. Claude Code recomienda oficialmente mantener cada CLAUDE.md por debajo de 200 líneas: demasiado largo consume contexto y reduce el grado de seguimiento. Codex también tiene un límite total: cuando varias guías suman 32 KiB (valor por defecto), se detiene la carga.

Forma correcta: escribe solo los hechos que la IA no puede adivinar (comandos, convenciones, prohibiciones), un elemento por línea, limitándote a unas decenas de líneas.

❌ Escribir solo principios y no comandos ​

«El código debe ser ordenado» es una frase vacía que la IA no puede ejecutar.

Forma correcta: escribe instrucciones verificables: «inicia con pnpm dev, prueba con pnpm test», «los manejadores de API van en src/api/handlers/».

❌ Claude Code no ve AGENTS.md ​

Causas habituales: hay un CLAUDE.md (o CLAUDE.local.md) a nivel de proyecto en el directorio de trabajo o en un nivel superior, así que Claude Code solo lee CLAUDE.md y el ~/.claude/CLAUDE.md a nivel de usuario no cuenta; o la versión es anterior a la v2.1.277.

Lo correcto: claude --version para confirmar la versión; /context para ver qué archivos se cargan realmente, /memory para listar la ubicación de los archivos de memoria en cada sitio; seguir el paso 3 e importar con @AGENTS.md para conectarlos. Además, ten en cuenta: OpenCode v2.3.1 (2026-11-18) en adelante vuelve a leer CLAUDE.md, pero solo como respaldo cuando no hay AGENTS.md en el directorio; si se establecen las variables de entorno OPENCODE_DISABLE_CLAUDE_CODE o OPENCODE_DISABLE_CLAUDE_CODE_PROMPT, se omiten todos los CLAUDE.md. Por lo tanto, sigue rigiendo AGENTS.md, y lo más seguro es configurar ambos archivos.

❌ Verificar en una sesión antigua ​

Tras modificar el manual, preguntas a la IA de inmediato en la sesión actual y lo que responde siguen siendo las reglas antiguas.

Forma correcta: tras cambiar el archivo, abre una sesión nueva para probar; en Claude Code también puedes ejecutar directamente /context para confirmar que el archivo se cargó.

Técnicas avanzadas ​

  • Deja que la IA escriba el borrador por ti: ejecuta /init dentro de Claude Code; analiza el código base y genera automáticamente un CLAUDE.md inicial con comandos de construcción, instrucciones de prueba y convenciones del proyecto; si el archivo ya existe, da sugerencias de mejora sin sobrescribirlo.
  • Hazle una revisión médica a tus reglas: desde Claude Code v2.1.283 está disponible /doctor prompt-audit, que hace que Claude revise el archivo de instrucciones en busca de contenido obsoleto, contradictorio o que referencie archivos inexistentes.
  • Anulaciones por directorio (Codex): coloca un AGENTS.override.md en un subdirectorio y Codex lo leerá con prioridad; si el repositorio ya tiene archivos como TEAM_GUIDE.md, puedes registrarlos como nombres de archivo alternativos en project_doc_fallback_filenames de ~/.codex/config.toml.
  • Cuelga más guías (OpenCode): añade archivos, globs o URLs al array instructions de opencode.jsonc para que se carguen junto con AGENTS.md.
  • Preferencias del proyecto solo para ti:Claude Code admite CLAUDE.local.md en el directorio raíz, donde pones preferencias personales del proyecto; recuerda añadirlo a .gitignore.

Resumen de esta lección ​

✅ A estas alturas ya has:

  • Escrito un AGENTS.md: cuatro bloques de contenido, una línea por punto, colocado en la raíz del proyecto y subido a git
  • Configurado para Claude Code un CLAUDE.md que lo referencia, de modo que tres herramientas leen el mismo conjunto de reglas
  • Verificado con una sesión nueva: sin que se lo indiques, la IA ya sabe cómo arrancar el proyecto y qué convenciones respetar

Repaso de los archivos clave:

ArchivoUbicación recomendadaFunción
AGENTS.mdRaíz del proyectoÚnica fuente de verdad; Codex y OpenCode lo leen directamente
CLAUDE.mdRaíz del proyectoArchivo de memoria de Claude Code, usa @AGENTS.md para importar el contenido compartido
~/.claude/CLAUDE.mdDirectorio principal del usuarioPreferencias personales, aplican a todos tus proyectos
~/.codex/AGENTS.mdCodex Directorio principalCodex Guía global, heredada por todos los repositorios
~/.config/opencode/AGENTS.mdOpenCode Directorio de configuraciónOpenCode Guía global, aquí van las reglas aplicables en todas partes

Para recordarlo en una frase: AGENTS.md es el manual del proyecto para la IA: escríbelo concreto, colócalo en la raíz y mantenlo único.

Avance de la próxima lección ​

El manual hizo que la IA entienda tu proyecto; en la próxima lección le daremos más capacidades: Vercel × agentes de codificación con IA: el trío de Plugin, Skills y MCP.

Aprenderás:

  • Qué son el Plugin, las Skills y el MCP de Vercel, el trío preparado para agentes de codificación con IA
  • Cómo conectarlos a tu agente con los comandos oficiales
  • Qué se puede conectar entre la IA y tus proyectos de Vercel una vez integrados

Si quieres aclarar primero «qué escribir», repasa Primero planifica, luego actúa: convierte una idea de una frase en una lista de requisitos; las operaciones básicas de Claude Code se ven en Claude Code Uso de Claude Code: el agente de programación con IA en la terminal.

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.