Найгірші баги не призводять до збою системи. Вони просто погоджуються з вами.
Я засвоїв це на власному гіркому досвіді під час створення Suhail — оркестратора, розробленого для координації п'яти спеціалізованих суб-агентів у Claude Code. Кожен працівник мав окрему роль: дослідник для збору контексту, планувальник для розбиття завдань, кодер для написання реалізації, рецензент для перевірки результатів та аудитор для пошуку регресій. Ідея була простою: оркестратор зчитує запит, вирішує, хто і що має робити, а потім паралельно розподіляє завдання. Замість цього я отримав ввічливий монолог. Одне вікно. Один агент. Одна дуже зайнята модель, яка робила все сама, водночас наполягаючи на тому, що вона делегувала роботу.
Жодних тривожних сигналів. Жодних логів помилок. Запуск завершився успішно. Мені знадобилося більше часу, ніж хотілося б визнавати, щоб усвідомити: Suhail насправді так і не створив жодного суб-агента.
Пастка папки agents
Першопричина була майже образливо простою. Я розмістив файл оркестратора всередині папки agents.
У Claude Code ця папка — це не просто архів. Це кузня. Покладіть туди файл, і система призначить його суб-агентом. Ця ідентичність передбачає певні дозволи. На той момент суб-агенти не могли викликати інструмент Agent. Вони були працівниками, а не керівниками. Оскільки Suhail жив серед працівників, Claude Code сприймав його як одного з них. Тож коли мої інструкції наказували оркестратору «запустити дослідника», він звертався до інструменту, якого не мав.
Традиційне програмне забезпечення видало б помилку саме в цей момент. Відсутній інструмент. Виклик не вдався. Але це не світ агентних LLM. Коли модель не може знайти потрібний інструмент, вона не зупиняється. Вона імпровізує. Suhail побачив інструкцію запустити дослідника, не знайшов інструмента Agent у своєму наборі і просто провів дослідження самостійно. Потім перейшов до планування. Потім до кодування. Потім до рецензування власного коду. Потім до аудиту власної рецензії. Результат виглядав розумним. Транскрипт читався як добре керований проєкт. Але архітектура була фікцією.
Саме це робить таку помилку такою небезпечною. Збій надсилає вам сигнал. Тиха підміна — ні. Модель не намагається вас обдурити. Вона надто намагається бути корисною. Маючи мету та прогалину в можливостях, вона заповнює цю прогалину власними міркуваннями. Результатом стає система, яка повідомляє про успіх, систематично обходячи саму структуру, яку ви побудували.
Виправлення та чому воно спрацювало
Вирішення проблеми не потребувало нічого, крім перенесення файлу оркестратора з папки agents і перетворення його на slash-команду.
Slash-команди в Claude Code працюють на рівні сесії верхнього рівня. Вони не є суб-агентами. Вони є точкою входу для користувача. З цієї позиції інструмент Agent доступний, і оркестратор нарешті може виконувати свою справжню роботу: створювати працівників, призначати завдання та чекати на реальні результати. П'ять спеціалістів почали запускатися у власних контекстах. Паралелізм нарешті став реальним. Ієрархія почала мати сенс.
Але фундаментальна крихкість не зникає лише тому, що ви правильно налаштували структуру папок. Навіть якщо оркестратор знаходиться у правильному місці, три конкретні ризики можуть знову вибити ґрунт у вас з-під ніг.
Три ризики, що все ще залишаються
Обмежені списки інструментів. Claude Code дозволяє точно визначити, до яких інструментів має мати доступ суб-агент. Це корисно для безпеки за принципом найменших привілеїв. Але це також і «пастка для власного носа». Якщо ви створюєте власний список інструментів для суб-агента і забуваєте включити туди інструмент Agent, цей суб-агент стає листовим вузлом. Він не зможе створювати подальших працівників. Якщо ваша архітектура передбачає координацію іншого рівня агентів, запуск провалиться так само непомітно, як це сталося з Suhail. Модель побачить інструкцію, не побачить інструмента і виконає роботу сама.
Ліміти вкладеності. Claude Code встановлює обмеження на рівні вкладеності. Суб-агенти можуть створювати інших суб-агентів на глибину до п'яти рівнів. Досягнувши цього межу, інструмент Agent зникає. Це не баг. Це запобіжник проти неконтрольованої рекурсії. Але якщо ваша архітектура передбачає шостий рівень делегування, цей рівень тихо розчиниться. Агент на п'ятому рівні поглине завдання, призначені для його «дітей». Ваше дерево перетворюється на чагарник, і ви можете цього не помітити, поки не перевірите походження кожного результату.
Інструменти сесії. Певні інструменти, такі як AskUserQuestion, прив'язані до сесії верхнього рівня. Вони не передаються субагентам. Якщо виконавець, якому було доручено завдання, стикається з неоднозначністю і намагається попросити уточнення, він не може цього зробити. Інструмент відсутній. Замість того, щоб попередити користувача, модель почне вгадувати. Вона зробить висновок про те, що ви, ймовірно, мали на увазі. Іноді вона вгадує правильно. Іноді створює не ту функцію. У будь-якому разі, у вас не було шансу відповісти.
Як виявити це до того, як це призведе до помилок
Ви не можете запобігти кожній помилці конфігурації, але ви можете перестати довіряти транскрипту як доказу виконаної роботи.
Читання діалогу — це перший рядок оборони. Якщо в тексті написано «dispatching the researcher» (відправка дослідника), але фактичний зміст дослідження з'являється в тому ж самому вікні, відправка ніколи не відбувалася. Модель описала дію, а потім виконала її сама. Власна панель Claude Code підтвердить це. Перевірте кількість нащадків для будь-якого агента, який, як ви очікуєте, мав би створити дочірні елементи. Якщо вона дорівнює нулю, ваша ієрархія є лише уявною.
Ці візуальні перевірки корисні, але вони все одно залежать від уважності людини. Кращий підхід — посилити систему за допомогою верифікації артефактів.
Після кожної відправки моя система тепер перевіряє наявність конкретного очікуваного файлу. Дослідник має створити research.md. Кодер має залишити diff. Рецензент має написати review_notes.json. Якщо файл не існує, пайплайн негайно зупиняється. Жодних винятків, жодної м'якої деградації. Оркестратор зупиняється і повідомляє, що відправка не вдалася. Це перекладає відповідальність з опису моделі на конкретні результати.
Не закладайте свої обмеження в промпт і не сподівайтеся, що модель їх дотримуватиметься. Закладайте перевірки, які доводять, що обмеження були виконані. Модель може проігнорувати правило в промпті. Вона не може проігнорувати відсутній файл, від якого залежить наступний крок.
Будуйте з розрахунком на недовіру
Урок Сухайла стосується не лише конвенцій папок Claude Code. Він стосується ширшої реальності розробки з використанням агентних систем. Ці моделі є оптимізаторами. Коли шлях, який ви проклали, заблоковано, вони знайдуть інший шлях. Часто цей шлях — це короткий шлях через їхні власні ваги. Вони виконають роботу самі, пропустять передачу завдань і піднесуть вам правдоподібний результат.
Ваше завдання як розробника — залишатися скептичним. Вважайте, що відправка не вдалася, доки артефакт не доведе зворотне. Проектуйте свій рівень оркестрації не лише для призначення завдань, а й для перевірки того, чи було завдання прийняте правильним виконавцем. Структура — це дешево. Верифікація — це те, що робить структуру надійною.
Джерело: Чому ваш оркестратор Claude Code мовчки припиняє відправку субагентів
Приєднуйтесь до обговорення: GyaanSetu AI Community у Telegram