Los peores errores no bloquean tu sistema. Simplemente te dan la razón.

Aprendí esto por las malas mientras construía Suhail, un orquestador diseñado para coordinar cinco subagentes especializados dentro de Claude Code. Cada trabajador tenía un rol distinto: un investigador para reunir contexto, un planificador para desglosar tareas, un programador para escribir la implementación, un revisor para inspeccionar el resultado y un auditor para verificar regresiones. La idea era sencilla. El orquestador leería una solicitud, decidiría quién debía hacer qué y luego despacharía el trabajo en paralelo. En su lugar, obtuve un monólogo educado. Una ventana. Un agente. Un modelo muy ocupado haciéndolo todo él mismo mientras insistía en que había delegado el trabajo.

Sin señales de alerta. Sin registros de errores. La ejecución terminó con éxito. Me tomó más tiempo del que me gusta admitir darme cuenta de que Suhail nunca había generado realmente ni un solo subagente.

La trampa de la carpeta agents

La causa raíz era casi insultante por su simplicidad. Había colocado el archivo del orquestador dentro de la carpeta agents.

En Claude Code, esa carpeta no es solo un archivador. Es una forja. Si pones un archivo ahí, el sistema lo convierte en un subagente. Esa identidad conlleva permisos. En aquel momento, los subagentes no podían invocar la herramienta Agent. Eran trabajadores, no capataces. Como Suhail vivía entre los trabajadores, Claude Code lo trató como uno de ellos. Así que, cuando mis instrucciones le decían al orquestador que "despachara al investigador", intentaba usar una herramienta que no poseía.

El software tradicional habría lanzado una excepción en ese mismo instante. Herramienta faltante. Llamada fallida. Pero no en el mundo de los LLM agénticos. Cuando un modelo no encuentra la herramienta adecuada, no se detiene. Improvisa. Suhail vio la instrucción de despachar al investigador, no encontró la herramienta Agent en su kit y simplemente realizó la investigación él mismo. Luego pasó a la planificación. Luego a la programación. Luego a revisar su propio código. Luego a auditar su propia revisión. El resultado parecía razonable. La transcripción parecía la de un proyecto bien gestionado. Pero la arquitectura era una ficción.

Esto es lo que hace que el fallo sea tan peligroso. Un error de ejecución te envía una señal. Una sustitución silenciosa, no. El modelo no está siendo engañoso. Está siendo excesivamente servicial. Ante un objetivo y una brecha de capacidad, llena ese vacío con su propio razonamiento. El resultado es un sistema que informa de éxito mientras elude sistemáticamente la estructura misma que construiste.

La solución, y por qué funcionó

Resolverlo no requirió más que sacar el archivo del orquestador de la carpeta agents y convertirlo en un comando slash.

Los comandos slash en Claude Code residen en la sesión de nivel superior. No son subagentes. Son el punto de entrada para el usuario. Desde esa posición, la herramienta Agent está disponible y el orquestador finalmente puede hacer su trabajo real: generar trabajadores, asignar tareas y esperar a que los resultados reales regresen. Los cinco especialistas comenzaron a activarse en sus propios contextos. El paralelismo ocurrió de verdad. La jerarquía empezó a tener sentido.

Pero la fragilidad subyacente no desaparece solo porque logres estructurar correctamente las carpetas. Incluso con el orquestador en la ubicación correcta, tres riesgos específicos pueden volver a quitarte el suelo bajo los pies.

Tres riesgos que aún acechan

Listas de herramientas curadas. Claude Code te permite definir exactamente a qué herramientas puede acceder un subagente. Esto es útil para la seguridad de mínimo privilegio. Pero también es un arma de doble filo. Si creas una lista de herramientas personalizada para un subagente y olvidas incluir la herramienta Agent, ese subagente se convierte en un nodo hoja. No puede generar más trabajadores. Si tu diseño espera que coordine otra capa de agentes, el despacho fallará de forma tan silenciosa como ocurrió con Suhail. El modelo verá la instrucción, no verá ninguna herramienta y se encargará del trabajo él mismo.

Límites de profundidad. Claude Code impone un límite de anidamiento. Los subagentes pueden generar otros subagentes hasta cinco niveles de profundidad. Al alcanzar ese límite, la herramienta Agent desaparece. Esto no es un error; es una barrera de seguridad contra la recursión descontrolada. Pero si tu arquitectura asume un sexto nivel de delegación, esa capa se disolverá silenciosamente. El agente en el nivel cinco absorberá las tareas destinadas a sus hijos. Tu árbol se convierte en un arbusto, y es posible que no te des cuenta hasta que inspecciones la procedencia de cada resultado.

Session tools. Certain tools, like AskUserQuestion, are bound to the top-level session. They do not travel into subagents. If a dispatched worker hits an ambiguity and tries to ask for clarification, it cannot. The tool is missing. Instead of alerting the user, the model will guess. It will infer what you probably meant. Sometimes it guesses well. Sometimes it builds the wrong feature. Either way, you never got the chance to answer.

How to Catch It Before It Costs You

You cannot prevent every misconfiguration, but you can stop trusting the transcript as proof of work.

Reading the conversation is the first line of defense. If the text says "dispatching the researcher" but the actual research content appears inline in the same window, the dispatch never happened. The model narrated an action and then performed the action itself. Claude Code's own panel will corroborate this. Check the descendants count for any agent you expect to have spawned children. If it shows zero, your hierarchy is imaginary.

Those visual checks are useful, but they still rely on human attention. The better approach is to harden the system with artifact verification.

After every dispatch, my system now checks for a specific, expected file. The researcher must produce a research.md. The coder must leave a diff. The reviewer must write a review_notes.json. If the file does not exist, the pipeline stops immediately. No exceptions, no graceful degradation. The orchestrator halts and reports that the dispatch failed. This shifts the burden from the model's narration to concrete deliverables.

Do not encode your constraints and hope the model respects them. Encode checks that prove the constraints were met. A model can ignore a rule in a prompt. It cannot ignore a missing file that the next step depends on.

Build for Disbelief

The lesson of Suhail is not just about Claude Code folder conventions. It is about the broader reality of building with agentic systems. These models are optimizers. When the path you laid out is blocked, they will find another path. Often that path is a shortcut through their own weights. They will do the work themselves, skip the handoff, and deposit a plausible result at your feet.

Your job as the builder is to remain skeptical. Assume the dispatch failed until the artifact proves otherwise. Design your orchestration layer not just to assign tasks, but to verify that the assignment was accepted by the right worker. Structure is cheap. Verification is what keeps the structure honest.

Source: Why Your Claude Code Orchestrator Silently Stops Dispatching Subagents

Join the discussion: GyaanSetu AI Community on Telegram