Правила, робочий процес та підагенти: розділення плагіну штучного інтелекту для dbt.
Чому один великий файл інструкцій зазнав невдачі, та як AGENTS.md, навичка, заснована на специфікаціях, ізолювала підагентів, хуки та Jira MCP виконали по одній завданню у робочому процесі dbt.
Джерела: Rules, Workflow, Sub-Agents: The Three Layers We Split Our AI Agent Into
Один файл інструкцій не може містити правила, процес та щоденні завдання, не порушуючи при цьому жодного з цих аспектів. Саме так поводилася перша версія робочого процесу одного агента dbt, а причини його розділення багато чого говорять про те, як організувати інструкції для AI-агентів.
Деякий контекст. Штучний інтелект, якому доручили створювати моделі dbt, може повертати код, який компілюється та проходить усі тести, проте все одно дає неправильні результати. Замість того, щоб покладатися на пам’ять агента, цей процес було перетворено на сім жорстких контрольних точок, розміщених безпосередньо в самому репозиторії, і ці точки вже виявили справжні дефекти, які тести самі по собі б пропустили. Тут увага зосереджена на механізмах, які підтримують ці контрольні точки: правила, робочий процес, підагенти, хуки та інтеграція з Jira. Плагін має три рівні: постійно діючі правила, робочий процес, який запускає користувач, та ізольовані підагенти для складних кроків, а також хуки, які забезпечують послідовність сеансу, та інтерфейс MCP для взаємодії поза межами репозиторію. Жодна з частин не дублює функції іншої.
Спочатку лексика
- Агент. Система ШІ, яка може відкривати файли, виконувати команди та самостійно виконувати кілька кроків, тож робить більше, ніж просто відповідає на запитання.
- Файл правил (
AGENTS.md). Постійні правила, які агент автоматично завантажує під час початку сеансу. Це відкритий стандарт, який працює з різними інструментами та не прив’язаний до одного постачальника. Це як посібник для співробітників, який усі мають знати заздалегідь. - Навичка (робочий процес). Інструкції, які завантажуються лише тоді, коли з’являється певний тип завдання, подібно до рецепта, який витягується, коли замовляється конкретна страва.
- Підагент. Окрема копія агента, запущена для виконання однієї роботи у власному приватному контексті, яка після завершення повертає підсумок.
Що спочатку пішло не так
У найраніших робочих процесах, заснованих на специфікаціях, бракувало більшості цих елементів. У корені репозиторію знаходилася одна файлова структура у форматі markdown, яка містила правила та процес та намагалася керувати агентом на кожному кроці по черзі. Не було підагентів, хуків чи жорстких перешкод — лише пропонована послідовність дій.
Деякий час це працювало. Однак коли сесія ставала довгою, правила, розташовані у верхній частині файлу, приблизно на третьому етапі реалізації виходили з активного контексту, і агент починав імпровізувати, не повідомляючи про це. Процеси відкриття, специфікації та реалізації відбувалися в одному вікні, тож найстаріші інструкції ставали першими жертвами.
Команди в інших складах стикаються з тією самою проблемою. Одна з практик, використовуваних більш досвідченими командами, полягала у розділенні правил, робочого процесу та виконання, а також у використанні механізмів сесій для того, щоб компактизація контексту не могла тихо видаляти інструкції під час виконання завдання. Висновок полягав у тому, що не варто розглядати „інструкції агента“ як єдине ціле. Їх є три, кожна з яких має свій термін дії та свої функції.
Три шари, по одному власнику кожен
- Перший шар – постійні правила:
AGENTS.md, присутній усім часом - Другий рівень – процес: навичка
spec-driven, яку ініціює користувач - Третій рівень – складні кроки: підагенти, створювані за потреби
Правила
Файл з правилами містить обов’язкові інженерні правила блокування, а також профіль проекту, який фіксує налаштування кожної команди: конвенції найменувань, способи реалізації, базову гілку, систему 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 використовує його для читання тикета під час відкриття сесії, а на етапі визначення параметрів — для додавання пронумерованих вимог до цього тикета. Таким чином, специфікація знаходиться поруч із роботою, а не в історії чату, яка зникає.
Notion MCP наразі відіграє меншу роль. Його використовують тоді, коли щось потребує документування у більш постійному місці, ніж опис PR чи репозиторій, наприклад, для опису повного циклу виконання. Загалом MCP дозволяє правилам, робочим процесам та підагентам взаємодіяти з будь-чим поза репозиторієм. Сьогодні це може бути тикет, а завтра — платформа BI чи канал у Teams.
Повна картина
Користувач ставить запит, а шляхи виконання завдань та працівники відходять убік. Кожен працівник повертає звіт та не зберігає свої файли у головному потоці. Хуки та MCP оточують структуру даних, не знаходячись всередині неї: вони завантажують правила, попереджають перед стисненням та передають дані до Jira.
Що покращилося
- Головний потік залишається зосередженим на прийнятті рішень та не обтяжується великою кількістю файлів із результатами обробки.
- Правила більше не „зникають“, оскільки існує лише одна їхня копія.
- Під час стиснення даних під час сеансу нічого не може бути втрачено без попередження.
Цей загальний урок стосується не лише dbt. Будь-хто, хто використовує AI-агента для роботи з реальним репозиторієм, ймовірно, матиме версію концепції „один файл для всього“, і вона зазвичай ламається так само: чим довший сеанс, тим більше ранніх інструкцій витісняються.