agents-md: Claude Code AGENTS.md como instrucciones del proyecto
Carga AGENTS.md como instrucciones del proyecto, igual que CLAUDE.md, con cuatro modos en /config.
Permisos
- Intercepta llamadas a herramientasVe cada llamada a herramienta que hace Claude (tool.call / tool.check) y podría bloquearla o modificarla.
- Modifica la interfazDibuja en la interfaz de Claude Code: bandas, paneles, texto de estado, avisos (ui.render / $.ui.*).
- probado con
- v2.1.310
- última prueba
- requiere
- Claude Code ≥ 2.1.287
- superficies
- ninguna
- código fuente
- Anthropic (anthropics)
Instalar dentro de Claude Code:
git clone https://github.com/anthropics/claude-code
claude --plugin-dir ./claude-code/mods/agents-md¿Qué hace este mod?
agents-md es un mod de Anthropic (anthropics/claude-code) que da a Claude Code AGENTS.md como fuente de instrucciones. Muchos repositorios guardan sus instrucciones para agentes en AGENTS.md, mientras que Claude Code lee CLAUDE.md. El mod entrega los archivos AGENTS.md a Claude Code como archivos de instrucciones del proyecto, de modo que el modelo los ve en el mismo lugar y con el mismo marco que un CLAUDE.md.
Una opción, instructionFiles, decide qué se carga:
claude-md: soloCLAUDE.md, como hoy. El mod no añade nada.claude-md-or-agents-md(por defecto): un proyecto sinCLAUDE.mdpropio recibe en su lugar sus archivosAGENTS.md.claude-md-and-agents-md: cadaAGENTS.mdse carga junto aCLAUDE.md.managed-only: se descartan los archivos de instrucciones del proyecto y los tuyos; se mantienen elCLAUDE.mdgestionado de la organización y la memoria.
Los archivos se buscan desde la raíz del sistema de archivos hasta el directorio de trabajo, y cuentan tanto AGENTS.md como .claude/AGENTS.md. Cuando Claude lee un archivo en un subdirectorio, el AGENTS.md de ese directorio se adjunta al resultado, como Claude Code hace con un CLAUDE.md anidado. El mod no dibuja nada en pantalla; su efecto está en lo que el modelo sabe.
Demo
La grabación inicia Claude Code con el mod cargado en el pequeño proyecto de demostración. Antes del clip, una línea de preparación oculta escribe un AGENTS.md breve en el proyecto (dos reglas: los mensajes de commit empiezan con el id del ticket, como DEMO-123, y se ejecuta npm test antes de cada commit). El proyecto no tiene CLAUDE.md. En el clip preguntamos: «Without reading any file: what does my AGENTS.md say about commit messages? One sentence.» Claude responde en unos dos segundos y sin llamar a ninguna herramienta que los mensajes de commit empiezan con el id del ticket, como DEMO-123, porque el archivo ya estaba en su contexto.
Instalación
Usa cualquiera de los métodos del bloque de instalación; instalan desde el repositorio anthropics/claude-code. El repositorio no tiene un marketplace.json que liste este plugin, así que el bloque usa el propio repositorio como origen. El modo por defecto no necesita configuración: inicia una sesión en un proyecto con AGENTS.md y sin CLAUDE.md.
$ install agents-md
Requiere Claude Code ≥ 2.1.287
Se instala desde el marketplace del autor: anthropics/claude-code
1.Pruébalo sin instalarlo
git clone https://github.com/anthropics/claude-code claude --plugin-dir ./claude-code/mods/agents-mdCarga el mod solo para una sesión. No se añade nada a tu configuración.
Cómo funciona
hooks/register.ts es el único módulo de hooks/hooks.json; todo lo demás bajo hooks/ son piezas auxiliares que importa. En los dos modos de carga, un hook prompt.context recibe los archivos de instrucciones que Claude Code ya cargó, busca AGENTS.md hacia arriba con $.fs.ancestors y responde con la lista más los archivos nuevos como archivos project. Esta es la búsqueda, de hooks/register.ts:
const found = isClaudeProject
? NONE
: await $.fs.ancestors({ names: Names.AGENTS_NAMES }).catch(() => {
isWalkFailed = true
return NONE
})
const added = Files.unseenFiles(Files.filesOf(found), handed)unseenFiles descarta un archivo cuya ruta Claude Code ya tiene, o cuyo texto es igual al de un archivo de proyecto entregado (por ejemplo, un CLAUDE.md que es un enlace simbólico a AGENTS.md). Un hook tool.call sobre Read deja terminar la lectura y, para un archivo bajo la raíz del proyecto, adjunta los AGENTS.md de los directorios entre la raíz y ese archivo como Contents of <path>:, una vez por bucle de agente. Un hook agent.spawn para forks copia el conjunto ya entregado al padre, para que un fork no reciba los mismos archivos dos veces.
Personalízalo
La opción es la fila «Project instructions» de /config, un selector con los cuatro valores. A mano se define en la configuración de usuario, en --settings o en la configuración gestionada (el .claude/settings.json de un proyecto no se lee para opciones de plugins):
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}Con claude --plugin-dir mods/agents-md, la misma entrada usa la clave "agents-md". La clave antigua projectInstructions se sigue respetando hasta que instructionFiles se fija en un valor distinto del predeterminado. El README del autor enumera ocho puntos en los que AGENTS.md aún difiere de CLAUDE.md; por ejemplo, los directorios de --add-dir no aportan AGENTS.md y /memory no conoce esos archivos.
Permisos y seguridad
Leímos todos los archivos que el plugin puede ejecutar: plugin.json, hooks/hooks.json, hooks/register.ts, todos los módulos auxiliares de hooks/ que importa y las pruebas. No hay package.json, script de instalación, binario ni código empaquetado, y las fuentes no contienen caracteres no ASCII.
- Lee archivos.
$.fs.ancestorsleeAGENTS.mdy.claude/AGENTS.mdhacia arriba en el árbol (y buscaCLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md). Su texto llega al modelo como instrucciones del proyecto, así que unAGENTS.mden el que no confías puede dirigir a Claude, igual que unCLAUDE.md. - Lee variables de entorno.
HOME,USERPROFILE,CLAUDE_CODE_SIMPLEyCLAUDE_CODE_DISABLE_ATTACHMENTS, solo para resolver rutas con~y omitir adjuntos donde Claude Code no adjunta nada. No escribe variables de entorno. - Intercepta llamadas a herramientas. El hook
tool.callsobreReady el hookagent.spawnpara forks esperan a la llamada y devuelven su resultado; solo añaden contexto tras una lectura correcta. Nunca deniegan una llamada.claude plugin validateseñala que a ambos hooks les falta un.catch. - Telemetría. Llama a
$.telemetry.logy$.telemetry.markcon contadores y opciones cerradas (modo, número de archivos e importaciones, longitud total, algunas marcas). El README dice que no incluyen ruta ni texto y que se descartan donde no está el plugin de telemetría de Anthropic. No revisamos ese plugin. - Sin red, sin procesos, sin escrituras, sin demonios. El mod no usa
fetch, shell, escritura con$.fsni temporizadores en segundo plano. Solo escribe una línea de registro de depuración con$.ui.log:no CLAUDE.md found; AGENTS.md loaded: <paths>. - Licencia. El
LICENSE.mddel repositorio dice «© Anthropic PBC. All rights reserved» y sujeta el uso a los Commercial Terms de Anthropic, por eso la página esredistributable: false: enlazamos el código y no lo replicamos.
claude plugin validate no informó de errores. Solo mostró una advertencia no bloqueante de «sin icono» para el directorio del plugin, las dos notas de .catch ya citadas y el consejo de que el README no tiene una línea de instalación. Las 5 pruebas del autor pasaron en Claude Code 2.1.310.
- Intercepta llamadas a herramientas
- Ve cada llamada a herramienta que hace Claude (tool.call / tool.check) y podría bloquearla o modificarla.
- Modifica la interfaz
- Dibuja en la interfaz de Claude Code: bandas, paneles, texto de estado, avisos (ui.render / $.ui.*).
Compatibilidad y solución de problemas
Comprobado con Claude Code 2.1.310 en macOS (validate, pruebas y grabación de la demo). El README lo describe como plugin integrado (agents-md@builtin), así que una versión de Claude Code que lo incluya puede cargarlo ya; /plugin lista los integrados y ahí se puede desactivar. Si tu AGENTS.md no se carga:
- Busca un
CLAUDE.md,.claude/CLAUDE.mdoCLAUDE.local.mddesde la raíz hasta el directorio de trabajo. En el modo por defecto, cualquiera de ellos hace que el mod se aparte. - Comprueba que la opción de
/configno seaclaude-mdnimanaged-only. - En ejecuciones con
--bareo--safe-mode, o conCLAUDE_CODE_DISABLE_CLAUDE_MDS, Claude Code no carga archivos de instrucciones; conCLAUDE_CODE_DISABLE_ATTACHMENTSse omiten los adjuntos anidados. - En un cliente ligero el mod no encuentra nada, porque los archivos del espacio de trabajo son remotos.
- Tras cambiar la opción, los archivos nuevos llegan con el siguiente contexto que construya Claude Code: el siguiente turno,
/clearo una compactación.
Preguntas frecuentes
- ¿Claude Code lee AGENTS.md sin este mod?
- Según el README del mod, el motor solo carga CLAUDE.md y el plugin añade AGENTS.md encima. Con la opción en claude-md el plugin no añade nada y CLAUDE.md se carga como siempre.
- ¿Qué pasa si mi proyecto tiene CLAUDE.md y AGENTS.md?
- En el modo por defecto, claude-md-or-agents-md, el mod se aparta si hay un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en cualquier punto desde la raíz hasta el directorio de trabajo. En claude-md-and-agents-md carga ambos y omite un AGENTS.md que CLAUDE.md ya importa o enlaza.
- ¿Envía el texto de mi AGENTS.md a algún sitio?
- El código no hace llamadas de red ni ejecuta comandos. Solo entrega contadores (número de archivos, de importaciones, longitud total, modo) a un objeto de telemetría. Según el README, esas filas solo existen donde está instalado el plugin de telemetría de Anthropic y no incluyen rutas ni texto de archivos.
- ¿Cómo cambio el modo?
- Abre /config y elige un valor en la fila «Project instructions», o define instructionFiles bajo pluginConfigs en tu configuración de usuario. El cambio recarga el módulo y el siguiente contexto que construya el motor usa el nuevo modo.
- ¿Puedo reutilizar el código en mi propio plugin?
- No copiándolo. El LICENSE.md del repositorio dice «All rights reserved» y remite a los Commercial Terms de Anthropic, así que esta página enlaza el código y no lo replica.
# Mods relacionados
DestacadoContext Inspector
Muestra qué llena el contexto de Claude Code, cuánto es desperdicio y qué conservó la compactación.
- estado
- panel
- aviso
- Escribe archivos
- Intercepta llamadas a herramientas
- Lee tus prompts
- Modifica la interfaz
- Añade comandos/herramientas
probado con v2.1.303