Subagentes Claude Code: archivos .claude/agents sin ruido

Un subagente hace un tipo de trabajo en su propia ventana y devuelve un resumen. Usa uno cuando una búsqueda, una ejecución de prueba, o una revisión archivo por archivo enterraría la conversación que aún necesitas. Este laboratorio escribe cinco agentes que puedes comprometer. Los comandos de sesión y flags están en la hoja de trucos Claude Code.

Qué es un subagente

Cada subagente personalizado es un archivo Markdown. El front matter establece el nombre al que Claude delega, las herramientas que puede usar, y el modelo en el que se ejecuta. El cuerpo reemplaza el prompt del sistema normal de Claude Code para ese agente. Aún recibe detalles básicos del entorno como el directorio de trabajo.

La sesión padre ve una fila de herramientas corta, el nombre del agente, y el resultado final. Las lecturas intermedias se quedan en la transcripción del subagente bajo los archivos de sesión del proyecto en ~/.claude. Esa división es la razón para crear un agente que de otro modo repromptearías cada día.

Los agentes incorporados ya existen. Explore busca el árbol sin editar. Plan recopila contexto mientras la sesión principal está en modo plan. No necesitas redefinirlos. Un agente de proyecto o usuario cuyo name es Explore sobrescribe el incorporado.

Los subagentes son una forma de trabajo agentivo: un modelo, una lista de herramientas, y una condición de parada. No son servidores MCP. MCP expone herramientas externas. Un subagente es otra sesión Claude con un prompt más estrecho.

Formato de archivo

Solo name y description son requeridos. Claves no reconocidas se ignoran. name es como máximo 256 caracteres y no puede contener :, porque los nombres con dos puntos se reservan para plugins. El nombre del archivo no tiene que coincidir con name, pero coincidir lo hace carpeta legible.

Otros campos soportados que usarás:

isolation: worktree se ramifica desde la rama por defecto del repositorio, no desde tu HEAD actual. El worktree se elimina cuando el agente no hace cambios. Déjalo fuera cuando el agente deba ver la rama que tienes checada.

Un cd dentro del agente no persiste entre llamadas shell, y no cambia el directorio de la sesión principal.

Dónde vive el archivo

Los agentes de proyecto se descubren caminando hacia arriba desde el directorio de trabajo hasta la raíz del repo. Si dos de esas carpetas definen el mismo name, la más cercana al directorio de trabajo gana. Claude Code también escanea subcarpetas, así que .claude/agents/review/security.md es un diseño válido. Comprende agentes de proyecto. Mantén experimentos personales en ~/.claude/agents/.

Claude Code vigila ~/.claude/agents/ y .claude/agents/ del proyecto. Las ediciones se muestran en segundos. Tres casos aún necesitan reinicio: el directorio agents fue creado después de que la sesión inició, el archivo está dentro de un directorio que agregaste con --add-dir, o la sesión se inició con --disable-slash-commands.

/agents en versiones actuales imprime un recordatorio para editar estos archivos. En Claude Code v2.1.197 y anteriores abrió un UI de gestor. Los agentes en segundo plano ya ejecutándose se listan con /tasks, que la hoja de trucos incluye.

Verifica front matter con claude plugin validate .claude/agents. Esa verificación necesita Claude Code v2.1.233 o posterior. Reporta archivos que no se interpretan. No se queja de un name faltante si el YAML mismo se interpreta.

Cuándo Claude delega

Claude compara tu solicitud, la description del agente, y el contexto actual. Una descripción que dice cuándo ejecutar es más útil que una descripción que solo dice qué es el agente. Los docs llaman la atención sobre la frase «usa proactivamente» como una forma de alentar la delegación. Mantén descripciones cortas. Si las descripciones combinadas de tus agentes personalizados superan 15,000 tokens, Claude Code advierte al iniciar y aún carga cada agente. Mueve instrucciones largas al cuerpo, que carga solo cuando ese agente se ejecuta.

La delegación es una opción. Una descripción vaga pierde frente a Explore o a la sesión principal haciendo el trabajo mismo.

La invocación explícita tiene tres niveles:

La sintaxis de mención que muestra agentes en el autocompletado se ve así:

@"code-reviewer (agent)" mira los cambios de autenticación

También puedes escribir @agent-code-reviewer sin el selector. Mientras escribes esa forma, el menú muestra archivos. La mención aún se resuelve cuando la envías. Tu oración va al padre. El padre escribe el prompt de tarea que el subagente realmente recibe.

Un agente de plugin aparece como un nombre con alcance, por ejemplo @agent-my-plugin:code-reviewer. Si el archivo del plugin se sienta en una subcarpeta, el alcance incluye esa carpeta: my-plugin:review:security.

