Правілы, працэс і субагенты: як мы падзялілі AI-плагін для dbt
Чаму адзін вялікі файл інструкцый не спрацаваў і як AGENTS.md, навык на аснове спецыфікацый, ізаляваныя субагенты, хукі і Jira MCP узялі па адной задачы ў працэсе dbt.
Крыніцы: Rules, Workflow, Sub-Agents: The Three Layers We Split Our AI Agent Into
Адзін файл з інструкцыямі не можа ўместыць кнігу правілаў, працэс і повсякдзенную працу, не паспеўшы адказаць за ўсе тры аспекты. Самэ так паводзілася першая версія аднаго рабочага працэсу dbt agent, а прычыны яго раздзелення даюць важлівыя падказкі пра тое, як організаваць інструкцыі для AI-агента.
Кілька кантэксту. Агент AI, якому прагнулі напісаць мадэлі dbt, можа вернуць код, які скомпілюецца і працаваць усіх тэстаў, але ўсё равно даць некарэктныя цыфры. У замест на тое, каб павергацца памяці агента, гэты процэс быў ператворэны ў сэм «жорсткіх» блакатоў, якія знаходзяцца ў самай базе дадзеных, і гэтыя блакаты ўжо знайшлі рэальныя дыфекты, якія тэставанне самае по сабе бы прыховала. Тут акцэнт ставіцца на механізмы, якія падтрымваюць цісносць блакатоў: правілы, рабочыя працэсы, падагенты, хукі і інтэграцыя з Jira. Плагін складаецца з трохоў слоёў: правілы, якія працуюць завжды, рабочы працэс, які запускае корыстнік, і ізольаваныя падагенты для складных крокаў, а таксама хукі, якія падтрымваюць цісносць сесіі, і MCP для доступу за межы базы дадзеных. Ніякі элемент не дублюе задачу іншага.
Спачатку слоўнік
- Агент. Сістэма AI, якая можа ачыць файлы, выкананыць каманды і самастойна выпалняць калькі крокаў, таму яна робіць больш, чым проста адпавядае на запытанні.
- Файл правілаў (
AGENTS.md). Постаўленыя правілы, якія агент автаматычна завантажае пад час пачатку сесіі. Цэў адкрыты стандарт, які працуе ў розных інструментах і не прыязджае да аднаго вэндора. Можна супарабяляць з інструкцыямі для працавікаў, якія, як ожыдваецца, усі вядомы. - Навык (працоўы працэс). Інструкцыі, якія завантажаюцца толькі тады, калі з’яўляецца конкрэтны тып задання, падобна да рэцэпта, які выцягуецца, калі замовляецца адзін конкрэтны страва.
- Падагент. Адзінэцкі экзамен агента, які запускаецца для аднаго завадання ў сваёй сабэйскай сэрэйні, і які пасля завершэння вяртае падсумак.
Што было не так спачатку
Першыя практыкі, адмовіліся ад спецыфікацый, не мелі большасці гэтых элементаў. У корні рэпазітарыя быў толькі адны файл у фармаце 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/hooks.json запускае трыя хукі, для чаго не трэба саўместнай працы агентаў. Адны з іх завантажае файл AGENTS.md пад час пачатку сесіі. Адны паведамляе пра прыбліжэнне кантэкста, ўбачліва чынічы, каб ніч важлівага не знікло непазірна, што было самэй прычыной неяксносці першай версіі. Адны дадае прыметку сесіі пад час выходу.
Кожны хук поставляецца у варыянтах для bash і PowerShell. Cortex запускае той варыант, які падходзіць для операцыйной сістэмы, а іншы працюе без проблем. Командзе, якая вікорыстоўвае розныя операцыйныя сістэмы, не трэба настаўляння для кожнага карыстальніка.
Паўязка MCP з Jira
Усё гэта стае безрэзультатным, калі „падаць спецыфікацыю знову ў тыкет“ означае, што хтось ручна копіюе тэкст між тэрміналам і Jira. Два серверы MCP паў’язуюць гэты працэс.
Atlassian MCP — гэта незаменны элемент. Падагент discovery выкарыстоўвае яго для чытання тыкета калі пачынаецца сесія, а на этапы Specify — для падачы прынцыпоў, паракметаваных номерамі, назад у той жа тыкет. Такім чынам прынцыпы застаюцца празаўсёды разам з работай, а не ў історыі чату, якая знікае.
Notion MCP наразе выпалюе менш значны ролю. Яго выкарыстоўваюць, калі ў чым-небудзь ёсць патрэба у дакументацыі ў болей стойкім месцы, чым опіс PR-запроса або сам рэпазітарый, напрыклад, для апісання цэлага працэсу. У загальным сэнсе MCP — гэта тое, што дазволяе правілам, рабочым пракцэсам і падагентам адносіцца да будзь-чаго за межамі рэпазітарыя. Сёньдзе гэтым можа быць тыкет, а завтра — платформа BI або канал у Teams.
Весь картэнаж
Пользоватэль запытаецца, а шляхі спэцыялізацыі і працоўнікі адходзяць у бок. Кожны працоўнік вяртае атлас і не кідае сваіяя файлы ў галоўную ніт. Хукі і MCP абгортаюць зображэнне, не застаючыся ўнутры яго: яны завантажаюць правілы, паветараюць перад стысненнем і даступаюць да Jira.
Што падбарылася
- Галоўная ніт застаецца сфокусаванай на рашэннях і не перавантажваецца выходамі з дзесятка файлоў.
- Правілы больш не змішваюцца, адколі існуе толькі адна копія.
- Стысненне падчас сесіі не можа чагосьць загубіць без паветарання спачатку.
Загальны урок паслужыць не толькі для dbt. Кожны, хто запускае AI-агента проты рэальнага рэпазітарыя, верагатна будзе маты версію „адзін файл, які робіць усё“, і яна зазвычай ламаецца так сама: чым дольшая сесія, тым больш раннія інструкцыі вытысняюцца.