Subagente sin CLAUDE.md en Claude Code con omitClaudeMd
· 6 min de lectura
Para crear un subagente sin CLAUDE.md en Claude Code, agrega omitClaudeMd: true al frontmatter del archivo .claude/agents/<nombre>.md, o al JSON de --agents. Necesitas Claude Code 2.1.271 o posterior. El subagente arranca sin tus CLAUDE.md de usuario, proyecto y local, pero los archivos de política gestionada se cargan igual. Explore y Plan ya lo hacen por defecto.
Claude Code 2.1.271, publicada el 14 de septiembre de 2026, añadió un campo nuevo a la definición de subagentes: omitClaudeMd. Con `omitClaudeMd: true`, ese subagente arranca sin tus archivos CLAUDE.md de usuario, de proyecto y locales.
Hasta esa versión, solo los subagentes integrados Explore y Plan se saltaban esos archivos; según la documentación oficial, para que la investigación sea rápida y económica. Cualquier otro subagente, integrado o tuyo, los cargaba todos.
Para qué sirve un subagente sin CLAUDE.md
Tu CLAUDE.md suele traer reglas pensadas para la conversación principal: el tono de las respuestas, el formato de los commits, las convenciones de estilo del proyecto. Un subagente que solo investiga o revisa no necesita nada de eso para hacer su tarea.
La documentación recomienda el campo para subagentes que sacan todo lo que necesitan del prompt de delegación, es decir, del mensaje con el que Claude les pasa la tarea. Dos casos típicos:
Investigación: buscar en el código, leer documentación y devolver un resumen con rutas de archivo.
Revisión: leer un cambio y devolver hallazgos con el criterio escrito en su propio prompt.
Qué necesitas
Claude Code 2.1.271 o posterior. Compruébalo con `claude --version`. La documentación marca esa versión como la mínima para el campo.
Si instalaste con npm, revisa la etiqueta. El 15 de septiembre de 2026, en el registro de npm la etiqueta stable seguía en 2.1.236 y latest ya iba por 2.1.272. Para actualizar: `npm install -g @anthropic-ai/claude-code@latest`.
Si usas el instalador nativo, manda el ajuste `autoUpdatesChannel`: en "stable" la versión suele ir alrededor de una semana por detrás.
Paso a paso: crea tu subagente sin CLAUDE.md
1. Elige el alcance. Un archivo en `.claude/agents/` vale solo para ese proyecto; uno en `~/.claude/agents/` vale para todos tus proyectos.
2. Crea un archivo Markdown en esa carpeta, por ejemplo `.claude/agents/investigador.md`.
3. Escribe el frontmatter con `name` y `description`, que son obligatorios, los campos opcionales que quieras y `omitClaudeMd: true`. El prompt de sistema del subagente va en el cuerpo, debajo del frontmatter.
Este es el archivo completo:
El frontmatter va entre dos líneas que solo tienen tres guiones (---). Estas son sus líneas, una por renglón:
name: investigador
description: Investiga en el código y en la documentación y devuelve un resumen con rutas de archivo. Úsalo para preguntas de solo lectura.
tools: Read, Grep, Glob
model: sonnet
omitClaudeMd: true
Debajo del segundo --- va el prompt de sistema, tal cual:
«Eres un investigador de solo lectura. No modificas archivos.»
«Recibes una pregunta concreta. Busca con Grep y Glob, lee solo lo necesario y responde con:»
1. La respuesta en dos o tres frases.
2. Las rutas de archivo y las líneas que la sostienen.
3. Lo que no pudiste confirmar.
«Todo lo que necesitas saber del proyecto viene en el mensaje con el que te delegan la tarea.»
4. Guarda el archivo. Claude Code vigila `~/.claude/agents/` y `.claude/agents/` y aplica los cambios en unos segundos, sin reiniciar. La excepción: si es el primer archivo de una carpeta `agents` que no existía al abrir la sesión, reinicia Claude Code.
5. Delégale una tarea. Escribe «Usa el subagente investigador para encontrar dónde se valida el login», o menciónalo con `@agent-investigador` para garantizar que esa tarea la haga él.
Si no quieres crear un archivo, el mismo campo funciona en el JSON de `--agents`, que define subagentes solo para esa sesión. Ahí el prompt de sistema va en el campo `prompt`:
claude --agents '{
"investigador": {
"description": "Investiga en el código y devuelve un resumen con rutas de archivo.",
"prompt": "Eres un investigador de solo lectura. No modificas archivos.",
"tools": ["Read", "Grep", "Glob"],
"model": "sonnet",
"omitClaudeMd": true
}
}'
Cómo comprobar que funciona
La documentación no trae un comando que liste qué archivos cargó un subagente. Lo que sí puedes verificar:
La versión. `claude --version` tiene que devolver 2.1.271 o una posterior.
Que la tarea fue a tu subagente. En el transcript, la delegación aparece como una fila con el nombre del subagente y una descripción corta de la tarea, del estilo `investigador(Buscar la validación del login)`. Si ves otro nombre, Claude eligió otro subagente.
Límites y trampas
La política gestionada se carga igual. Si tu organización despliega un CLAUDE.md de política gestionada, el subagente lo recibe. Solo los subagentes definidos en los ajustes gestionados arrancan sin ninguno.
Con --agent no hace nada. El campo se ignora cuando el agente corre como sesión principal con `claude --agent` o con el ajuste `agent`. Ahí tus CLAUDE.md se cargan como siempre.
Una regla necesaria no llega sola. Si una norma tiene que cumplirse dentro del subagente, por ejemplo ignorar la carpeta `vendor/`, la documentación indica repetirla en el prompt que le das a Claude al delegar. Si aplica siempre, escríbela en el prompt de sistema del subagente.
El estado de git sigue llegando. omitClaudeMd solo quita los CLAUDE.md. Según la documentación, no puedes cambiar qué subagentes reciben el estado de git: solo Explore y Plan se lo saltan.
No hay cifra de ahorro. Ni la documentación ni el changelog dicen cuánto contexto te ahorras.
Preguntas frecuentes
¿Qué hace omitClaudeMd en Claude Code?
omitClaudeMd es un campo de la definición de subagentes que llegó en Claude Code 2.1.271. Con omitClaudeMd: true en el frontmatter o en el JSON de --agents, el subagente arranca sin los CLAUDE.md de usuario, de proyecto y locales. Los archivos de política gestionada se siguen cargando, salvo en los subagentes definidos en los ajustes gestionados.
¿Qué versión de Claude Code necesito para usar omitClaudeMd?
Necesitas Claude Code 2.1.271 o posterior, y lo compruebas con claude --version. El 15 de septiembre de 2026, en el registro de npm la etiqueta stable seguía en 2.1.236 y latest iba por 2.1.272. Si instalaste con npm, actualiza con npm install -g @anthropic-ai/claude-code@latest.
¿Funciona omitClaudeMd si lanzo el agente con claude --agent?
No. La documentación indica que el campo se ignora cuando el agente corre como sesión principal, con claude --agent o con el ajuste agent, y en ese caso tus CLAUDE.md se cargan de forma normal. omitClaudeMd solo actúa cuando el agente trabaja como subagente al que Claude le delega una tarea.
¿Cómo hago que un subagente sin CLAUDE.md cumpla una regla del proyecto?
Repite la regla en el prompt que le das a Claude al delegar, que es lo que recomienda la documentación, o escríbela en el prompt de sistema del subagente si debe cumplirse siempre. Tu conversación principal sigue teniendo el CLAUDE.md completo cuando lee los resultados, así que la mayoría de las reglas no necesita llegar al subagente.
¿Los subagentes Explore y Plan cargan mi CLAUDE.md?
No. Los subagentes integrados Explore y Plan se saltan tus archivos CLAUDE.md y el estado de git de la sesión principal; según la documentación, para que la investigación sea rápida y económica. El resto de subagentes, integrados o personalizados, cargan tus CLAUDE.md salvo que su definición traiga omitClaudeMd: true.