Para qué proyectos sirven los subagents de Claude Code: casos de uso, límites y errores comunes

Cuando alguien ve por primera vez los subagents de Claude Code, suele pensar que son “varias IA escribiendo código a la vez”. Esa idea es solo media verdad.

En realidad, los subagents resuelven tres problemas: aislar contexto, dividir subtareas independientes y mantener reglas estables para un rol concreto. No son un acelerador necesario para todo proyecto. Si la tarea es pequeña, el límite no está claro o varios agents van a pelear por los mismos archivos, dividir en subagents puede empeorar el resultado.

Este artículo responde desde la perspectiva de proyecto: para qué sirven los subagents de Claude Code, cuándo usarlos, cuándo evitarlos y cómo diseñar un subagent de proyecto.

Quick Answer

Tipo de proyecto o tarea	Encaje	Motivo
Primer análisis de un código grande	Muy bueno	Se puede dividir API, base de datos, frontend y tests
Investigación paralela por módulos	Muy bueno	Las subtareas son independientes
Revisión de PR o diff grande	Muy bueno	Se separan bug, seguridad, rendimiento y cobertura
Fallos de tests y análisis de logs	Bueno	Un rol enfocado filtra ruido
Docs, migraciones, upgrades de dependencias	Bueno	Puede leer material y resumir impacto
Bug pequeño de un archivo	Malo	El coste de coordinación supera el beneficio
Exploración vaga	Malo	Los subagents necesitan límites claros
Varios agents editando los mismos archivos	Alto riesgo	Probables conflictos y sobrescrituras

En una frase: los subagents encajan con tareas que se pueden separar, completar de forma independiente y devolver como conclusiones o resultados acotados.

El valor principal es gestionar contexto

La documentación de Claude Code describe los subagents como instancias independientes. El agent principal delega una tarea enfocada; el subagent trabaja en su propio contexto y devuelve el resultado.

Su valor no es solo velocidad:

Aislamiento de contexto: logs, salidas de tests, docs y escaneos no saturan la sesión principal.
Roles estables: code-reviewer siempre revisa read-only; test-runner ejecuta tests y explica fallos.
Control de permisos: algunos subagents pueden limitarse a Read/Grep/Glob.
Investigación paralela: varias direcciones independientes pueden correr a la vez.
Memoria de proyecto: las reglas del equipo pueden vivir en .claude/agents/.

Antes de preguntar “¿será más rápido?”, pregunta si la tarea genera mucho contexto y si puede dividirse en roles claros.

Buen encaje 1: mapear un código grande

Cuando heredas un repositorio desconocido, el primer problema es saber dónde mirar.

Puedes delegar exploraciones:

api-reader: rutas, controladores, autenticación.
db-reader: schema, migraciones, modelos ORM.
frontend-reader: páginas, estado, entradas de componentes.
test-reader: framework de tests, cobertura, comandos.

Cada subagent devuelve 5 a 10 conclusiones. La sesión principal mantiene un mapa, no todo el detalle del repositorio.

Esto encaja con monorepos, sistemas legacy, repos frontend/backend mixtos, scripts dispersos y evaluaciones de deuda técnica.

Si diseñas un handoff entre Codex y Claude Code, puedes poner esta lectura del repo del lado de subagents de Claude Code y entregar el mapa a Codex para cambios más largos: /es/2026/07/10/codex-claude-code-task-handoff-guide/.

Buen encaje 2: dividir revisión de código por roles

La revisión se divide naturalmente por preocupación:

bug-reviewer: errores lógicos, nulls, límites, regresiones.
security-reviewer: permisos, validación, secretos, inyección, bypass.
performance-reviewer: bucles, queries, caché, rendering, concurrencia.
test-reviewer: si las pruebas cubren riesgos reales.

El límite importante: los subagents de revisión deberían ser read-only por defecto.

Flujo seguro:

La sesión principal reúne el diff.
Varios subagents read-only revisan.
La sesión principal fusiona conclusiones.
Un implementador explícito aplica arreglos pequeños.

Para un flujo cerrado de revisión entre Claude Code y Codex, mira: /es/2026/07/10/claude-code-codex-code-review-workflow/.

Buen encaje 3: fallos de tests y logs ruidosos

Las pruebas fallidas producen mucha salida. En E2E, integración y CI, el error útil suele estar escondido.

Un test-runner puede:

ejecutar el comando indicado;
extraer casos fallidos;
resumir la causa probable;
señalar archivos relacionados;
no corregir código directamente.

subagent	Herramientas sugeridas	Tarea
`test-runner`	`Bash, Read, Grep`	Ejecutar tests y explicar fallos
`log-analyzer`	`Read, Grep, Glob`	Analizar logs y stack traces
`coverage-reviewer`	`Read, Grep, Glob`	Encontrar pruebas faltantes y ramas riesgosas

Si ya usas hooks de Claude Code para ejecutar tests, los hooks pueden disparar la ejecución y el subagent explicar el fallo: /es/2026/07/10/claude-code-hooks-auto-run-tests/.