--agent persiste cuando reanudas la sesión. Si el archivo del agente se ha ido al momento de reanudar, la sesión continúa con las herramientas por defecto y muestra una advertencia.

Los agentes de una sola vez pueden pasarse como JSON. Esta forma es para un lanzamiento único, no para un archivo que comprometas:

claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'

En modo print en v2.1.281 o posterior, --agents puede apuntar a un archivo JSON. Una sesión interactiva rechaza una ruta de archivo allí.

Cinco agentes

Los nombres de herramientas debajo son los que la referencia del subagente usa: Read, Grep, Glob, Edit, Write, y Bash. Listar herramientas es lo que impide que un revisor edite. Un campo tools omitido hereda el conjunto completo de subagentes.

Revisor de código

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Revisa diffs locales por bugs de corrección y tests faltantes. Usa proactivamente después de cambios de código.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Eres un revisor de código para este repositorio.

Ejecuta git status y git diff. Lee solo los archivos que toca el diff, más tests junto a ellos.
Reporta hallazgos como bloqueante, debería-corregir, o nota.
Cada hallazgo necesita una ruta de archivo y el modo de fallo.
Salta detalles de estilo que un formateador arreglaría.
No edites archivos ni hagas commits.

Bash está en este agente para que pueda ejecutar git diff. También puede ejecutar otros comandos shell, así que el prompt tiene que prohibir ediciones y commits. Si necesitas un parador duro, quita Bash y acepta que el padre debe pegar el diff en el prompt de delegación.

Escritor de pruebas

.claude/agents/test-writer.md

---
name: test-writer
description: Agrega o actualiza tests para código que acaba de cambiar. Usa cuando el usuario pida tests o un cambio no tiene cobertura.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
---

Escribes tests que coinciden con el runner y diseño existentes de este repo.

Lee el código cambiado y un archivo de test cercano antes de agregar algo.
Cubre el comportamiento que regresó o que el cambio dice añadir.
No cambies código de producción excepto para exponer un hook de test que el proyecto ya usa.
Ejecuta el comando de test más estrecho que ejecute el nuevo test.
Si falla, corrige el test. Si el código de producción está mal, detente y reporta eso en lugar de reescribirlo.

Auditor de seguridad

.claude/agents/security-auditor.md

---
name: security-auditor
description: Pasada de solo lectura sobre autenticación, secretos, y shell o SQL riesgosos. Usa proactivamente antes de que un cambio sensible de seguridad se merge.
tools: Read, Grep, Glob
model: sonnet
---

Auditas este repositorio por problemas de seguridad que un revisor puede verificar desde el código.

Busca secretos en el árbol, verificaciones de autenticación que confíen en el cliente, inyección de comandos, y queries construidas con concatenación de strings.
Cita el archivo y el patrón. Di cómo podría ser explotado.
No modifiques archivos. No ejecutes exploits. No solicites credenciales.
Si tienes dudas, etiqueta el elemento como needs-human y cita la línea.

Sin Bash ni herramientas de escritura. El agente no puede «solo hacer curl a producción» para verificar una idea.

Escritor de documentación

.claude/agents/doc-writer.md

---
name: doc-writer
description: Actualiza README o docs para que coincidan con el código. Usa cuando el comportamiento cambió y los docs no fueron parte de la edición.
tools: Read, Grep, Glob, Edit, Write
model: haiku
---

Actualizas documentación para que coincida con el código.

Lee primero la implementación. Edita la página de doc existente que ya describe la función.
Describe el comportamiento que quien llama puede observar. No inventes flags o rutas.
Si el código es ambiguo, escribe la pregunta al inicio de tu resumen y salta la edición de doc.

model: haiku mantiene un pase de redacción en el alias más pequeño. El padre puede permanecer en Sonnet. Ver la sección de costo abajo.

Depurador

.claude/agents/debugger.md

---
name: debugger
description: Encuentra por qué un test fallando o comando falla. Usa cuando el usuario pega un stack trace o dice que una verificación está en rojo.
tools: Read, Grep, Glob, Bash, Edit, Write
model: inherit
maxTurns: 12
---

Debugueas una falla.

Reprodúcela con el comando en la tarea antes de que edites.
Cambia la superficie más pequeña que explica la falla.
Re-ejecuta ese comando. Si aún falla, reporta qué intentaste y detente.
No limpies archivos no relacionados.

model: inherit sigue el modelo de sesión. maxTurns: 12 detiene un depurador que está en bucle. El resultado vuelve marcado parcial, y puedes pedir a Claude que reanude ese mismo agente en lugar de comenzar uno nuevo.

Trampas

