Главная / Статьи

Правила, рабочий процесс и подагенты: разделение плагина искусственного интеллекта для dbt

Почему один большой файл с инструкциями не сработал, и как AGENTS.md, навык, основанный на спецификациях, изолировал подагентов, а hooks и Jira MCP выполняли по одной задаче в рабочем процессе dbt.

Издатель: REACTAPP.TOP6 мин чтения1298 слов

Источники: Rules, Workflow, Sub-Agents: The Three Layers We Split Our AI Agent Into

Один файл с инструкциями не может вмещать в себя сборник правил, процедуры выполнения задач и ежедневные действия, не нарушая при этом ни одного из этих аспектов. Так вел себя первый вариант рабочего процесса агента dbt, и причины его разделения многое говорят о том, как следует организовывать инструкции для ИИ-агентов.

Небольшой контекст. Искусственный интеллект, которому поручают написать модели dbt, может сгенерировать код, который компилируется, проходит все тесты, но при этом выдает неверные результаты. Вместо того чтобы полагаться на память агента, этот процесс был преобразован в семь строгих контрольных точек, размещённых непосредственно в репозитории; эти точки с тех пор позволяют обнаруживать реальные дефекты, которые при использовании только тестирования остались бы незамеченными. Здесь основное внимание уделяется механизмам, обеспечивающим соблюдение этих контрольных точек: правилам, рабочему процессу, вспомогательным агентам, хукам и интеграции с Jira. Плагин состоит из трёх уровней: постоянно действующих правил, рабочего процесса, запускаемого пользователем, и изолированных вспомогательных агентов для выполнения сложных операций, а также хуков, сохраняющих целостность сессии, и механизма MCP для взаимодействия с внешними ресурсами. Ни один компонент не дублирует функции другого.

