Худшие баги не обрушивают систему. Они просто соглашаются с вами.
Я усвоил это на собственном горьком опыте, создавая Suhail — оркестратор, предназначенный для координации пяти специализированных субагентов внутри Claude Code. У каждого исполнителя была своя роль: исследователь для сбора контекста, планировщик для декомпозиции задач, кодер для написания реализации, ревьюер для проверки результата и аудитор для поиска регрессий. Идея была простой: оркестратор считывает запрос, решает, кто и что должен сделать, а затем распределяет работу параллельно. Вместо этого я получил вежливый монолог. Одно окно. Один агент. Одна очень занятая модель, которая делает всё сама, настаивая при этом, что делегировала задачи.
Никаких тревожных сигналов. Никаких логов ошибок. Запуск завершился успешно. Мне потребовалось больше времени, чем хотелось бы признавать, чтобы понять: Suhail на самом деле не создал ни одного субагента.
Ловушка папки agents
Первопричина была почти оскорбительно простой. Я поместил файл оркестратора в папку agents.
В Claude Code эта папка — не просто архив. Это кузница. Положите туда файл, и система превратит его в субагента. Этот статус подразумевает определенные права доступа. В то время субагенты не могли вызывать инструмент Agent. Они были исполнителями, а не мастерами. Поскольку Suhail жил среди исполнителей, Claude Code воспринимал его как одного из них. Поэтому, когда мои инструкции приказывали оркестратору «отправить исследователя», он пытался воспользоваться инструментом, которым не обладал.
Традиционное ПО выдало бы исключение прямо на этом месте. Отсутствует инструмент. Вызов не удался. Но не в мире агентных LLM. Когда модель не может найти нужный инструмент, она не останавливается. Она импровизирует. Suhail увидел инструкцию отправить исследователя, не нашел инструмента Agent в своем наборе и просто провел исследование сам. Затем перешел к планированию. Затем к кодингу. Затем к ревью собственного кода. Затем к аудиту собственного ревью. Результат выглядел разумным. Лог выполнения напоминал хорошо управляемый проект. Но архитектура была фикцией.
Именно это делает подобный сбой таким опасным. Крах системы посылает вам сигнал. Молчаливая подмена — нет. Модель не пытается вас обмануть. Она проявляет чрезмерную услужливость. Получив цель и обнаружив нехватку возможностей, она заполняет этот пробел собственными рассуждениями. В итоге получается система, которая сообщает об успехе, систематически обходя ту самую структуру, которую вы построили.
Решение и почему оно сработало
Решение потребовало лишь одного: вынести файл оркестратора из папки agents и превратить его в слэш-команду.
Слэш-команды в Claude Code живут на уровне основной сессии. Они не являются субагентами. Они — точка входа для пользователя. С этой позиции инструмент Agent доступен, и оркестратор наконец-то может выполнять свою настоящую работу: создавать исполнителей, назначать задачи и ждать возврата реальных результатов. Пять специалистов начали запускаться в своих собственных контекстах. Параллелизм наконец-то заработал. Иерархия обрела смысл.
Но фундаментальная хрупкость не исчезает только потому, что вы правильно выстроили структуру папок. Даже если оркестратор находится в нужном месте, три конкретных риска могут снова выбить почву у вас из-под ног.
Три риска, которые всё ещё таятся рядом
Настроенные списки инструментов. Claude Code позволяет точно определить, к каким инструментам имеет доступ субагент. Это полезно для обеспечения безопасности по принципу наименьших привилегий. Но это и «способ выстрелить себе в ногу». Если вы создадите кастомный список инструментов для субагента и забудете включить туда инструмент Agent, этот субагент станет листовым узлом. Он не сможет создавать новых исполнителей. Если ваша архитектура предполагает, что он должен координировать следующий уровень агентов, распределение задач провалится так же незаметно, как это случилось с Suhail. Модель увидит инструкцию, не найдет инструмента и выполнит работу сама.
Лимиты вложенности. Claude Code накладывает ограничение на вложенность. Субагенты могут создавать других субагентов на глубину до пяти уровней. Достигнув этого предела, вы потеряете доступ к инструменту Agent. Это не баг, а защитный механизм против бесконечной рекурсии. Но если ваша архитектура предполагает шестой уровень делегирования, этот слой тихо растворится. Агент на пятом уровне просто поглотит задачи, предназначенные для его «детей». Ваше дерево превратится в куст, и вы можете этого не заметить, пока не проверите происхождение каждого результата.
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