Buen encaje 4: análisis de impacto antes de refactorizar

Un refactor grande no debería empezar editando. Los subagents sirven para reconocimiento read-only.

Pueden responder:

qué archivos dependen de la interfaz antigua;
qué tests cubren esa lógica;
qué rutas de llamada son frágiles;
si docs, scripts o configs necesitan cambios;
dónde conviene añadir tests antes de tocar código.

La regla: el subagent entrega impacto, no parches.

La sesión principal decide después si cambiar todo, dividir fases o añadir tests primero. Esto también ayuda a recuperar tareas largas: /es/2026/07/10/ai-agent-long-task-resume-guide/.

Mal encaje: no dividas todo

Los subagents tienen coste: más contexto, espera y coordinación.

Normalmente no convienen para:

1. Problemas pequeños

Typos, imports, una clase CSS, un null check o una config se resuelven mejor en la sesión principal.

2. Requisitos vagos

“Optimiza este proyecto” o “mejora esta página” requieren aclarar objetivo, restricciones y aceptación antes de delegar.

3. Tareas con negociación constante

Los subagents funcionan mejor con trabajo independiente, no con diseño que cambia cada dos líneas.

4. Varios agents editando los mismos archivos

Mejor que revisen read-only y que un solo ejecutor aplique cambios.

5. Operaciones externas de alto riesgo

Producción, cuentas reales, APIs pagas, borrado, permisos, emails o mensajes requieren límites estrictos y puntos de confirmación.

Diseño de subagents de proyecto

Claude Code permite escribir subagents como Markdown. Los de proyecto suelen vivir en:

1

.claude/agents/

Los globales en:

1

~/.claude/agents/

Un subagent de proyecto debería capturar comandos de test, estructura, prioridades de revisión, archivos prohibidos y formato de salida.

Ejemplo mínimo read-only:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


---
name: code-reviewer
description: Use when the task needs a read-only review of code changes for bugs, regressions, security risks, and missing tests.
tools: Read, Grep, Glob
---

# Code Reviewer

Only perform read-only review. Do not modify files.

Focus on:

- logic errors and edge cases
- regression risk
- security and permission issues
- missing tests
- inconsistency with project style

Output:

1. List high-risk issues first.
2. Include file paths and reasons.
3. If no issue is found, say so clearly.
4. Do not output long rewritten code.

La parte más importante es description, porque Claude Code la usa para decidir cuándo delegar.

Conjunto común de subagents

Empieza con 3 a 5 roles:

Nombre	Herramientas	Propósito
`code-reviewer`	`Read, Grep, Glob`	Revisión read-only de bugs y regresiones
`test-runner`	`Bash, Read, Grep`	Ejecutar tests y explicar fallos
`docs-researcher`	`Read, Grep, Glob`	Resumir docs, migraciones y convenciones
`security-reviewer`	`Read, Grep, Glob`	Revisar permisos, inputs, secretos e inyección
`refactor-planner`	`Read, Grep, Glob`	Analizar impacto antes de cambios grandes

Si un subagent devuelve consejos genéricos, su rol es demasiado amplio.

Cómo llamar un subagent

Puedes llamarlo explícitamente:

1

Use the code-reviewer subagent to review the current diff. Do not modify files.

También puedes nombrarlo como @code-reviewer o iniciar:

1

claude --agent code-reviewer

En tareas críticas, no dependas solo de delegación automática. Di “read-only”, “do not modify files” y “return conclusions only”.

Fórmula de decisión

Haz cinco preguntas:

¿La tarea se puede dividir por módulo, directorio, rol o preocupación?
¿Las subtareas son relativamente independientes?
¿Cada subtarea puede devolver una conclusión clara?
¿Se necesitan permisos de herramientas diferentes?
¿El beneficio de aislar contexto supera el coste en tokens y espera?

Si tres o más son sí, prueba subagents. Si solo una es sí, probablemente no conviene.

Checklist de errores

Usa nombres concretos, no helper, assistant o worker.
En description, escribe el caso de activación.
Los subagents de revisión deberían ser read-only.
Los subagents que editan deben tener un alcance pequeño.
En refactors grandes, analiza impacto primero.
Los subagents de test deben resumir fallos, no devolver logs completos.
La sesión principal fusiona las salidas.
Limita herramientas y alcance en acciones riesgosas.
Reglas de proyecto en .claude/agents/; hábitos personales en ~/.claude/agents/.
Elimina subagents de baja calidad o duplicados.

Resumen

Los subagents de Claude Code encajan mejor en tareas medianas o grandes con módulos, roles y límites claros.

Sirven para mapear repositorios, revisión especializada, análisis de fallos de tests, evaluación de impacto de migraciones y reutilización de roles de proyecto. No sirven tanto para ediciones pequeñas, requisitos vagos, negociación constante o varios agents escribiendo los mismos archivos.

Un buen subagent no se mide por cantidad, sino por límites. La sesión principal mantiene objetivos, decisiones y entrega final; el subagent investiga un problema local con profundidad y limpieza. Usado así, pasa de ser “otra IA más” a una parte fiable del workflow.