Сначала словарный запас

  • Агент. Система ИИ, способная открывать файлы, выполнять команды и самостоятельно выполнять несколько действий, то есть делать нечто большее, чем просто отвечать на вопросы.
  • Файл правил (AGENTS.md). Фиксированные правила, которые агент автоматически загружает при начале сессии. Это открытый стандарт, совместимый с различными инструментами и не привязанный к конкретному поставщику. Можно сравнить его с руководством для сотрудников, знание которого предполагается у всех.
  • Навык (работа в потоке). Инструкции, загружаемые только тогда, когда появляется конкретный тип задачи, подобно рецепту, который берут, когда заказывают определенное блюдо.
  • Подагент. Отдельная копия агента, запускаемая для выполнения одной задачи в собственном закрытом контексте, которая после завершения возвращает краткое резюме.
  • Hook. Скрипт, привязанный к определённому моменту сессии и запускающийся автоматически, независимо от решения агента. Хорошим примером может служить противопожарная спринклерная система: она активируется при первых признаках дыма без запроса к кому-либо.
  • MCP (Model Context Protocol). Стандарт, разработанный компанией Anthropic, который определяет способ подключения агента к внешним инструментам, благодаря чему не требуется писать индивидуальный код для каждого инструмента. Его часто сравнивают с разъёмом USB-C для ИИ-приложений, поскольку любое приложение, соответствующее этому стандарту, может к нему подключаться.
  • Что пошло не так в начале

    В самых ранних рабочих процессах, основанных на спецификациях, отсутствовало большинство этих элементов. В корне репозитория находился один файл в формате Markdown, в котором были указаны правила и процедура, а также предусматривалось пошаговое руководство для агента. Не было ни подагентов, ни хуков, ни жёстких ограничений — только предложенная последовательность действий.

    Некоторое время это справлялось. Однако когда сессия затягивалась, правила, находящиеся в верхней части файла, примерно на третьем этапе реализации выходили из активного контекста, и агент начинал импровизировать, не сообщая об этом. Этапы обнаружения, спецификации и реализации происходили в одном окне, и старейшие инструкции становились первыми жертвами.

    Команды в других складах сталкиваются с той же проблемой. В одной из команд, находящихся на более продвинутом этапе, правила, рабочий процесс и выполнение были разделены, а также использовались специальные механизмы сессий, чтобы компактизация контекста не могла тайно удалять инструкции в процессе выполнения задачи. Вывод заключался в том, что нельзя рассматривать «инструкции агента» как единое целое. Их три, у каждой своя продолжительность существования и своя функция.

    Три уровня, по одному ответственному на каждый

    • Первый уровень — постоянные правила: AGENTS.md, присутствующий всегда
    • Второй уровень: процесс: навык, основанный на спецификациях, инициируемый пользователем
    • Третий уровень: сложные шаги: подагенты, создаваемые по мере необходимости

    Правила

    Файл с правилами содержит обязательные инженерные правила блокировки, а также профиль проекта, в котором задаются настройки каждой команды: правила номенклатуры, способы реализации, базовая ветка, система CI и т. д. Хук загружает этот файл в начале каждой сессии, что исключает необходимость в том, чтобы агент сам вспоминал о его просмотре. Файл доступен до отправки первого сообщения. Поскольку профиль находится отдельно, другие команды могут использовать плагин без необходимости создания копии проекта.

    Рабочий процесс

    Этот процесс кодируется как навык, который агент вызывает по запросу пользователя. Он активируется при использовании фраз вроде «исправить баг X» или «создать функцию Y», либо явно через команду /dbt-spec-driven:spec-driven в Cortex Code. Процесс направляется в зависимости от цели (функция, баг, рефакторинг, отдельный аудит или отдельная документация) и координирует соответствующие этапы.

    Самое важное решение в дизайне заключается в том, что этот навык никогда не повторяет правила — он указывает на файл AGENTS.md. Благодаря этому решению была решена большая часть проблем с исходным контекстом, поскольку не возникает дублирующихся копий правил, которые могли бы отклониться друг от друга.

    Подагенты

    Пять задач потребляют столько ресурсов контекста, что их выполнение в основном потоке заблокирует выполнение настоящей работы: discovery, test-author, output-validator, peer-reviewer и ci-interpreter. Каждая из них запускается в собственном контексте, выполняет одну задачу и возвращает структурированный отчет, содержащий только необходимую информацию.

    Основная идея заключается в том, что контекст — это ограниченный ресурс, а не бесконечный носитель данных. Возьмем процесс обнаружения: он может включать чтение десятка файлов моделей и анализ их связей. Если он выполняется в основном потоке, это означает, что половина ресурсов тратится еще до начала реализации на файлы, которые к тому моменту никому не понадобятся. Обнаружение также хорошо подходит для небольших, недорогих моделей, поскольку чтение и обобщение требуют меньше вычислительных ресурсов.

    Хуки

    Файл hooks/hooks.json запускает три хука, для которых не требуется сотрудничество агентов. Один из них загружает файл AGENTS.md при начале сессии. Другой выдает предупреждение перед сжатием контекста, чтобы ничего важного не исчезло незаметно, что и стало причиной сбоя в первой версии. Третий добавляет запись о сессии при её завершении.

    Каждый хук поставляется в виде пары вариантов для bash и PowerShell. Cortex запускает тот вариант, который соответствует операционной системе, а остальной работает без ошибок. Команде, использующей разные операционные системы, не требуется индивидуальная настройка.

    Подключение MCP к Jira

    Всё это теряет смысл, если под «возвратом спецификации в тикет» понимается ручная копировка текста между терминалом и Jira. Для связи рабочих процессов используются два сервера MCP.

    Atlassian MCP — это нечто просто необходимое. Подагент discovery использует его для чтения тикета при открытии сессии, а на этапе Specify — для добавления пронумерованных требований обратно в этот тикет. Таким образом, спецификация остается рядом с работой, а не исчезает в истории чатов.

    Notion MCP в настоящее время играет более второстепенную роль. Он применяется тогда, когда что-то требует документирования в более постоянном месте, чем описание в PR или в репозитории, например, для описания полного цикла работы. В целом, MCP позволяет правилам, рабочим процессам и подагентам взаимодействовать с любыми элементами вне репозитория. Сегодня это может быть тикет, а завтра — платформа BI или канал в Teams.

    Общая картина

    Пользователь задаёт вопрос, и маршруты обработки навыков вместе с рабочими процессами отклоняются в сторону. Каждый рабочий процесс возвращает отчёт и не сохраняет свои файлы в основном потоке. Хуки и MCP оборачивают структуру данных, не находясь внутри неё: они загружают правила, предупреждают перед сжатием и передают данные в Jira.

    Что улучшилось

    • Основной поток продолжает сосредотачиваться на принятии решений и не перегружается результатами обработки десятков файлов.
    • Правила больше не теряются, поскольку существует ровно одна их копия.
    • Во время сессии сжатие не может привести к потере данных без предварительного предупреждения.

    Этот урок актуален не только для dbt. Любой, кто использует ИИ-агента для работы с реальным репозиторием, скорее всего, сталкивается с ситуацией, когда «один файл выполняет всё», и это приводит к тем же проблемам: чем дольше длится сессия, тем сильнее уступают место более ранние инструкции.