El agente no ve tu chat. Un subagente no bifurcado comienza limpio. No obtiene tu historial, habilidades que ya ejecutaste, ni archivos que el padre ya abrió. Sí obtiene su propio prompt del sistema, el mensaje de delegación, CLAUDE.md de los niveles que el padre cargó (a menos que omitClaudeMd esté establecido), una fotografía de estado git cuando estés en un repo git, y cualquier habilidad nombrada en skills. Explore y Plan omiten la carga de CLAUDE.md y la fotografía de git.

Pon hechos que el agente no debe perder en la oración que envías, o en su cuerpo Markdown. «Usa el depurador en la falla que discutimos» es una delegación débil. «Usa el depurador en npm test -- auth.test.ts. La aserción es expected 401.» es una completa.

Una bifurcación, que puedes iniciar con /subtask, hereda la conversación padre en su lugar. Esa es la herramienta cuando reafirmar el fondo costaría más que compartirlo. Las bifurcaciones son una función diferente de los cinco archivos arriba.

Pagas por el segundo modelo. Las solicitudes del subagente cuentan para los mismos límites de uso que la sesión principal. Las descripciones de cada agente personalizado también se cargan en el padre, hasta la advertencia de 15,000 tokens. Un escritor de doc haiku es más barato que heredar Opus para un pase de redacción. La ventana de contexto de un subagente es la ventana de su propio modelo, así que un modelo más pequeño es también una ventana más pequeña.

Hay un tope de concurrencia. Una vez que 20 subagentes se ejecutan, otra generación desde la herramienta Agent falla con un error de límite de concurrencia hasta que uno termina. Ese tope necesita Claude Code v2.1.217 o posterior, y sesiones con ultracode encendido están exentas. Subirlo es CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Raramente quieres un tope más alto en una laptop.

Los worktrees no son tu rama. isolation: worktree comienza desde la rama por defecto. Un agente pedido para revisar trabajo sin comprometer en una rama de función no verá ese trabajo si enciendes aislamiento.

El reanude es explícito. Cada delegación comienza una instancia nueva. Cuando el agente termina, el padre recibe un id de agente y puede reanudarlo, manteniendo la transcripción de ese agente. Explore y Plan no devuelven un id. Pide al padre que continúe el code-reviewer, o inicia uno fresco si el primer pase fue suficiente.

Los hooks dentro del agente no son hooks de sesión. El front matter hooks se ejecuta mientras ese agente se ejecuta. Un hook Stop escrito allí se dispara como SubagentStop. Los hooks de proyecto en settings.json también se ejecutan para herramientas que el agente llama, con agent_id y agent_type en la entrada. La guía de hooks muestra el archivo de configuración. Los agentes de plugin ignoran hooks, mcpServers, y permissionMode en su propio front matter.

Una checklist repetida que debe permanecer en el chat principal es un comando slash, no un agente. Un agente es para la mitad ruidosa de una tarea.

Preguntas frecuentes

¿Qué es un subagente Claude Code?

Un subagente es un asistente separado con su propia ventana de contexto, prompt del sistema, lista de herramientas y modelo. Claude delega una tarea secundaria a este y devuelve un resumen, así que volcados de búsquedas y archivos de logs se quedan fuera de la conversación principal. Cada llamada a un subagente es su propia solicitud al modelo y cuenta para los mismos límites de uso que el chat principal.

¿Cómo agrego un subagente personalizado?

Crea un archivo Markdown en .claude/agents/ para un repositorio, o en ~/.claude/agents/ para todos los proyectos en tu máquina. El front matter necesita name y description. tools y model son opcionales. El cuerpo Markdown es el prompt del sistema. Si el directorio agents no existía cuando se inició la sesión, reinicia Claude Code una vez para que se detecte la nueva carpeta.

¿Cómo obligo a Claude a usar un subagente?

Escribe @ y elige el agente del autocompletado, o escribe @agent-code-reviewer en el prompt. Esa mención garantiza que ese agente se ejecute para la tarea. Nombrarlo en una oración, como «usa el subagente code-reviewer», le pide a Claude que delegue pero deja la opción abierta. claude --agent code-reviewer hace que ese agente sea toda la sesión.

¿Por qué mi subagente ignoró la conversación?

Un subagente normal comienza desde un contexto vacío. No ve tu historial de chat, habilidades que ya invocaste, ni archivos que la sesión principal ya leyó. Claude escribe un mensaje de delegación, y el subagente funciona desde ese más su propio prompt y los archivos CLAUDE.md que puede cargar. Una bifurcación es la excepción: hereda la conversación padre.

¿Los subagentes cuestan extra?

Envían sus propias solicitudes en el modelo que asignaste, y esas solicitudes cuentan para los mismos límites de plan o uso de API que la sesión principal. Un revisor haiku gasta menos que uno opus. Los campos de descripción de tus subagentes personalizados también se sientan en el contexto padre, y Claude Code advierte al iniciar cuando esas descripciones juntas superan 15,000 tokens.