Блог Maguyva

Контекст, що подорожує з вами

Mon, 07 Sep 2026 00:00:00 GMT

Індексатор Cursor чудовий усередині Cursor. Автодоповнення, вбудоване редагування, чат і агент у тому вікні вже спираються на індекс проєкту, який Cursor підтримує для відкритого робочого простору. Якщо Cursor — єдине середовище, де ви пишете код, і цей індекс уже знаходить потрібні файли, залишайтеся там. Це чесний випадок «залишайтеся на місці», і він по праву відкриває цю статтю.

Ця стаття про іншу половину звичайного тижня. Той самий репозиторій також відкривають у Claude Code, у нього запитують із Codex CLI, його перевіряють на другій машині, або до нього звертається агент, що працює в CI. Питання не в тому, «який індексатор кращий». Питання в тому, чи та сама карта, якій агент довіряє в одному вікні, є тією самою картою, якій він довіряє в наступному.

Maguyva — це та карта, що подорожує з вами. Це віддалений MCP-шар контексту кодової бази. Агент звертається до нього так само, як до будь-якого іншого MCP-інструмента. Результати повертаються як ранжовані шляхи з номерами рядків. Cursor залишається редактором. Рухається саме контекст.

Для чого потрібен індексатор Cursor

Вбудована індексація Cursor існує для того, щоб чат, агент і пошук усередині редактора могли отримувати релевантний код, а не покладатися лише на те, що вміщується в сире контекстне вікно моделі. Це правильний дизайн для IDE. Цей індекс — нативна частина Cursor. Це не MCP-сервер, і він недоступний із жодного іншого клієнта.

Ось як це працює, згідно з публічною документацією Cursor і власними заявами Cursor на момент написання: основний шлях пошуку більше не проходить через хмарний індекс ембеддингів. Команда Cursor заявила на своєму форумі спільноти, що виділений семантичний пошук на основі ембеддингів поступово згортається на користь пошуку на основі grep, бо сучасні моделі вже достатньо добре досліджують живе дерево коду самостійно. Натомість є Instant Grep — локальний пошуковий індекс, побудований на n-грамах, інвертованих списках і фільтрах Блума, що зберігається в таблиці пошуку, відображеній у пам’ять, тож запити вирішуються на власній машині розробника, а не на сервері.

Сам індекс живе у власному каталозі .git/cursor/ репозиторію, прив’язаному до конкретного git-коміту; зміни з моменту цього коміту накладаються поверх, а не запускають повторне сканування, і індекс перебудовується лише тоді, коли локальний стан сильно відхилився від того, для чого його було побудовано. Оскільки він міститься всередині .git, він ніколи не відстежується системою контролю версій і ніколи не пушиться — видаліть теку, і індекс зникне. .gitignore дотримується за побудовою, оскільки враховується лише контент, відстежуваний git, а .cursorignore застосовується на шляху читання. На цьому шляху більше немає ні серверного етапу ембеддингу, ні віддаленої векторної бази даних. Раніша документація описувала дизайн із хмарною підтримкою — шифрування чанків, синхронізацію через дерево Меркла, повторне використання індексу між членами команди — і сама команда Cursor відтоді заявила, що цей дизайн згортається, тож у цій статті він більше не описується як актуальний.

Яскрава особливість усередині редактора — субагент Explore від Cursor. Він може запускати кілька паралельних пошуків у власному контекстному вікні на швидшій моделі й повертати лише релевантні знахідки, тож основна розмова не роздувається результатами пошуку. Це справжня сила всередині редактора. Збережіть її.

Мульти-кореневі робочі простори підтримуються: контекст кожної відкритої теки доступний агенту. Деякі залежні від git функції, як-от worktree, вимикаються в мульти-кореневих налаштуваннях, а Cloud Agents взагалі не підтримують мульти-кореневі робочі простори.

Ніщо з цього не привід залишати Cursor. Це точний опис карти, яка чудова там, де вона живе.

Що насправді означає «подорожувати з вами»

Карта подорожує з вами, коли ті самі запитання повертають той самий тип відповіді, з цитатами, які можна відкрити, з більш ніж одного клієнта.

У Cursor: «Де визначено parseConfig і хто його викликає?»
У Claude Code, на тому самому репозиторії: те саме запитання.
У Codex CLI, на машині для рев’ю, яка ніколи не відкривала вікно Cursor: те саме запитання.
У CI-агенті, що розмовляє MCP: те саме запитання, до того самого розміщеного знімка.

Якщо кожне середовище будує власний приватний індекс, у вас немає однієї карти. У вас є кілька кешів, що розходяться. Індекс редактора може бути актуальним для дерева на диску. Сесія CLI може відставати на день. Завдання CI може дивитися на іншу робочу копію. І агент усе одно звучатиме впевнено.

Індексатор Cursor не мусить це вирішувати. Оскільки він живе всередині редактора, контекст, який він будує, — для цього редактора. Читачеві, якому також потрібні CLI, конвеєр CI або інший редактор, потрібен окремий інструмент для цих середовищ. Це факт меж застосовності, а не дефект. Maguyva і є цим окремим інструментом.

Опублікована кількість мов для індексатора Cursor не вказана в матеріалах, які може використовувати цей текст. Maguyva публікує підтримку понад 279 мов і текстових технологій. Ціни Cursor тут також не наводяться; див. їхню сторінку з тарифами. Maguyva бере плату за робочий простір, а не за місце, з опублікованими тарифами $0, $19, $49 і $149 залежно від обсягу індексації та розміру робочого простору.

Одна розміщена карта, будь-який MCP-клієнт

Maguyva — це віддалений MCP-сервер. Ви підключаєте GitHub, обираєте репозиторії, і хмарний конвеєр будує символи, ребра графа та ранжовану карту. Ви додаєте API-ключ до конфігурації MCP того клієнта, яким уже користуєтеся. У Maguyva є посібники з налаштування для 24 задокументованих MCP-клієнтів — включно з Cursor — і вона може підключатися до інших MCP-сумісних клієнтів, що підтримують стандартну конфігурацію.

Сторінка налаштування Cursor — це шлях, специфічний для редактора, якщо саме там ви працюєте. Той самий сервер відповідає Claude Code, VS Code, Windsurf, Codex CLI та іншим. Вам не потрібно міняти редактор. Ви даєте кожному агенту ту саму поверхню інструментів: 11 клієнтських MCP-інструментів для пошуку, символів, аналізу залежностей, отримання файлів, контексту репозиторію та детермінованих службових робочих процесів. Семантичний, структурний, графовий і текстовий пошук зливаються в ранжовані результати.

У цьому й полягає перевага переносності. Цитати, які ви перевірили в Cursor цього ранку, мають ту саму форму, що й цитати, які Codex CLI поверне сьогодні ввечері. Шлях до файлу й номер рядка. Відкрийте їх. Якщо вони неправильні, ви це побачите. Якщо правильні — наступна правка матиме куди приземлитися. Схвалене твердження — менше галюцинованих правок, а не обіцянка, що кожна правка правильна.

Актуальність публікується відкрито. Знімки позначені часом, тож агент знає, яку версію дерева він читає. Періодичність перебудови — щодня на безкоштовному плані та щогодини на платних. Чесне обмеження — несинхронізована локальна робота: правка, що існує лише в робочому дереві, ще не потрапила до розміщеної карти. Це обмеження однакове незалежно від того, з якого клієнта ви робите запит, і саме в цьому суть. Розбіжність між клієнтами більше не друге, приховане обмеження.

Документація дає цикл активації, застосовний до будь-якого клієнта: проіндексуйте репозиторій, який ви вже знаєте, підключіть клієнта, поставте одне запитання, яке можна перевірити. Зробіть це один раз у Cursor. Зробіть це ще раз із того CLI, яким ви справді користуєтеся в дні рев’ю. Якщо обидві відповіді цитують той самий обробник, карта справді подорожувала з вами.

Як дві карти співіснують одна з одною

Використовуйте обидві. Це не альтернативи в сенсі сторінки порівняння.

Тримайте індексатор Cursor увімкненим для проєкту на диску. Нехай Explore, Instant Grep і агент усередині редактора використовують його. Цей цикл нативний і швидкий.
Додайте Maguyva як MCP-сервер у Cursor, щоб та сама сесія могла також запитувати розміщену карту робочого простору. Cursor — задокументований клієнт Maguyva. Ви не обираєте один індекс, видаляючи інший.
Додайте той самий сервер Maguyva до Claude Code, Codex CLI або будь-якого іншого MCP-клієнта, що торкається репозиторію. Одна форма API-ключа. Один робочий простір.
Якщо CI-агент MCP-сумісний, спрямуйте його на той самий сервер. Він прочитає той самий позначений часом знімок, що й ноутбук.

Індекс редактора залишається найкращим інструментом для питання «що на диску в цьому вікні прямо зараз». Розміщена карта — найкращий інструмент для питання «як цей робочий простір виглядає для кожного агента, що торкнеться його сьогодні». Ці твердження не конкурують.

Квоти робочого простору опубліковані на сторінці тарифів: репозиторії, проіндексовані рядки та користувачі, оплачувані за робочий простір. Агенти й люди ділять один і той самий лічильник користувачів. Почніть безкоштовно з репозиторію, який ви вже вмієте оцінювати. Підвищуйте робочий простір лише після того, як цитати витримали контакт із деревом.

Чого ця стаття не стверджує

Вона не стверджує, що індексатор Cursor слабкий, неповний або є приводом змінити редактор. Перше речення цього тексту говорить протилежне.

Вона не стверджує, що Maguyva замінює Instant Grep або субагент Explore. Це функції Cursor. Вони залишаються в Cursor.

Вона не вигадує кількість мов, цифру затримки чи економію токенів для жодного з продуктів. Невідомі цифри залишаються неопублікованими.

Вона не вдає, ніби непушнута локальна робота є в розміщеній карті. Позначені часом знімки роблять це обмеження видимим. Вони його не усувають.

Тест звичайний. Проіндексуйте репозиторій, який ви вже знаєте. Поставте одне запитання, яке можна перевірити, спочатку в Cursor, потім у другому MCP-клієнті. Контекст, що подорожує з вами, — це та сама цитата в обох місцях.

// same map, wherever you opened it.

Спочатку карта, потім рев'ю

Mon, 07 Sep 2026 00:00:00 GMT

По обидва боки пул-реквесту стоять дві різні задачі. Перш ніж агент почне писати, йому потрібна карта дерева, яке він збирається змінити. Після того як агент відкрив PR, щось має прочитати цю зміну у зіставленні з рештою системи й залишити коментарі, за якими людина може діяти.

Ці задачі виглядають схоже здалеку, бо обидві включають «розуміння кодової бази». Це не один і той самий продукт. Одна відповідає на питання «куди має приземлитися ця зміна?». Інша відповідає на питання «що зламав цей diff, що пропустить порядковий лінтер?». Змішати їх означає отримати гірший перший чернетку й галасливіше рев’ю.

Цей текст — посібник зі спільного робочого процесу. Maguyva — карта, яку агент запитує першою. Greptile — агент рев’ю, який коментує PR після. Ця пара взаємодоповнювана за побудовою: Maguyva не рев’ює пул-реквести, а Greptile не замінює шар контексту, який агент використав, щоб їх написати.

Чому цей поділ корисний

Кодувальний агент, що відштовхується від апріорних знань із тренування плюс кілька вставлених файлів, вигадає правдоподібний шлях і відредагує його. Це провал «неправильного файлу», і це проблема пошуку. Maguyva — віддалений MCP-шар контексту кодової бази: семантичний, структурний (AST), графовий/залежнісний і текстовий пошук зливаються в ранжовані результати, плюс пошук символів і отримання файлів. Обґрунтовані відповіді повертаються у вигляді path/file.ext:line, тож ви можете відхилити промах до того, як з’явиться патч. Твердження залишається скромним: менше галюцинованих правок. Модель усе ще може вгадувати. Просто перший крок перестає бути вгадуванням.

Greptile — це агент рев’ю коду на основі ШІ. За їхніми власними словами, він автоматично рев’ює кожен пул-реквест із повним розумінням кодової бази, протиставляючи це традиційним лінтерам, які перевіряють файли ізольовано, а не всю систему. Налаштування полягає у встановленні застосунку GitHub або GitLab і виборі репозиторіїв. Немає локального індексу, який вам потрібно експлуатувати. Хостинг — Greptile Cloud (вони заявляють про відповідність SOC 2 Type II, зі звітом, доступним за запитом), з опцією самостійного хостингу для підприємств.

Їхній власний пронумерований процес такий: підключитися й побудувати граф залежностей кожної функції, класу й залежності; при кожному пул-реквесті аналізувати зміну, використовуючи цей повний граф репозиторію, і публікувати знахідки у вигляді коментарів PR із запропонованими виправленнями приблизно за три хвилини; кожен коментар може передати проблему кодувальному агенту, яким команда вже користується. Вони також заявляють, що читають попередні коментарі людей до PR із часом, щоб вивчити стандарти коду команди й зменшити галасливі пропозиції. За їхніми словами, їхній навчальній системі потрібно 2–3 тижні, щоб адаптуватися.

Це рев’ю, а не чернетка. Сильна сторона Greptile — контекст повного графа репозиторію на зміну, яка вже приземлилася в PR, а потім замкнений цикл, що надсилає знахідку в Claude Code, Codex, Conductor, Cursor або Devin. Сильна сторона Maguyva — ранжована карта, яку агент запитав до того, як цю зміну було написано. Використовуйте обидва. Не просіть жоден із них робити роботу іншого.

Офіційна інтеграція продуктів Maguyva–Greptile від першої сторони не заявлена. Вона вам і не потрібна. Maguyva розмовляє з агентом через MCP. Greptile розмовляє з GitHub або GitLab через свій застосунок. Вони зустрічаються на пул-реквесті. Жодного зв’язувального скрипта, жодного cron, що з’єднує один інструмент з іншим. Ця пара обходиться без bash, бо кожен продукт уже займає ту поверхню, яка йому належить.

Чим це не є

Це не розгром Greptile. Це не сторінка «змініть рецензента». Greptile запустився на Hacker News 5 березня 2024 року як компанія Y Combinator W24, і та гілка обговорення — це те, як багато людей уперше дізналися про цей продукт. Якщо саме так ви їх знайшли, продовжуйте ними користуватися. Ця сторінка — відсутня передня половина того циклу: дати агенту опору заздалегідь, щоб PR, який бачить Greptile, уже націлювався на правильні файли.

Маркетингові матеріали Greptile ведуть із твердженнями про швидкість рев’ю та виявлення багів. Ставтеся до них як до власних заяв Greptile, а не як до незалежно перевірених цифр. Цей текст не повторює їх як факти.

Покриття мов — та сама чесність. Greptile формулює підтримку як охоплення всіх мов програмування, а не перелічений список; точне число не вказане. Maguyva публікує підтримку понад 279 мов і текстових технологій, з технічним поділом (AST на основі парсера проти лише тексту) на сайті, коли питання технічне. Це різні продукти, що роблять різні заяви. Не змішуйте їх.

Ціни Greptile не вказані в матеріалах, які може використовувати цей текст. Платні плани існують; див. їхню сторінку тарифів. Maguyva бере плату за робочий простір, а не за місце. Плани починаються безкоштовно. Сторінка тарифів перелічує опубліковані рівні, якщо вам потрібні цифри по робочих просторах.

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

Три іменовані етапи. Виконуйте їх у цьому порядку. Не пропускайте жоден із них, коли пробуєте цю пару вперше.

1. Контекст Maguyva

Проіндексуйте один репозиторій, який ви вже знаєте. Підключіть MCP-клієнта, у якому ви вже пишете код — Claude Code, Cursor, Codex CLI, VS Code, Windsurf або іншого MCP-сумісного клієнта. У Maguyva є посібники з налаштування для 24 задокументованих MCP-клієнтів, і вона може підключатися до інших клієнтів, що підтримують стандартну конфігурацію MCP.

Поставте запитання, яке ви можете оцінити, перш ніж хтось напише хоч рядок. «Де обробляється закінчення сесії і що це викликає?» — кращий перший хід, ніж «полагодь автентифікацію». Вимагайте цитат. Відкрийте результати file.ext:line. Простежте символ. Підтвердьте залежність, яку ви збираєтеся торкнутися.

Maguyva надає 11 клієнтських MCP-інструментів для пошуку, символів, аналізу залежностей, отримання файлів, контексту репозиторію та детермінованих службових робочих процесів. Чотири режими пошуку зливаються в ранжовані результати; find_symbol — окремий інструмент, коли ви вже знаєте ім’я. Документація описує найкоротший шлях: почати безкоштовно, проіндексувати репозиторій, який ви вже знаєте, підключити клієнта, потім поставити одне запитання, яке можна перевірити.

Знімки позначені часом, тож агент може визначити, яку версію дерева він читає. Чесне обмеження — несинхронізована локальна робота. Якщо правка існує лише в робочому дереві й не була запушена, розміщена карта поки що її не містить. Файли інструкцій (CLAUDE.md, AGENTS.md) досі знаходять тут своє місце для угод і того, чого не слід торкатися. Це не жива карта. Використовуйте їх для поведінки. Використовуйте Maguyva для фактів.

Не дозволяйте агенту відкривати PR, доки цитати не витримають контакт із репозиторієм. Цей бар’єр — весь сенс цього етапу.

2. PR агента

Той самий агент тепер пише зміну в клієнті, за який ви вже платите. Maguyva — не редактор і не рецензент. Агент і далі виробляє diff. Ви і далі відкриваєте пул-реквест на GitHub або GitLab так само, як уже робите.

Що має відрізнятися — це перший файл. PR має називати обробник, який справді реалізує поведінку, виклик, що зламається, і тест, який впаде, якщо зміна неправильна. Якщо етап 1 було пропущено, етап 3 витратить свої коментарі на зміну, що приземлилася не в той пакет. Greptile все ще може знаходити системні проблеми. Йому не має доводитися ще й відновлюватися після галюцинованого шляху.

Тримайте PR у вузьких рамках. Обґрунтований перший файл — не ліцензія на переписування модуля. Ця взаємодоповнювана пара працює, коли агент зробив одну роботу з картою, а потім попросив рецензента зробити іншу роботу над обмеженим diff.

3. Рев’ю Greptile

Greptile вже підключений до репозиторію через застосунок GitHub або GitLab. На новому пул-реквесті він аналізує зміну, використовуючи побудований ним повний граф репозиторію, і публікує знахідки у вигляді коментарів із запропонованими виправленнями. Їхні власні матеріали відводять на цей прохід близько трьох хвилин.

Читайте коментарі так, як читали б уважного колегу по команді: відкрийте процитоване місце, вирішіть, чи реальна знахідка, потім дійте. Там, де Greptile пропонує «Fix with your Agent», він надсилає проблему — шляхи до файлів, номери рядків, запропонований код — у Claude Code, Codex, Conductor, Cursor або Devin. «Fix All» надсилає всі проблеми рев’ю одразу. Вони також постачають Greptile MCP і плагін для Claude Code для цієї передачі. Maguyva немає в цьому поіменованому списку цілей; ця відсутність не проблема. Maguyva вже зробила свою роботу на етапі 1. Кодувальний агент, що написав PR, — це той, хто має отримати навантаження з виправленням.

Очікуйте шум у перші 2–3 тижні, поки навчальна система Greptile адаптується до коментарів, які ваша команда справді залишає. Це їхній заявлений графік, а не дефект пари. Рев’ю людини залишається в циклі. Greptile — автоматизований перший прохід, а не кнопка злиття.

Якщо коментар Greptile вказує на файл, який агент жодного разу не запитував на етапі 1, це корисний сигнал. Або карта пропустила виклик, або агент пропустив цитату. Виправте чернетку відповідно до коментаря. Не вимикайте рецензента.

Як зберегти цю взаємодоповнюваність чесною

Maguyva завжди першою. Рев’ю PR із неправильним файлом усе одно залишається рев’ю неправильного файлу.
Greptile завжди після. Добре процитована чернетка все одно потребує прочитання diff на рівні всієї системи.
Не просіть Maguyva публікувати коментарі до PR. Вона цього не робить.
Не просіть Greptile бути першим шаром пошуку агента, поки він ще обирає шлях. Це не та робота, для якої побудований їхній застосунок GitHub або GitLab.
Не вигадуйте bash-конвеєр, що їх «синхронізує». PR — це інтерфейс.
Перевіряйте обидві сторони незалежно. Проіндексуйте репозиторій, який ви вже знаєте. Поставте одне запитання, яке можна перевірити. Потім відкрийте невеликий PR і прочитайте, що Greptile справді коментує.

Коли цьому дають ім’я, цикл стає звичайним. Спочатку карта. Потім PR агента. Потім рев’ю. Кожен продукт залишається на тій стороні пул-реквесту, на якій він хороший.

// map first. review second. in that order.

Дати ШІ-агенту контекст великого репозиторію без локального індексатора

Fri, 14 Aug 2026 00:00:00 GMT

Великий репозиторій не вміщується в контекстне вікно, і якщо ви хоч раз спрямовували індексатор ноутбука на справжній monorepo, ви знаєте, що там він теж не вміщується комфортно — RAM злітає, перша індексація займає годину, а ваш агент усе ще починає наступну сесію з вгадування, які файли важливі.

Звична відповідь — запускати індексатор поруч із редактором, і для репозиторію, який зручно вміщується на одній машині, це хороша відповідь. Якщо ваш monorepo вже індексується швидко в Cursor і це єдине місце, де вам потрібна карта, цьому тексту нічого додати — пропустіть його.

Цей текст про інший випадок — коли агенту потрібна запитувана карта великого репозиторію, а ви не хочете запускати для цього локальний індексатор.

Коли локальний індексатор — неправильний інструмент

Локальний індекс припускає, що код живе на тій машині, яка його запитує, і в масштабі справжнього monorepo це припущення тріщить навіть усередині одного редактора. Репозиторій просто більший, ніж ви хочете тримати «теплим» на ноутбуці: ви працюєте в одному пакеті, поки радіус впливу на три каталоги далі, а перша холодна індексація дерева у два мільйони рядків — не те, що ви хочете пережити двічі: ні на своїй машині, ні на CI-раннері, який ніколи раніше не клонував це дерево. Або колезі по команді має бути можна запитувати ту саму карту, що й вам, не чекаючи, поки його власна машина прожене той самий індекс.

Ніщо з цього не привід викидати хороший індексатор редактора. Це привід додатково мати розміщену карту, яку будь-який із ваших агентів може запитати через MCP.

І проблема масштабу глибша, ніж «забагато файлів, щоб вставити». На великому дереві цікаве питання майже ніколи не «покажи мені цей файл» — це яких файл, який символ, які виклики, які тести. Агент, що починає з переліку src/ і читання перших трьох результатів, легко пропустить обробник у apps/api і згенерований клієнт у packages/sdk. Вам потрібен пошук, побудований по всьому дереву, потім ранжований, потім процитований.

Що насправді означає «контекст великого репозиторію»

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

Ці відповіді мають надходити з індексу, побудованого за вашим репозиторієм, а не з пам’яті моделі про чужі репозиторії, і цей індекс має жити десь за межами контекстного вікна агента. Для цієї задачі він також має жити десь за межами вашого ноутбука.

Ще одна річ, яку файли інструкцій не можуть зробити за вас: CLAUDE.md і AGENTS.md — правильне місце для угод і поведінки, але це не жива, ранжована, запитувана карта дерева у два мільйони рядків. Використовуйте правила для поведінки; використовуйте інтелект репозиторію для фактів.

Будуємо карту в хмарі, запитуємо її з будь-якого клієнта

Maguyva — це віддалений MCP-шар контексту кодової бази. Ви підключаєте GitHub, обираєте свої репозиторії й можете йти, поки хмарні конвеєри розбирають дерево, будують символи й ребра графа та підтримують ранжовану карту — без локального індексатора, ніколи.

Коли ви пушите код, змінені файли розбираються інкрементально, а шари графа й ранжування перебудовуються за розкладом: щодня на безкоштовному плані, щогодини на платних. Кожен знімок позначений часом, тож ваш агент може визначити, яку версію дерева він читає. Чесне обмеження тут — несинхронізована локальна робота: правка, що існує лише у вашому робочому дереві й ніколи не була запушена, ще не потрапила до розміщеної карти.

Потім ви підключаєте будь-якого клієнта, яким уже користуєтеся, додавши API-ключ до його конфігурації MCP. Є посібники з налаштування для 24 задокументованих MCP-клієнтів, і будь-який інший MCP-сумісний клієнт, що підтримує стандартну конфігурацію, теж може підключитися. Якщо Cursor — ваш дім, сторінка Cursor проведе цим шляхом; той самий сервер відповідає Claude Code, VS Code, Windsurf, Codex CLI та іншим.

Вам не потрібно міняти редактор. Ви даєте своєму агенту поверхню інструментів — 11 MCP-інструментів для пошуку, символів, аналізу залежностей, отримання файлів і контексту репозиторію — з покриттям понад 279 мов і текстових технологій, що важить більше, ніж здається, на monorepo, який перестав бути одномовним багато років тому.

Відповіді повертаються обґрунтованими, у вигляді шляхів до файлів із номерами рядків. Семантичний, структурний, графовий і текстовий пошук зливаються в ранжовані результати, тож запитання на кшталт «що залежить від parseConfig» дає не звалище grep і не єдиний семантичний фрагмент, а жменьку місць, які справді важливі.

Конкретна інструкція

Не починайте з індексації всієї компанії. Ось шлях, який працює:

Оберіть один репозиторій, який ви вже добре знаєте — пакет, який ви можете оцінити вручну, вартий більше, ніж найбільше дерево, яке у вас є.
Почніть безкоштовно: 3 репозиторії, 50 тисяч проіндексованих рядків, усі 11 інструментів, без місячної квоти запитів. Якщо ваш репрезентативний репозиторій більший, сторінка тарифів перелічує рівні робочого простору ($0, $19, $49, $149) за обсягом індексації, а не за кількістю місць.
Підключіть GitHub і зачекайте завершення першої індексації. Ви нічого не компілюєте локально.
Підключіть MCP-клієнта — кілька рядків конфігурації. Maguyva — віддалений MCP-сервер, тож немає ні плагінів, ні розширень, ні другого редактора, який потрібно освоювати.
Поставте одне запитання, яке можна перевірити. «Що залежить від parseConfig?» або «Де обробляється закінчення сесії входу?» Потім відкрийте процитовані результати file.ext:line і звірте їх із деревом перед вами.
Лише після того, як цитати витримають цю перевірку, дозвольте агенту редагувати.

Якщо перший репозиторій підійшов, а ваше дерево велике, підвищте робочий простір відповідно до проіндексованих рядків і періодичності перебудови. Люди й агенти ділять один і той самий лічильник користувачів — Maguyva бере плату за робочий простір, а не за місце, — тож додавання третього агента до циклу нічого вам не коштує.

Тест активації той самий, що документація рекомендує для будь-якого першого запуску: проіндексуйте репозиторій, який ви вже знаєте, поставте одне запитання, яке можна перевірити. Великий репозиторій не змінює тест; він лише робить неправильний перший файл дорожчим.

На що звертати увагу після підключення

Слідкуйте за трьома речами. Актуальність: платні плани перебудовуються щогодини, безкоштовні — щодня, і непушнута локальна робота не потрапить до карти — це компроміс, на який ви йдете. Обсяг: індексуйте репрезентативний набір репозиторіїв, а не кожен заархівований форк; безкоштовний рівень навмисно розрахований на те, щоб зрозуміти, чи варті відповіді того, щоб їх зберігати. І перевірка: карта великого репозиторію, яка не може процитувати шляхи та номери рядків, — це просто повільніша машина для вгадування, тож нехай агент покаже місце, перш ніж постачати патч.

Потім запустіть той самий тест, що й на маленькому репозиторії. Проіндексуйте репозиторій, який ви вже знаєте. Поставте одне запитання, яке можна перевірити. Якщо карта справжня, ваш агент перестане починати з холодного дерева.

// no laptop got hot building this map.

Чому ваш ШІ-агент для коду галюцинує шляхи до файлів

Fri, 14 Aug 2026 00:00:00 GMT

Ознака — не неправильне тіло функції. Це впевнена правка файлу, якого не існує, або файлу, який існує, але не реалізує потрібну поведінку.

Ви попросили виправити закінчення сесії. Агент відкрив src/auth/session.ts. Цей шлях правдоподібний. Він же й неправильний. Справжній обробник живе в apps/api/src/middleware/expiry.ts, перейменованому два рефакторинги тому. Агент вам не збрехав. Він завершив рядок у формі шляху на основі апріорних знань із тренування плюс усього, що вже було в контекстному вікні.

Це поширений патерн відмови на справжньому репозиторії. Модель уміє писати код. Помилка — у виборі неправильного місця для його написання.

Чому агенти вигадують шляхи

Кодувальний агент — це модель передбачення наступного токена з інструментами. Коли ви кажете «полагодь закінчення сесії», йому потрібно назвати файл, перш ніж він зможе щось прочитати або пропатчити. Якщо в нього ще немає обґрунтованої карти, він конструює шлях із:

Угод про іменування, які він бачив в інших репозиторіях. src/auth/session.ts — часта форма.
Файлів, уже присутніх у розмові, які можуть бути тими, що ви вставили минулого тижня, а не тими, що важливі зараз.
Лістингів каталогів, які він випадково виконав, неповних на великому дереві.
Файлів інструкцій. CLAUDE.md і AGENTS.md кажуть агенту, як поводитися. Це не живий індекс символів, викликів чи поточних шляхів.

Жодне з цих джерел не є картою цього репозиторію сьогодні. Модель заповнює прогалину так само, як заповнює будь-яку прогалину: високоймовірним продовженням. Це продовження часто виглядає як справжній шлях. Іноді файл існує й міститься поруч із правильним. Іноді він існував у гілці, злитій минулого місяця. Іноді він ніколи не існував.

Grep не врятує вас тут, якщо агент узагалі не шукає правильний рядок. Агент вгадав шлях, потім прочитав те, що цей шлях повернув, потім відредагував. Першим неправильним кроком був шлях, а не патч.

Читання файлів — теж не те саме, що знаходження правильних. Claude Code, Cursor, Codex і подібні інструменти можуть відкрити що завгодно, на що ви їм вкажете. Питання в тому, чи знаходять вони надійно правильні файли, важливі символи, залежності, тести та радіус впливу до того, як редагують. Доступ до файлів без карти все одно починається з вгадування.

Правка неправильного файлу — це проблема пошуку

Ставтеся до вигаданого шляху як до промаху пошуку, а не як до дефекту характеру.

Якби агенту потрібно було повернути path/file.ext:line, перш ніж йому дозволять редагувати, сталися б дві речі. По-перше, ви могли б відкрити цитату й відхилити роботу за десять секунд. По-друге, агенту довелося б запитати щось, що справді знає дерево.

Це робота шару контексту кодової бази. Самого семантичного пошуку недостатньо. Фрагмент, що «звучить як закінчення сесії», усе одно може приземлитися в застарілому пакеті. Вам також потрібен точний текст, коли ви знаєте рядок, пошук символів, коли ви знаєте ім’я, структурний пошук, коли ви знаєте форму, і граф залежностей, коли вам потрібні виклики й радіус впливу.

Maguyva — цей шар для MCP-сумісних кодувальних агентів. Це не редактор. Claude Code, Cursor, Codex CLI, VS Code, Windsurf та інші MCP-клієнти залишаються там, де вони є. Агент запитує ранжовану карту, перш ніж торкнутися рядка.

Твердження навмисно скромне: менше галюцинованих правок. Maguyva не позбавляє модель здатності вгадувати. Вона змінює перший крок за замовчуванням із «вигадати правдоподібний шлях» на «запитати ранжовані, процитовані місця».

Як виглядає обґрунтована відповідь

Корисна відповідь на питання «де обробляється закінчення сесії» — не абзац тексту. Це короткий список місць:

apps/api/src/middleware/expiry.ts:48 - обробник
apps/web/src/lib/auth-client.ts:112 - виклик
apps/api/tests/expiry.test.ts:20 - тест, який впаде, якщо зміна неправильна

Ви можете відкрити ці рядки. Якщо вони неправильні, ви зупиняєтеся. Якщо правильні, агент може редагувати. Суть у перевірці, а не в гаслі.

Maguyva надає 11 клієнтських MCP-інструментів для пошуку, символів, аналізу залежностей, отримання файлів, контексту репозиторію та детермінованих службових робочих процесів. Чотири режими пошуку (семантичний, структурний, графовий/залежнісний і текстовий) зливаються в ранжовані результати; пошук символів — окремий MCP-інструмент (find_symbol). Обґрунтовані відповіді повертаються зі шляхами до файлів і номерами рядків, тож ви можете оцінювати їх за деревом перед вами.

Документація описує найкоротший шлях: почати безкоштовно, проіндексувати репозиторій, який ви вже знаєте, підключити клієнта, потім поставити одне запитання, яке можна перевірити.

Цикл, що змінює першу правку

Вам не потрібна нова релігія робочого процесу. Вам потрібен один додатковий крок перед першим записом.

Поставте запитання, яке ви вже можете оцінити. «Який код обробляє вхід і закінчення сесії?» краще, ніж «полагодь автентифікацію».
Вимагайте цитат. Шлях до файлу й номер рядка, а не переказ «модуля автентифікації».
Відкрийте процитовані файли. Простежте символ. Підтвердьте залежність, яку ви збираєтеся торкнутися.
Лише тоді дозвольте агенту пропатчити.

Якщо крок 2 не повертає нічого корисного, у агента немає права імпровізувати шлях. Він шукає знову, або ви йому вказуєте. Саме цей єдиний бар’єр виробляє менше галюцинованих правок. Модель — та сама модель. Змінилася карта.

Файли інструкцій досі важливі. Збережіть їх. Використовуйте їх для угод, правил рев’ю та того, чого не слід торкатися. Не просіть їх бути індексом. CLAUDE.md, що перелічує три важливі каталоги, застаріє через тиждень після поділу пакета. Запитувана карта оновлюється, коли оновлюється репозиторій.

Споріднений збій — майже правильний файл: агент відкриває auth.ts, коли поведінка живе в auth-client.ts, або патчить згенерований файл замість вихідного, або редагує копію в packages/legacy, бо ім’я збіглося. Цитати не роблять ці помилки неможливими. Вони роблять їх видимими до того, як diff приземлиться.

Чого карта не виправить за вас

Будьте тверезі щодо того, що ви отримуєте. Обґрунтована карта не зробить кожну правку правильною — ваш агент усе одно може написати поганий патч у точно правильному файлі. Якщо ваша кодова база спирається на динамічну диспетчеризацію, рефлексію чи манкіпатчинг, деякі пошуки символів повертатимуться біднішими, ніж вам хотілося б, бо саме це робить рантайм-непрямість з будь-яким статичним індексом. І якщо ви сподіваєтеся на відсоток — «галюциновані шляхи скоротилися на X%» — ви його тут не знайдете, бо ніхто, крім вас самих, не може чесно виміряти цю цифру для вашого репозиторію.

Чого ви можете очікувати — вужче й корисніше: агент перестає починати правки з вгаданого шляху. Цей перший крок стає обґрунтованим справжньою картою, і саме звідси береться менше галюцинованих правок. Усе після цитати — читання diff, оцінка патча — і далі ваша робота, як і завжди.

Цей тест майже нічого вам не коштує: проіндексуйте репозиторій, який ви вже знаєте, і поставте одне запитання, яке можна перевірити. Почніть зі шляху, на якому вас уже обпікало. Якщо цитати неправильні, ви побачите це негайно. Якщо правильні, наступна правка вашого агента отримає краще місце для приземлення.

// it doesn't know the file. it knows how to find it.

Чому ми оновили пошук коду до voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Числа бенчмарків у цьому дописі відображають рейтинги RTEB на момент публікації (червень 2026). Рейтинги змінюються; сприймайте позиції як знімок моменту, а не постійний факт.

Семантичний пошук настільки хороший, наскільки хороші ембеддинги під ним.

Коли агент запитує Maguyva «де ми обробляємо повторні спроби», він не грепає слово «retry». Він запитує сенс — цикл backoff, запобіжник (circuit breaker), те, що обгортає ненадійний виклик. На це запитання відповідає векторна модель, що перетворює код на точку в просторі й знаходить сусідів. Оберіть кращу модель, і кожен семантичний запит у продукті тихо стає точнішим.

Тож ми змінили нашу. Станом на червень 2026 року ембеддинги коду Maguyva працюють на voyage-4-large, замінивши voyage-code-3.

Бенчмарк

Ми не ухвалювали це рішення на відчуттях. Публічний Retrieval Embedding Benchmark (RTEB) ранжує моделі ембеддингів на реальних задачах пошуку, і в його рейтингу Code voyage-4-large посідає #1 загалом (90.86) — попереду gemini-embedding-2-preview (90.26) і, що важливо, попереду моделі, яку ми вже використовували, voyage-code-3 (89.73, #3).

Це невеликий абсолютний розрив. Але це розрив у правильному напрямку, на публічному бенчмарку, на точно тій задачі, яка нас цікавить: пошук коду за сенсом.

Компроміс, на який ми йдемо: бінарна квантизація

Ось та частина, яку більшість дописів «ми оновили нашу модель» пропускають.

Maguyva не зберігає вектори повної точності. Ми зберігаємо бінарно-квантизовані ембеддинги: кожен 2048-вимірний вектор стискається до 2048-бітного підпису — 256 байт на вектор. Ці підписи шукаються за відстанню Хеммінга, індексовані та розділені по тенантах.

Це навмисний компроміс. Бінарна квантизація жертвує деякою точністю пошуку в обмін на значно менший обсяг зберігання та швидке й дешеве обчислення відстані без окремої векторної бази даних для експлуатації. Для продукту, що індексує цілі репозиторії на робочий простір, ця економіка важливіша, ніж вичавлювання останньої частки бенчмаркового балу.

voyage-4-large вписується в цей дизайн без примусової міграції шару сховища: вона видає 2048-вимірний вивід, так само як voyage-code-3, тож наші колонки bit(2048) та шлях пошуку за Хеммінгом не змінилися. Модель стала кращою; схема залишилася на місці.

Код був лише початком

Maguyva — інструмент інтелекту коду. Але ми також клієнт номер нуль, і ми спрямовуємо його на дещо інше: markdown, що живе в наших репозиторіях поруч з кодом. Записи архітектурних рішень, runbook-и, контракти, фінансові документи та внутрішні політики — усе це під контролем версій у Git, усе за тим самим сервером MCP, семантичний індекс над документами, а не лише над джерельним кодом.

Саме тому широта voyage-4-large має значення. У тій самій родині рейтингів RTEB вона #1 у фінансах, #1 в охороні здоров’я і #1 у загальному текстовому пошуку — попереду Gemini Embedding від Google, Embed v4 від Cohere та text-embedding-3-large від OpenAI. (Voyage — співтворець RTEB, тож ми сприймаємо це як сильний публічний сигнал, а не як абсолютно нейтрального суддю — але вона бенчмаркується напряму проти кожної великої комерційної моделі на приватних відкладених наборах.) Той самий індекс, що знаходить потрібну функцію для агента, знаходить потрібне положення в контракті чи потрібний рядок у документі внутрішньої політики — і в цих доменах voyage-4-large не компроміс, а лідер.

Чому ми платимо за преміум-ембеддинги

Існує дешевший спосіб робити пошук, і чимало з нього безкоштовне. Лексичний пошук — BM25 та його родичі — зіставляє ключові слова, працює локально й нічого не коштує. Моделі ембеддингів з відкритим кодом на кшталт BGE, Nomic та embeddinggemma дають справді пристойний семантичний пошук, і їх можна хостити самостійно за ціну GPU. Maguyva також використовує безкоштовний бік: кожен запит зливає текстовий, AST, графовий та семантичний пошук. На чому ми не економимо — це семантичний шар.

Ми платимо за токен за преміум-ембеддинги — voyage-4-large — замість того щоб самостійно хостити безкоштовну модель, з двох причин. По-перше, самого лише пошуку за ключовими словами недостатньо, щоб відповісти на «де ми обробляємо повторні спроби», коли код каже backoff та circuit breaker і ніколи не каже слово «retry» — саме передавання сенсу є призначенням ембеддингу, і в доменах, які ми обслуговуємо, відкриті моделі відстають від преміум: на пару балів на загальному тексті, і ще більше в нішах на кшталт коду, контрактів та фінансів. По-друге, за нашим досвідом, якість пошуку формує фінальну відповідь більше, ніж модель на іншому кінці — сильний агент, якому дали неправильний контекст, все одно відповість неправильно, і він ніколи не побачить документ, якого йому ніколи не дали.

Тож преміум-ембеддинги — це рахунок за токен, що масштабується з кожним репозиторієм і документом, який ми індексуємо — і ми платимо його навмисно. Заради результату, який отримують наші користувачі — правильної функції чи правильного положення — ми вважаємо, що цей компроміс вартий того.

Чесна частина

Власна документація Voyage все ще позначає voyage-code-3 як модель, оптимізовану для коду. То чому ж перехід?

Бо ми читаємо публічний бенчмарк, а не лише таблицю моделей вендора, а бенчмарк поставив voyage-4-large на вершину для пошуку коду. Це було рішення з поглядом уперед: взяти новішу, загалом сильнішу модель і валідувати її проти публічного рейтингу на задачах, які мають значення. Нам комфортно робити цю ставку, бо докази широкі — voyage-4-large не просто перемагає в коді, вона також лідирує у фінансах, охороні здоров’я та загальному пошуку.

Непомітна основа

Кожен інструмент, який ми надаємо — семантичний пошук, збір контексту задачі, обґрунтовані запитання й відповіді — врешті-решт спирається на пошук. Коли ретрівер покращується, агент на іншому кінці отримує кращі докази, рідше ухвалює хибні рішення і обґрунтовує свої відповіді правильним кодом — або потрібним положенням контракту чи потрібною внутрішньою політикою. Точніша модель ембеддингів — не яскрава функція. Це основа всього іншого, і ми щойно підвищили її якість. Ви цього не помітите. У цьому й суть.

Рекурсивне самовдосконалення мов: шліфування інтелекту коду для ~280 мов

Tue, 26 May 2026 00:00:00 GMT

Числа в цьому дописі відображають стан системи на момент публікації (травень 2026). Актуальні цифри дивіться на нашій сторінці команди.

Maguyva вилучає символи, посилання та граф залежностей із вихідного коду приблизно 280 мов. Кожна мова — це кастомний обробник tree-sitter — запити, евристики, крайові випадки — і кожен обробник може бути хибним по-своєму, тонко й непомітно. Виклик методу, поданий як читання. Функція, приписана не тій зовнішній області видимості. Зв’язок, якого просто не існує.

Це неможливо перевірити вручну. Жодна команда не здатна прочитати результати вилучення для 280 граматик і виявити погані ребра графа. Тож цікаве запитання не «чи правильне наше вилучення» — а «як дізнатися, що воно неправильне, за такого масштабу, без людини в кожному циклі». Наша відповідь — рекурсивне самовдосконалення мов: цикл якості, керований мовними агентами, LLM у ролі судді, і одне правило, яке ми постійно засвоюємо заново: зелений не означає правильний.

Зелений не означає правильний

Кожна мова має набір фікстур, і перевірка перед випуском оцінює її за п’ятьма вимірами — точність, структурна цілісність, повнота, якість та продуктивність. Мова стає GREEN (зеленою) лише тоді, коли на її фікстурах precision ≥ 0.95, recall ≥ 0.99 та F1 ≥ 0.97, з щонайменше 20 очікуваними ребрами для статистичної довіри. Нижче цього — YELLOW чи RED, і мова не постачається.

Ця перевірка необхідна, але недостатня. Фікстури перевіряються за фікстурами, які написали ми самі. Вони кодують випадки, які ми вже передбачили. Обробник може бути бездоганним на своїх фікстурах і все одно спотворювати патерн, який трапляється лише в реальному коді — макро-ідіому, метод з обмеженнями узагальненого типу, мовну особливість, для якої ніхто не написав фікстуру. GREEN означає, що фікстури проходять. Це не означає, що реальний репозиторій вилучається чисто. Тож циклу доводиться залишити фікстури позаду й перевірити реальний код.

Внутрішній цикл: вибіркова перевірка, суддя, виправлення, доведення

Основний цикл обробляє одну мову за раз:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Кілька принципів допомагають цьому процесу давати результат, а не тупцювати на місці.

Суддя — це агент, а не виклик API. Коли ми кажемо «LLM як суддя», ми маємо на увазі, що сам мовний агент звіряє кожне вибране ребро графа з реальним вихідним кодом і класифікує його за фіксованою рубрикою з п’яти категорій: чи це ребро правильне, хибнопозитивне, правильний зв’язок з неправильним типом, прив’язане не до тієї області видимості, чи несе неправильні метадані? Ця рубрика — вся суть гри: «23% рівень помилок» нічого не означає, доки ви не знаєте, чи це реальні дефекти, чи суддя рахує неправильно.

Виправити одну річ, потім довести це. Кожна ітерація змінює рівно один редагований файл, потім повторно виконує перевірку в незмінному тестовому середовищі і зберігає зміну лише тоді, коли F1 покращується, а повторна класифікація виглядає краще. Якщо ні — зміна відкочується. Жодного пакетного набору правок на основі припущень, жодного «має стати краще». Зміна заслуговує на своє місце, або зникає. А коли виправлення закріплюється, воно потрапляє в набір фікстур — тож баг, який воно виправило, більше ніколи мовчки не повернеться. Саме цей крок промоції робить цикл рекурсивним, а не просто повторюваним: кожен прохід зміцнює оракул, проти якого валідується наступний прохід.

Урок, який ми постійно засвоюємо заново: метрики завищують кількість проблем

Ось пастка, і ми прямо в неї потрапили. Вторинні метрики корпусу — як часто вилучена ціль не має символу, який можна визначити, скільки символів виглядають «осиротілими» і так далі — масово завищують кількість проблем. Здебільшого це артефакти парадигми, а не баги.

Найчистіший приклад: llvm одного разу показав 73% рівень «джерела без символу» і був заклеймований як катастрофічний. Ми копнули глибше. Реальна точність становила 98.5%. «Відсутні символи» майже всі були легітимними зовнішніми посиланнями — викликами до стандартної бібліотеки, до фреймворків, до коду, що живе поза репозиторієм. Метрика вимірювала властивість мови, а не дефект обробника. Мови на кшталт Zig, COBOL та Odin показують рівень «осиротілості» 65–70% і при цьому цілком правильні; у COBOL не було жодної реальної помилки.

Якби ми дозволили цим числам керувати роботою, ми витратили б тижні на «виправлення» обробників, які вже були правильними, ігноруючи мови з тихими, реальними багами. Висновок різкий: агреговані метрики в найкращому разі — грубий сигнал для тріажу. Справжній сигнал якості — це вибіркова перевірка з класифікацією ребер — погляд на реальні ребра в реальних репозиторіях і суддівство по одному. Дані понад інтуїцію, але лише коли ви знаєте, які дані кажуть правду.

Зовнішній цикл: флот, а не марафон

Обробка однієї мови за раз для всіх 280 тривала б вічність, тож внутрішній цикл обгорнутий у зовнішній, що запускає багато мов паралельно.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Кожен агент працює у тимчасовому робочому дереві (worktree), щоб вони не заважали одне одному. Оркестратор інтегрує їхні виправлення по одному, кожне за перевіркою регресії на повному маніфесті: зміна, яка допомагає своїй власній мові, але тихо ламає три інші, не приймається. Інтеграція проходить перевірку й отримує підтвердження, перш ніж щось буде відправлено (push) — перевірка на регресії визначає, що безпечно, людина все ще вирішує, що постачається. Потім пул перемикається на наступний набір мов, і весь процес запускається знову.

Що досі недосконале

Суддя може помилятися, і в цієї помилковості є напрямок: агент, що працює з надто малим контекстом, завищує кількість проблем. В одній партії вісім мов було позначено з 5–20% помилок; під час перевірки реальний баг підтвердився лише в одній мові — решта були помилками судді через пропуск власної семантики мови (один рядок джерела легітимно породжує кілька ребер, зв’язування параметрів моделюється як присвоєння, мови з посиланням на кожен ідентифікатор). Саме тому ми вибираємо з двома сідами (seeds) і перехресно перевіряємо, і саме тому розбіжність між суддею і фікстурами трактується як найцікавіший сигнал, а не остаточний вердикт — іноді помиляється саме фікстура.

Ми також чесні щодо мети. Мета — нуль реальних помилок, крапка — але «нуль» це напрямок, до якого ми послідовно рухаємося, вдосконалюючи підтримку кожної мови, а не галочка, яку можна поставити. Завжди є ще один репозиторій з ще однією ідіомою.

Заслужене, а не заявлене

Усе, що Maguyva робить для агента — знаходить символ, простежує залежність, відповідає на запитання з цитованим кодом — спирається на те, що вилучення, на якому все це ґрунтується, працює правильно. У межах 280 мов «правильність» не можна просто заявити; її потрібно постійно заслуговувати на реальному коді. Цикл — це те, як ми її заслуговуємо: автономний цикл вибіркової перевірки й виправлення, що ставиться до власних метрик з підозрою, доводить кожну зміну і перетворює кожне виправлення на запобіжник проти наступної регресії. Це не гламурно. Це та робота, яка дозволяє нам сказати «ми підтримуємо вашу мову» і мати це на увазі. Зелений — легко. Правильний — заслужений.

Мультимодальний пошук зі злиттям: обираємо правильний ретрівер для кожного запиту

Wed, 15 Apr 2026 00:00:00 GMT

Примітка про історичну архітектуру: ця стаття від квітня 2026 року описує тогочасну архітектуру маршрутизації, а не поточну поведінку за замовчуванням. Вересневе виправлення нижче стосується лише твердження про вимірювання. Про поточну маршрутизацію, попередньо задані налаштування та явне керування модальностями див. Як це працює.

Пошуковий запит — це не одна річ.

«де визначено parseConfig» хоче точний символ — одне точне місце, швидко. «як працює автентифікація» хоче сенс — розкидані пов’язані фрагменти коду, що пояснюють концепцію. «що зламається, якщо я зміню цю функцію» хоче граф залежностей. «знайди рядок ECONNREFUSED» хоче буквальний збіг, нічого хитрого.

Grep чудовий для буквальних збігів і корисний для деяких пошуків посилань, але це не граф залежностей, і він не розуміє сенсу. Ембеддинги покривають семантичний бік, але вони — неправильний інструмент для точних рядків та аналізу впливу. Більшість інструментів пошуку коду обирають один рушій і змушують кожен запит жити з цим вибором. Maguyva не обирає. Він з’ясовує, яке саме запитання ви поставили, а потім змішує чотири ретрівери в пропорції, якої заслуговує це запитання.

Чотири режими

Під капотом є чотири незалежні способи знайти код:

semantic — векторний пошук за бінарними ембеддингами Voyage; знаходить код за сенсом.
text — триграмне зіставлення; знаходить літерали, рядки помилок, точні ідентифікатори.
structural — запити AST; знаходить визначення, сигнатури та мовні конструкції.
graph — граф залежностей; знаходить викликачів, викликаних та радіус впливу.

Кожен сильний у своєму класі запитань. Хитрість у тому, щоб вирішити, наскільки довіряти кожному для конкретного запиту перед вами.

Класифікація наміру

Перш ніж запуститься будь-який пошук, легкий класифікатор сортує запит в один з шести намірів, з оцінкою впевненості. Він навмисно дешевий — упорядковані евристики, перший збіг перемагає — бо працює на гарячому шляху й додає лише мілісекунду-дві:

починається з def , class , func , import … → find_definition (впевненість 0.95)
«who calls», «usages of», «references to» (хто викликає, використання, посилання) → find_references (0.90)
«impact», «blast radius», «what depends on» (вплив, радіус впливу, що від цього залежить) → impact_analysis (0.90)
рядок у лапках "string" чи токен помилки на кшталт traceback → exact_match (0.85–0.90)
ідентифікатор CamelCase чи snake_case → find_definition (0.60–0.80)
«how», «why», «explain», «architecture» (як, чому, пояснення, архітектура) → understand_code (0.75)
нічого не збігається → understand_code, низька впевненість (0.40)

Кожен намір несе профіль ваг серед чотирьох режимів. Ось реальні цифри:

Намір	semantic	text	structural (AST)	graph
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

Тож «де визначено parseConfig» сильно спирається на AST (0.6). «як працює автентифікація» спирається на семантичні вектори (0.5). «що залежить від цього» майже повністю graph (0.7). «знайди ECONNREFUSED» майже повністю триграма (0.9), а модель ембеддингів повністю вимкнена — бо семантична подібність це саме неправильний інструмент для точного рядка.

Швидкий шлях і шлях зі злиттям

Коли класифікатор впевнений — оцінка ≥ 0.85 — і запит звичайний, Maguyva повністю пропускає злиття й спрямовує запит прямо в єдиний домінантний режим. «де визначено X» не потребує чотирьох ретріверів; йому потрібен індекс AST, зараз. Цей прямий шлях повідомляється назад як fusion_strategy: "direct".

Усе неоднозначне проходить через злиття. Чотири (або три, у пресеті за замовчуванням) режими запускаються паралельно, кожен повертає свій ранжований список, і ми їх об’єднуємо.

Зважене Reciprocal Rank Fusion

Злиття різнорідних ретріверів складніше, ніж здається: косинусна подібність 0.82, триграмна оцінка 137 і графова центральність 0.004 — не в одній шкалі, тож просто скласти їх не можна. Reciprocal Rank Fusion обходить проблему, відкидаючи сирі оцінки й залишаючи лише ранг, який присвоїв кожен рушій. Внесок результату від одного режиму:

contribution = weight × 1 / (k + rank + 1)

де rank — його позиція в списку цього режиму, а k — константа згладжування. Внески підсумовуються серед режимів для будь-якого результату, який знайшов більш ніж один рушій — узгодженість між ретріверами природно спливає нагору. Ми використовуємо k = 40 у пресеті за замовчуванням і 60 на thorough (quick працює лише семантично, тож злиття там ніколи не задіюється). Оригінальна робота з RRF зупинилася на k = 60 для загального пошуку; наше налаштування за замовчуванням дещо сильніше виділяє верхні позиції, надаючи трохи більшу вагу результатам, які кілька режимів одночасно ранжують високо — і ми не рекомендуємо налаштовувати це вручну.

Окрім цього, результати несуть посилення за важливістю графа. Хаб — функція, на яку спирається вся кодова база — має обходити за рангом малопомітний листовий вузол, навіть за однакової текстової релевантності, тож ми множимо кожен внесок на:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

Центральність береться з попередньо обчислених метрик PageRank/ступеня конвеєра, а посилення обмежене 1.5×, щоб популярна функція не могла повністю поховати релевантнішу, але малопомітну. Насамкінець ми знижуємо ранг результатів зі шляхів vendor, build та archive, і усуваємо дублікати, залишаючи найкращий фрагмент на файл.

Що досі недосконале

Класифікатор наміру — це набір регулярних виразів, а не навчена модель. Він обробляє поширені форми запитів за допомогою евристик, а неоднозначний запит переходить до understand_code і суміші з перевагою семантики. У попередній версії цієї статті зниження частки запитів без результатів приблизно з 15% до менш ніж 5% було описано як досягнуте. Насправді пропозиція від грудня 2025 року містила оцінку початкового рівня та цільове значення; підтвердного набору запитів або протоколу вимірювань не надано. Ми відкликаємо це твердження про досягнуте поліпшення; див. вихідні підтвердні матеріали та виправлення (англійською). Ми не замінили класифікатор навченою моделлю, бо недорога версія досить швидка й придатна для своєї задачі маршрутизації, а хибний, але впевнений класифікатор гірший за чесний запасний варіант. Самі ваги — це вручну обрані апріорні значення, а не значення, вивчені з даних про кліки, яких ми не збираємо.

Став запитання, а вибір інструмента залиш системі

Агенту не повинно бути потрібно знати, чи тягнутися до grep, чи до ембеддингів, чи до графа викликів — він має ставити своє запитання простими словами й отримувати правильну відповідь. Мультимодальне злиття — це те, що дозволяє find_symbol, семантичному пошуку та аналізу залежностей працювати через єдиний інтерфейс запитів: система читає форму запитання й тихо збирає для нього правильний ретрівер. Модель, що оцінює ембеддинги, важлива, але так само важливо знати, коли не використовувати їх. Обрати правильний інструмент для кожного запиту — це свій особливий вид якості, і ми радше візьмемо його на себе, ніж перекладемо на того, хто викликає.

// you bring the question. it brings the tools.

Спостережуваність агентів: хуки, Alloy та Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Агентні системи ламаються дивними способами.

Іноді проблема в моделі. Іноді проблема в інструменті. Іноді ваш сервер MCP у порядку, але агент обрав не того спеціаліста, або витратив половину сесії на роботу з shell, якої ви не очікували, або мовчки спалив кошти в циклі, що зовні виглядав продуктивним.

Якщо ви не бачите різниці, ви насправді не керуєте агентною системою. Ви вгадуєте.

Тож ми побудували стек спостережуваності для нашого власного робочого процесу: Claude Code, Codex, події хуків Claude, події сповіщень Codex, нативний OpenTelemetry, Grafana Alloy та Grafana Cloud на іншому кінці.

Цікава частина не в тому, що «ми зробили дашборд». Цікаво те, що нам довелося розділити телеметрію на два різні потоки, бо жоден окремий канал не давав повної картини.

Проблема: телеметрія агентів фрагментована

Сучасні агенти для програмування вже надсилають певну телеметрію. Це допомагає, але цього недостатньо.

Нативний OTEL добре відповідає на запитання на кшталт:

Скільки запитів ми зробили?
Скільки коштувала сесія?
Де спани та трейси?
Чи стрибнула затримка?

Він набагато гірше відповідає на запитання на кшталт:

На який сервер MCP спирався агент?
Ця помилка сталася в Bash, у вбудованому файловому інструменті чи у виклику MCP?
Яка навичка насправді активувалася?
Який тип субагента було відправлено?
Сесія робила корисну роботу чи просто буксувала?

Цей другий клас запитань живе ближче до хуків, ніж до трейсів.

Але правильне й зворотне твердження: деякі з найважливіших запитань про продуктивність живуть ближче до трейсів, ніж до хуків.

Якщо ви хочете знати, де насправді накопичилася затримка, які спани були повільними, чи сесія витратила час на виклики моделі, а не на виконання інструментів, вам потрібні дані трейсів так само, як і семантичні події.

Архітектура, до якої ми прийшли

Ми запускаємо два шляхи телеметрії паралельно.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Цей поділ навмисний.

Він також асиметричний. Claude Code дає нам набагато функціональніший інтерфейс хуків життєвого циклу. Codex дає нам нативний OTEL плюс інтерфейс сповіщень, тож ми нормалізуємо менш докладні події завершення ходу в ту саму схему логів, замість того щоб вдавати, ніби обидва середовища виконання надають однакові засоби керування.

Нативний OTEL дає нам базовий потік: логи та трейси від самого середовища виконання, плюс метрики там, де середовище виконання їх справді надсилає.

Події хуків і сповіщень дають нам семантичний шар: такі речі, як PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, та класифіковані метадані, які нас справді цікавлять під час діагностики поведінки агента. Claude Code надає тут багатший потік подій. Codex надає менш докладний, але все ще корисний нормалізований потік.

Навіщо взагалі потрібні хуки

Наш конвеєр хуків збагачує події, перш ніж вони потрапляють у Loki.

Замість того щоб просто сказати «інструмент виконався», ми класифікуємо подію за полями на кшталт:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: який бекенд MCP обробив виклик
bash_cli: родина shell-команди
subagent_type: який тип спеціаліста було відправлено
agent_tool: чи джерелом був Claude Code, чи Codex

Це означає, що ми можемо ставити операційно важливі запитання:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Це не поля заради галочки. Це різниця між «агент здавався повільним» і «агент витратив останні десять хвилин на операції git через shell із високою частотою помилок інструментів».

Одна деталь реалізації, яка виглядає дивнішою, ніж є насправді: спільний потік Loki все ще використовує service_name="claude-code-hooks" як мітку, навіть коли подія прийшла з Codex. Реальний поділ між середовищами виконання відбувається за agent_tool.

Чому Alloy стоїть посередині

Grafana Alloy у цій конфігурації не просто пересилач. Це точка застосування правил обробки телеметрії.

Ми спрямовуємо нативний потік OTEL від Claude Code та Codex на локальний проксі Alloy на localhost:4318, а потім дозволяємо Alloy очистити payload, перш ніж пересилати його до Grafana Cloud.

Це важливо, бо сира телеметрія агентів переповнена полями з високою кардинальністю, які корисні для аналізу, але жахливі як індексовані мітки:

session_id
prompt_id
кількість токенів
тривалості
блоби параметрів інструментів

Якщо індексувати все, отримаєте вибух міток і поганий день.

Тож Alloy робить для нас три речі:

Тримає індексованим дуже невеликий набір міток з низькою кардинальністю.
Переносить шумні, але корисні поля в структуровані метадані.
Повністю відкидає чистий шум.

Важлива ідея проста: спостерігай більше, індексуй менше.

Чому потік хуків обходить Alloy

Потік хуків уже сформований для Loki.

До того моменту, коли send_event.py надсилає подію, ми вже вирішили, які поля заслуговують на обробку як мітки, а які належать до структурованого тіла JSON. Цей потік іде прямо до OTLP-шлюзу Grafana Cloud, замість того щоб проходити ще один прохід через Alloy.

Тож у системи чіткий розподіл обов’язків:

Alloy приборкує сирий нативний потік OTEL.
Збагачення хуків робить семантичні події придатними для запитів.

Це тримає архітектуру простішою, ніж спроба протягнути все через один шлях.

Що насправді показує дашборд

Знімок екрана нижче — з одного з дашбордів спостережуваності, що стоїть за нашим агентним робочим процесом. Це не бенчмарк, а числа — лише зріз у певний момент часу. Суть у формі даних: стрічка активності, виклики інструментів, відмови, промпти та розбивки за агентом, вбудованими інструментами, використанням MCP, shell-командами та навичками.

Корисно те, що цей дашборд живе на тому самому стеку Grafana, що й решта телеметрії агентів. Ми можемо фільтрувати за вихідним агентом та родиною інструментів і дивитися крізь середовища виконання, не вигадуючи окрему історію спостережуваності для кожної системи.

Один із живих дашбордів, що стоїть за нашим агентним робочим процесом. Цей знімок екрана — лише один зріз спільного стеку Grafana, який також отримує телеметрію від інших наших агентних середовищ виконання та систем. Натисніть на зображення, щоб переглянути версію в повній роздільній здатності.

Чому трейси важливіші, ніж здається на перший погляд

Логи повідомляють, яка категорія роботи відбулася. Трейси повідомляють, як робота розгорталася в часі.

Ця відмінність важлива в агентних системах, бо слово «повільно» надто неточне, щоб бути корисним.

Трейс може сказати нам, звідки взявся біль:

затримка моделі
час виконання інструмента
повторні спроби
одна особливо дорога взаємодія з MCP
довгий хвіст дрібних операцій, які поодинці виглядали безпечними

На практиці ми використовуємо потік хуків і трейси Tempo разом.

Логи хуків відповідають: що за річ сталася?
Трейси відповідають: куди пішов час?

Саме ця комбінація перетворює спостережуваність з дашборда на пояснення.

Де в цьому місце Codex

Codex — частина того самого стеку, але він не ідентичний Claude Code.

Для Codex ми під’єднуємо дві частини:

Нативний OTEL від Codex в Alloy
Вебхук сповіщень у codex_notify.py, який відображає завершення ходів у ту саму схему Loki, яку ми використовуємо для подій хуків

Це дає нам уніфікований фільтр на кшталт agent_tool="codex-cli" у межах того самого потоку логів.

Чесне застереження: payload сповіщень Codex наразі менш докладний, ніж payload хуків Claude Code, бо це не той самий тип інтерфейсу інтеграції. У нашій сьогоднішній конфігурації завершення ходів Codex можна нормалізувати в спільну схему, але детальне вилучення по кожному інструменту все ще краще виходить у нативному потоці OTEL, ніж у мосту сповіщень.

Це не привід уникати цього допису. Це якраз і є суть допису. Реальні системи спостережуваності збираються з недосконалих сигналів.

Grafana через MCP змінює правила гри

Більший зсув у тому, що Grafana — це не лише місце, куди люди заходять у браузері.

У цьому репозиторії ми також надаємо доступ до Grafana через MCP. Це означає, що агент може напряму запитувати Loki, Prometheus і Tempo, замість того щоб чекати, поки людина спершу вручну огляне дашборди.

Це перетворює спостережуваність на активний вхід у робочий процес.

Агент може запитати:

Які родини інструментів найчастіше відмовляли за останню годину?
Який сервер MCP домінував у сесії?
Чи нещодавні зміни зменшили кількість відмов інструментів, чи просто перемістили роботу в більш насичені shell-операціями шляхи з тими самими помилками?
Які трейси показують найвищу затримку чи повторні спроби?

Як тільки у вас це є, ви дуже близькі до циклу самовдосконалення.

Від дашборда до циклу зворотного зв’язку

Це та частина, яку ми вважаємо найцікавішою.

Щойно стек спостережуваності стає доступним для запитів з рівня агента, телеметрія перестає бути пасивним засобом звітності й стає сигналом керування.

Цикл виглядає так:

Активність агента породжує трейси, метрики та збагачені логи хуків.
Grafana зберігає докази в Loki, Tempo та Prometheus там, де існують метрики.
Агенти запитують ці докази через Grafana MCP.
Система виявляє поганий мікс інструментів, крихкі навички, слабку маршрутизацію чи насичені shell-операціями робочі процеси, що постійно призводять до помилок, яких можна уникнути.
Агенти чи оператори коригують промпти, конфігурації агентів, описи навичок, правила маршрутизації чи доступ до інструментів.
Наступна сесія породжує нову форму телеметрії, і цикл повторюється.

Саме так ви переходите від «цікавого дашборда» до «вимірюваної системи вдосконалення».

Мета не в тому, щоб максимізувати одну категорію інструментів. Мета в тому, щоб знайти правильний мікс CLI, вбудованих інструментів, викликів MCP та навичок для роботи, яка справді виконується.

На що це дозволяє нам відповісти

Щойно обидва середовища виконання потрапляють в один стек Grafana, ми можемо набагато швидше відповідати на операційні запитання:

Чи зосереджені відмови в одній родині інструментів?
Чи насичені shell-операціями робочі процеси створюють помилки, яких можна було б уникнути, там, де мав би існувати інструмент вищого рівня?
Які сервери MCP несуть основне навантаження?
Чи платимо ми за активність агента, яка не дає значущого прогресу?
Що спричиняє проблеми в сесії: модель, інструменти чи шар оркестрації?

Це особливо корисно в багатоагентних робочих процесах, де фраза «агент був зайнятий» майже нічого не повідомляє.

Якщо якийсь спеціаліст постійно отримує завдання і показує високий рівень відмов, це проблема маршрутизації чи формулювання промпту.

Якщо один сервер MCP домінує в усіх викликах, це може бути хорошою архітектурою — або ознакою того, що все інше — зайвий баласт.

Якщо відмови інструментів різко зростають, а вартість залишається високою, у вас операційна проблема, а не проблема якості.

Якщо робота з shell постійно й передбачувано провалюється так, як цього можна було б уникнути, там, де мав би існувати інструмент вищого рівня, це продуктовий сигнал.

Якщо одна навичка активується постійно, але не покращує результати, це сигнал про промпт чи маршрутизацію.

Справжній урок

Глибший урок тут у тому, що спостережуваність агентів потребує і телеметрії середовища виконання, і телеметрії робочого процесу.

Телеметрія середовища виконання повідомляє, що зробила система.

Телеметрія робочого процесу повідомляє, що, на думку агента, він робив.

Нам потрібно і те, і те.

Якщо зберігати лише трейси й лічильники, ви втрачаєте семантичний шар. Якщо зберігати лише події хуків, ви втрачаєте затримку, спани та ширшу картину середовища виконання.

А якщо зберігати і те, і те, але ніколи не повертати це на рівень агента, у вас моніторинг, а не адаптація.

Саме ця комбінація робить систему достатньо пояснюваною, щоб нею керувати, і достатньо налаштовуваною, щоб її вдосконалювати.

Що досі недосконале

Шершавостей ще вистачає.

Не кожна подія хука містить дані про тривалість і токени, які ми хотіли б мати.
Деякі з найінформативніших даних про тривалість досі беруться з трейсів Tempo, а не з логів хуків.
Codex сьогодні семантично бідніший за Claude Code у збагаченому потоці подій.
Знімок екрана дашборда — це відображення реальної роботи системи, а не відшліфований маркетинговий артефакт.

Остання теза навмисна. Ми радше покажемо реальну панель приладів, ніж вдаватимемо, що агентні системи магічно самопояснювальні.

Чому це важливо для Maguyva

Maguyva про те, щоб дати агентам кращий інтелект коду. Але щойно агенти справді виконують корисну роботу, одразу з’являється нова вимога: потрібно бачити, як вони поводяться.

Якість пошуку, якість маршрутизації, вибір інструментів та ефективність контексту — все це стає спостережуваними проблемами.

Саме тому ми вважаємо, що про це варто писати. Майбутній агентний стек — це не лише промпти й інструменти. Це промпти, інструменти та шар інструментування, який повідомляє, чи працює все загалом.

Якщо ви будуєте серйозні агентні робочі процеси, спостережуваність — не опціональна інфраструктура. Вона частина продукту.

Видобування знань з історії змін: як зміни стають інституційною пам'яттю

Tue, 03 Feb 2026 00:00:00 GMT

Числа в цьому дописі відображають стан системи на момент публікації (лютий 2026). Актуальні цифри дивіться на нашій сторінці команди.

Кожна інженерна команда стикається з однією й тією самою проблемою: зміни відбуваються постійно, але причини цих змін губляться. Через шість місяців хтось запитує «чому ми обрали DuckDB для етапів pipeline?», а відповідь живе лише в голові того, хто ухвалював це рішення — якщо ця людина ще з командою.

Ми побудували робочий процес видобутку (mining), що замикає цей цикл. Зміни проходять через git-коміти, обробляються нашим конвеєром видобутку, перетворюються на структуровані записи журналу змін та архітектурні рішення, а потім повертаються до наших ШІ-агентів через запити CLI. Результат: інституційна пам’ять, доступна і людям, і ШІ.

Проблема: рішення випаровуються

Розгляньмо типовий сценарій. Розробник комітить:

feat(canonical): add DuckDB runtime for pipeline stages

Цей коміт відображає значущий архітектурний вибір. Команда оцінила варіанти, зважила компроміси і зупинилася на DuckDB з конкретних причин. Але весь цей контекст живе в:

Треді в Slack (імовірно, видаленому)
Чиїйсь пам’яті (точно згасаючій)
Коментарі в коді (можливо, якщо пощастить)

Через три місяці новий член команди запитує: «Мені використати DuckDB чи SQLite для цього нового етапу?» Без інституційної пам’яті вони або винаходять велосипед, або роблять непослідовний вибір.

Цикл: від комітів до контексту

Наш робочий процес видобутку перетворює історію git на знання, придатне для запитів:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

Ключове розуміння: і журнали змін, і архітектурні рішення випливають з тієї самої історії git, обробленої через уніфікований конвеєр. Це гарантує, що нічого не залишається поза увагою.

Як працює видобуток

Крок 1: Синхронізувати індекс

uv run orkestra mine sync

Ця команда сканує історію git і будує індекс усіх комітів. Вона вилучає структуровані сигнали з кожного коміту:

Тип коміту за стандартом Conventional Commits (feat, fix, chore, docs)
Область дії (який пакет чи ділянка)
Маркери зламних змін (breaking change)
Змінені файли та метрики складності

Крок 2: Перевірити статус покриття

uv run orkestra mine status

Ось як виглядає наш поточний статус:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15 637 комітів оброблено. 476 стали архітектурними рішеннями. 6 799 стали записами журналу змін. Кожен коміт класифіковано.

Крок 3: Отримати кандидатів для перегляду

uv run orkestra mine candidates --limit 50 --full

Це виводить коміти, які ще не оброблено, з повним контекстом для класифікації:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Сигнали допомагають спрямувати класифікацію: is_releasable_type: true підказує, що це має з’явитися в журналі змін. Велика кількість вставок та інфраструктурні файли підказують, що це може бути й архітектурним рішенням.

Крок 4: Класифікувати коміти

Тут шляхи розходяться: записи журналу змін і архітектурні рішення.

Для записів журналу змін:

uv run orkestra mine classify abc123 --changelog added

Це фіксує, що коміт abc123 має з’явитися в журналі змін під категорією «Added» (Додано).

Для архітектурних рішень:

Спочатку отримайте реальний ID рішення:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Потім класифікуйте з ID рішення:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Це пов’язує коміт із записом рішення, який буде створено чи оновлено.

Для пакетної обробки (що ми насправді робимо):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Формат JSONL підтримує обидва домени за один прохід:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Крок 5: Відрендерити вивід

uv run orkestra registry changelog render --package <pkg>

Це генерує файли CHANGELOG.md для кожного пакета з журналу (ledger). Журнали змін — похідні артефакти: видаліть їх, і вони бездоганно регенеруються з вихідного журналу.

Структура запису рішення

Вилучені рішення стають YAML-файлами з насиченими метаданими:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Кожне рішення посилається назад на свої вихідні коміти. Кожне рішення вказує, які файли воно зачіпає. Зв’язки між рішеннями явні.

Інтеграція з CLI: запити до інституційної пам’яті

Тут цикл замикається. Агенти можуть запитувати рішення через CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Повертає рішення про логіку повторних спроб, обробку помилок, патерни відновлення.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Повертає повний запис рішення з контекстом, обґрунтуванням та впливом.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Показує, які архітектурні рішення були ухвалені нещодавно.

Як агенти це використовують

Базові інструкції нашого оркестратора включають:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Коли агента просять реалізувати щось пов’язане з DuckDB, він може спершу перевірити:

uv run orkestra registry decisions search --query "DuckDB"

І виявити DEC-PL-142, дізнавшись:

Чому ми обрали DuckDB (context)
Як правильно це використовувати (agent_guidance)
На які файли дивитися (files)
Які пов’язані рішення існують (related)

Агент не винаходить велосипед. Він спирається на усталені патерни.

Тест трьох запитань

Не кожен коміт заслуговує на запис рішення. Ми використовуємо тест трьох запитань для фільтрації:

Чи важко було це ухвалити? Чи вимагало це значного аналізу, оцінки компромісів чи дебатів?
Чи дорого це змінити? Чи вимагатиме скасування цього рішення значного переробляння?
Чи має це вплив на всю систему? Чи впливає це на кілька пакетів, чи встановлює патерни, яким слідуватимуть інші?

Якщо коміт відповідає «так» хоча б на одне з цих запитань, він кандидат на вилучення рішення. Наш типовий показник: 1–4 рішення на 100 комітів (близько 1–4%).

Для записів журналу змін планка нижча: будь-яка зміна, помітна користувачу (функції, виправлення, покращення), фіксується. Внутрішні дрібні завдання, оновлення документації та рефакторинги зазвичай пропускаються. Наш типовий показник: 30–50 записів журналу змін на 100 комітів.

Зберігання даних: журнали лише для додавання

Система видобутку використовує JSONL-журнали лише для додавання (append-only) для безконфліктної багатоагентної роботи:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Формат JSONL з merge=union у .gitattributes означає, що кілька агентів можуть класифікувати коміти одночасно без конфліктів злиття. Кожен рядок незалежний.

Контрольні перевірки

Перед будь-якою сесією видобутку ми запускаємо валідацію:

uv run orkestra mine validate --quick

Це перевіряє:

Валідність формату SHA
Відповідність формату ID рішення
Відсутність дублікатів записів для того самого SHA
Реальне існування рішень, на які є посилання

Після класифікації ми валідуємо знову перед комітом змін.

Чому це важливо

Цикл зворотного зв’язку, який ми побудували, вирішує кілька проблем:

Для нових членів команди: замість того щоб питати «чому ми зробили X?», вони можуть шукати в реєстрі рішень. Контекст збережено.

Для ШІ-агентів: вони не працюють у вакуумі. Вони можуть запитувати інституційні знання перед тим, як давати рекомендації. Коли їх просять додати новий етап pipeline, вони можуть виявити патерн DuckDB і слідувати йому.

Для архітектурної узгодженості: рішення явні й доступні для пошуку. Коли хтось пропонує підхід, що суперечить наявному рішенню, система може виявити конфлікт.

Для генерації журналу змін: нотатки про реліз — не поспіх в останню хвилину. Вони побічний продукт безперервної класифікації під час розробки.

Для онбордингу: нові агенти успадковують повний контекст кодової бази. Вони бачать не лише код — вони бачать рішення, які його сформували.

Поточний стан

На сьогодні:

15 637 комітів оброблено через конвеєр
476 архітектурних рішень вилучено й задокументовано
6 799 записів журналу змін зафіксовано
100% покриття в обох доменах

Кожен коміт з моменту, як ми почали, класифіковано. Інституційна пам’ять повна й доступна для запитів.

Початок роботи

Якщо ви хочете реалізувати щось подібне:

Почніть із комітів за стандартом Conventional Commits. Конвеєр видобутку працює найкраще, коли коміти мають структуровані префікси (feat:, fix:, chore:).
Визначте свої домени. Ми використовуємо домени на кшталт pipeline, agent-design, observability, data-modeling. Вони організовують рішення за ділянками.
Виробіть звичку класифікації. Видобуток працює, коли команди регулярно класифікують коміти. Пакетна обробка за допомогою LLM допомагає масштабуватися.
Зробіть рішення доступними для запитів. Цінність накопичується, коли агенти можуть шукати рішення через CLI. Структуруйте свій вивід для машинного споживання.
Замкніть цикл. Рішення мають впливати на майбутню роботу. Включайте посилання на рішення в інструкції для агентів та чеклісти перегляду коду.

Мета не в ідеальній документації. Мета в тому, щоб зробити причини змін доступними і людям, і ШІ, сьогодні і через шість місяців. Коли зміни стають інституційною пам’яттю, команди спираються на усталені патерни, а не винаходять їх заново.

Робочий процес видобутку — частина нашого рушія оркестрації, зокрема модуля контекстного рушія в нашому пакеті оркестрації.

Видобуток навичок: від 3500 кандидатів до 466 можливостей

Tue, 27 Jan 2026 00:00:00 GMT

Числа в цьому дописі відображають стан системи на момент публікації (січень 2026). Актуальні цифри дивіться на нашій сторінці команди.

Проблема 3500 навичок

Коли ми почали будувати систему оркестрації агентів, ми зіткнулися з цікавим викликом: у ШІ-екосистемі розкидані тисячі потенційних навичок. Репозиторії GitHub, документація вендорів, проєкти спільноти, внутрішні патерни — навички існують всюди. Але які з них важливі? Які працюють? І як підтримувати узгоджену бібліотеку навичок, яку агенти справді можуть використовувати?

Наша відповідь: систематичний цикл видобутку та засвоєння.

Цифри на сьогодні

Лише через трохи більше трьох місяців після того, як Anthropic випустила Agent Skills 16 жовтня 2025 року, ось де ми були на момент публікації цього допису 27 січня 2026 року:

Метрика	Кількість
Виявлено кандидатів	3500+
Відібрано навичок	466
Навички вендорів	373
Внутрішні навички	93
Активних вендорів	25+
Середня кількість токенів на навичку	2834
Задіяних інструментів	89
Унікальних тегів	635

Ми переглянули понад 3500 кандидатів на навички. Ми впровадили 466. Це 13% рівень відбору — і ця вибірковість навмисна.

Рівнева система знань

Не всі навички рівноцінні. Ми організовуємо їх у п’ять шарів знань (K0–K4), кожен з яких представляє іншу сферу застосовності:

K0: Основи (Універсальні)

Навички, які повинен мати кожен агент. Вони представляють можливості «доброго мислителя», що працюють будь-де.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Навички K0 переносяться в будь-який проєкт, будь-який домен, будь-який стек. Вони кодують універсальні когнітивні патерни.

K1: Ідентичності (Професійна сфера)

Навички «доброго інженера» чи «доброго дослідника», що застосовуються в проєктах у межах професійної сфери.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Домени (Предметна експертиза)

Навички «доброго експерта з баз даних» чи «доброго інженера з безпеки», придатні для повторного використання в межах галузі.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Стеки (Технологія)

Навички «доброго користувача Supabase» чи «доброго розробника Cloudflare» для конкретних технологічних стеків.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Проєкт (Організація)

Навички, специфічні для нашої організації та робочих процесів.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

Цикл видобутку

Фаза 1: Виявлення

Навички приходять звідусіль:

Репозиторії вендорів: AWS, Anthropic, Cloudflare, Supabase та контриб’ютори спільноти публікують колекції навичок. Ми відстежуємо 25+ вендорських коренів.

Проєкти спільноти: GitHub повний шаблонів Claude Code, патернів агентів та визначень робочих процесів.

Внутрішні патерни: коли наша команда вирішує проблеми, виникають патерни. Вони формалізуються в навички.

Видобуток з документації: технічна документація часто містить неявні навички — процедури, чеклісти, дерева рішень.

Виявлення безперервне. Ми використовуємо беклог навичок для відстеження кандидатів до формальної оцінки.

Фаза 2: Оцінка

Кожен кандидат проходить одну й ту саму рубрику:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Усі п’ять продуктових критеріїв мають бути виконані. Саме тому 87% кандидатів відхиляються.

Потім кожен кандидат проходить окремий перегляд довіри. Ми не трактуємо офіційний репозиторій вендора, відомого мейнтейнера спільноти та випадковий репозиторій GitHub як рівноцінні джерела істини.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Довірені вендори отримують спрощену перевірку походження, але не безумовний пропуск. Недовірені чи невідомі джерела отримують глибший ручний аудит, і ми не виконуємо пакетовані скрипти, доки їх не прочитали, не окреслили сферу дії та не класифікували як безпечні.

Аналіз прогалин: перед впровадженням ми шукаємо в нашому реєстрі:

uv run orkestra skills search "<capability>"

Якщо у нас це вже є, воно нам не потрібне. Якщо у нас є щось близьке, ми можемо об’єднати, а не додавати окремо.

Оцінка глибини та стандартів: ми також оцінюємо, наскільки повно кандидат використовує модель agent-skill. Самотній SKILL.md все ще може бути корисним, але глибші навички цінніші, коли вони відокремлюють інструкції від довідників, скриптів та активів, як заохочує agentskills.io.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Зірки GitHub можуть трохи підняти оцінку довіри, але вони ніколи не рятують поверхову чи небезпечну навичку. Репозиторій з великою кількістю зірок з одним розпливчастим SKILL.md та непрозорими скриптами отримує оцінку нижчу за менший репозиторій з точним описом, впорядкованими довідковими матеріалами в references/ та атомарними хелперами, що справді використовують повну можливість моделі навичок.

Структурний аналіз: ми перевіряємо якість навички:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Якщо кандидат включає скрипти, цей перегляд стає суворішим. Добра навичка не просто корисна; вона має бути читабельною, обмеженою та безпечною, щоб довірити її агенту. Сам цей фільтр безпеки дискваліфікує значну частку інакше цікавих кандидатів.

Фаза 3: Засвоєння

Коли навичка проходить оцінку, вона потрапляє в реєстр. Але навички ніколи не впроваджуються без змін. Вони модифікуються, щоб підходити нашій системі.

Модифікації при впровадженні:

Нормалізація метаданих: кожна навичка отримує нашу схему frontmatter
Присвоєння K-рівня: навички розміщуються у відповідному шарі знань
Збагачення тегами: додаються теги для виявлення
Декларація інструментів: явно декларуються дозволені інструменти
Вирівнювання секцій: вміст перебудовується відповідно до нашого шаблону

Типовий YAML навички після засвоєння:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Фаза 4: Присвоєння сфери

Навички присвоюються сферам — категоріям, що визначають, який агент завантажує яку навичку:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Агенти декларують свої сфери, і навички присвоюються автоматично:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Фаза 5: Матеріалізація

Навички не живуть як YAML у продакшні. Вони рендеряться в файли SKILL.md, які може завантажити Claude Code:

uv run orkestra sync

Ця команда:

Читає всі YAML-визначення навичок
Рендерить їх через шаблони Jinja
Записує файли SKILL.md у .claude/skills/
Організовує за K-рівнем (foundations/, identities/, domains/, stacks/, project/)

Фінальна структура виводу:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Патерн сплячої сфери

Один з наших найпотужніших патернів — навички «впроваджені, але не завантажені». Ми називаємо їх сплячими сферами.

Розгляньмо навички наукових обчислень з репозиторію k-dense-scientific. Ми впровадили 120+ навичок, що покривають біоінформатику, хімію, квантові обчислення та клінічну інформатику. Але більшості наших агентів не потрібен молекулярний докінг чи аналіз експресії генів.

Замість завантаження всіх 120 навичок у кожного агента (роздуваючи вікна контексту), ми:

Впроваджуємо навички з конкретною сферою (наприклад, bioinformatics)
Тримаємо їх сплячими — зареєстрованими, але не завантаженими
Активуємо їх лише коли агент декларує цю сферу

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Цей патерн дозволяє нам мати 466 навичок у реєстрі, тоді як типові агенти завантажують лише 40–60 релевантних.

Типи навичок

Навички бувають трьох когнітивних патернів:

Workflow (робочий процес)

Упорядковані процедурні кроки: «1. Зроби X, 2. Потім Y, 3. Нарешті Z»

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Discipline (дисципліна)

Поведінкові запобіжники: «Завжди X», «Ніколи Y», «Надавай перевагу Z»

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist (чекліст)

Критерії перевірки: «Підтверди X», «Перевір Y», «Звір Z»

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Перевірки якості

Кожна навичка має пройти валідацію, перш ніж постачатися:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Описи мають бути 50–400 символів з тригерними фразами («Use when…», «When you need…»), щоб Claude Code знав, коли їх пропонувати.

Ми валідуємо безперервно:

uv run orkestra validate --show-warnings

Екосистема вендорів

Наші 373 навички вендорів походять від:

Провайдер	Навички	Домен
AWS Agent	19	Хмарні сервіси
Anthropic	12	Генерація документів
Cloudflare	8	Edge-обчислення
Supabase	5	Бази даних
k-dense	100+	Наукові обчислення
silvainfm	4	Наука про дані
Java Developer Kit	45+	Spring/Java
Vercel	1	Автоматизація браузера

Кожен вендорський корінь декларується в metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Коли запускається orkestra sync, для навичок вендорів створюються символічні посилання (symlink) у .claude/skills/vendor/ у просторі імен відповідного провайдера.

Що ми зрозуміли

Вибірковість окупається. Спокусливо впроваджувати все, що виглядає корисним. Але кожна навичка коштує токенів. З 2834 середніми токенами на навичку роздування шкодить швидко. Наш 13% рівень відбору тримає агентів компактними.

Структура вмикає виявлення. Система K-рівнів — це не просто організація, а про перенесуваність. Навички K0 можна повторно використовувати будь-де. Навички K4 навмисно специфічні для проєкту. Ця чіткість допомагає і людям, і агентам знаходити потрібне.

Сплячі сфери масштабуються. Можна впровадити сотні навичок, не завантажуючи їх усі. Сфери дозволяють будувати всеосяжний реєстр, водночас тримаючи вікна контексту окремих агентів керованими.

Модифікація при впровадженні необхідна. Сирі навички вендорів рідко підходять вашій системі напряму. Процес засвоєння — додавання метаданих, присвоєння рівнів, збагачення тегами — робить зовнішні навички робочими всередині.

Видобуток безперервний. Число 3500 продовжує зростати. З’являються нові репозиторії вендорів. Виникають патерни спільноти. Закріплюються внутрішні робочі процеси. Цикл ніколи не зупиняється.

Що далі

Ми працюємо над кількома покращеннями:

Автоматизоване виявлення прогалин: сповіщення, коли поширені відмови агентів могли б бути вирішені ще не впровадженою навичкою
Процеси виведення навичок з обігу: формальний процес виведення з обігу навичок, які замінені чи не використовуються
Міжнавичкові залежності: явна декларація передумов навички
Аналітика використання: відстеження, які навички агенти справді викликають, а не просто завантажують

Цикл видобутку навичок — це інфраструктура. Нічого гламурного. Але саме це робить так, що 41 агент узгоджено працює з 466 можливостями, залишаючись у межах контексту.

Ось історія того, як 3500 стають 466. Не через ігнорування 3000 — через систематичну оцінку й відбір лише того, що працює.

Хочете побачити систему навичок у дії? Перегляньте uv run orkestra skills list, щоб дослідити наш поточний реєстр.

Прогресивне розкриття: вікна CLI в агентні системи

Tue, 20 Jan 2026 00:00:00 GMT

Числа в цьому дописі відображають стан системи на момент публікації (січень 2026). Актуальні цифри дивіться на нашій сторінці команди.

Агентні системи непрозорі за задумом. Вони ухвалюють рішення, викликають інструменти й координують роботу десятків спеціалістів. Але коли щось йде не так — або коли ви просто хочете зрозуміти, що відбувається — куди дивитися?

Відповідь — прогресивне розкриття: багаторівневий інтерфейс, що показує рівно стільки складності, скільки вам потрібно, саме тоді, коли це потрібно.

Проблема непрозорості

Сучасна система оркестрації агентів може мати:

40+ спеціалізованих агентів, кожен з унікальними можливостями
700+ навичок, що охоплюють внутрішню автоматизацію та інтеграції з вендорами
470+ архітектурних рішень, що формують поведінку
Десятки серверів інструментів MCP, що надають зовнішні можливості

Ця складність навмисна. Агентам потрібен доступ до багатого контексту — доменних знань, інтелекту коду, схем баз даних — щоб ухвалювати добрі рішення. Але та сама насиченість створює проблему видимості.

Як дізнатися, який агент обробляє міграції баз даних? Які рішення сформували поведінку ранжування системи пошуку? До яких інструментів має доступ радник з архітектури?

Без структурованого доступу вам залишається читати вихідний код або сподіватися, що документація актуальна.

Прогресивне розкриття як архітектура

Прогресивне розкриття — не просто патерн UI. Це архітектурний принцип: організовувати інформацію шарами, кожен глибший за попередній, щоб користувачі могли зупинитися на рівні, що відповідає на їхнє запитання.

Для агентних систем це означає команди CLI з дедалі вищою деталізацією:

Рівень	Команда	Запитання, на яке відповідає
1	`orkestra system status`	Чи все працює справно?
2	`orkestra agents list`	Які агенти існують?
3	`orkestra agents info <name>`	Що робить цей агент?
4	`orkestra decisions search`	Чому це працює саме так?
5	Інструменти Maguyva MCP	Покажи мені код.

Кожен рівень відповідає на природне наступне запитання. Вам рідко потрібно стрибати одразу до рівня 5.

Рівень 1: працездатність системи

Перше запитання завжди: чи все працює?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Одна команда. Чотири числа. Достатньо, щоб знати, що система налаштована, а реєстри заповнені.

Якщо кількість агентів несподівано падає, чи навички не завантажуються, ви бачите це тут першим. Занурення в логи не потрібне.

Рівень 2: інвентаризація агентів

Щойно ви знаєте, що система працює справно, наступне запитання: що доступно?

$ orkestra agents list

Це повертає структуровані дані — назви агентів, описи, бажані моделі, покриття доменів. Вивід за замовчуванням у JSON, тож легко направити його через конвеєр у jq для фільтрації:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Потрібні агенти, що обробляють роботу з базами даних? Команда пошуку звужує вибір:

$ orkestra agents search "database"

Вона сканує назви, описи та можливості. Ви знаходите правильного спеціаліста, не читаючи 40 визначень агентів.

Рівень 3: глибоке занурення в агента

Знайшли агента, що виглядає доречним? Команда info розкриває все:

$ orkestra agents info architecture-advisor

Вивід включає:

Метадані: назва, категорія, бажана модель, опис
Домени: які ділянки знань покриває цей агент
Identity: риси характеру (architect, strategist, knowledge-architect)
Довідники інструментів: яка документація інструментів впроваджується в контекст
Інструменти: повний список інструментів MCP, доступних цьому агенту

Ось приклад того, що ви бачите:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Це повідомляє точно, що агент може робити. Вихідний код не потрібен.

Рівень 4: археологія рішень

Агенти поводяться відповідно до задокументованих рішень. Коли вам потрібно зрозуміти, чому щось працює саме так, реєстр рішень — джерело істини.

$ orkestra decisions search "agent"

Це повертає відповідні архітектурні рішення:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Кожне рішення має повну історію походження — коли його ухвалили, чому, які компроміси розглядалися, які коміти його реалізували:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Це архітектурна документація, що залишається актуальною, бо вона видобувається з комітів, а не підтримується вручну.

Рівень 5: прямий інтелект коду

Коли вам потрібно побачити реальну реалізацію — не метадані про неї — інструменти MCP від Maguyva надають прямий доступ.

Із сесії агента:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Це автоматично маршрутизує через семантичний, текстовий та AST пошук, щоб знайти релевантний код. Для конкретних символів:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Для аналізу залежностей:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Ці інструменти не просто замінюють grep. Вони враховують граф, використовують семантичний індекс та інтегровані з тим самим інтелектом коду, що живить самих агентів.

Уніфікований пошук по реєстрах

Іноді ви не знаєте, який реєстр містить відповідь. Уніфікований пошук охоплює все:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 збіги в п’яти реєстрах. Резюме повідомляє, куди заглибитися. Приберіть --summary для детальних результатів або додайте --limit 5, щоб зберегти вивід керованим.

Чому це важливо

Прогресивне розкриття — не просто про зручність. Воно змінює те, як ви взаємодієте зі складними системами.

Налагодження стає посильним. Коли агент ухвалює несподіване рішення, ви не грепаєте логи. Ви перевіряєте, до яких інструментів у нього є доступ (agents info), які рішення формують його поведінку (decisions search), і за потреби простежуєте реалізацію (intelligent_search).

Онбординг прискорюється. Новим членам команди не потрібно читати всю кодову базу. Вони починають з system status, досліджують за допомогою agents list і заглиблюються лише коли натрапляють на щось незрозуміле.

Документація залишається актуальною. Оскільки CLI читає з тих самих реєстрів, що конфігурують агентів, вивід завжди точний. Немає розходження між тим, що каже документація, і тим, що робить система.

CLI як інтерфейс

Ми могли б побудувати веб-дашборд. Могли б написати розлогу документацію. Натомість ми побудували CLI, що читає з джерела істини.

CLI має переваги:

Композиційність: направляйте вивід через конвеєр у jq, інтегруйте зі скриптами
Придатність до скриптування: автоматизуйте перевірки, генеруйте звіти
Швидкість: жодних завантажень сторінок, жодних потоків автентифікації
Точність: читає реальну конфігурацію, а не кешоване представлення

Для систем, де коректність важливіша за естетику, перемагає CLI.

Побудова власного прогресивного розкриття

Якщо ви будуєте агентні системи, подумайте, як користувачі їх досліджуватимуть:

Почніть з перевірок працездатності. Одна команда, що повідомляє, чи все працює.
Надайте перегляди інвентаризації. Перерахуйте, що існує, перш ніж пояснювати, що воно робить.
Уможливте цільові запити. Пошук перемагає перегляд у масштабі.
Покажіть походження рішень. Дозвольте користувачам простежувати рішення до їхнього походження.
З’єднайте з інтелектом коду. Врешті-решт користувачам потрібно побачити реалізацію.

Кожен шар відповідає на наступне запитання. Будуйте їх у порядку частоти — більшість користувачів зупиняються на шарі 2 чи 3. Лише досвідчені користувачі досягають шару 5.

Мета не в тому, щоб розкрити все. Мета в тому, щоб розкрити рівно те, що потрібно, саме тоді, коли це потрібно. Це і є прогресивне розкриття, застосоване до архітектури агентів.

Базові істини: прив'язування ШІ-агентів до реальності

Tue, 13 Jan 2026 00:00:00 GMT

Числа в цьому дописі відображають стан системи на момент публікації (січень 2026). Актуальні цифри дивіться на нашій сторінці команди.

ШІ-агенти надзвичайно здібні. Вони вміють міркувати, синтезувати та генерувати. Але в них є фундаментальна слабкість: вони вигадують. Не зловмисно, а впевнено. Агент може вигадати параметри API, яких не існує, послатися на конфігурації, які ніколи не визначалися, або застосувати патерни з даних навчання, що суперечать вашій реальній архітектурі.

Стандартний спосіб зменшити ризик — «дати агенту більше контексту». Але контекст може суперечити сам собі. Документація розходиться з реалізацією. Коментарі брешуть. Навіть код може ввести в оману, якщо його читати без розуміння наміру.

Нам потрібно було щось конкретніше. Щось, що не можна проігнорувати чи неправильно витлумачити. Щось, що прив’язувало б агентів до перевірюваної реальності.

Ми називаємо їх базовими істинами (Ground Truths).

Що таке базова істина?

Базова істина (ground truth) — це явне, версійоване твердження про факт, яке агенти зобов’язані враховувати. Це не документація. Це не коментар. Це повноцінна сутність у системі з:

Унікальним ідентифікатором (на кшталт GT-MAG-015 чи GT-MAG-036)
Статусом життєвого циклу (поточний, попередній чи застарілий)
Сферою дії (уся платформа, конкретний пакет чи домен)
Доказами (шляхи до файлів, URL чи посилання, що доводять твердження)
Настановами для агента (явні інструкції «робити/уникати»)

Ось приклад з нашої платформи інтелекту коду Maguyva:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Це не проза. Це контракт. Коли агент натрапляє на цю базову істину, він знає:

Поведінка за замовчуванням детермінована (порожні результати, а не нечіткі здогадки)
Є конкретні параметри (find_similar, exact_match) з визначеною поведінкою
Докази існують у конкретних файлах, які можна перевірити
Твердження було перевірене конкретної дати

Анатомія реєстру базових істин

Базові істини живуть у YAML-реєстрах під ai_assets/reference/ground_truths.yaml. Кожен пакет чи домен може мати власний реєстр. Структура така:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Реєстр містить метадані про саму колекцію, конфігурацію рендерингу для генерації документації та самі твердження. Кожне твердження підпорядковується суворій схемі, валідованій моделями Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Як агенти отримують доступ до базових істин

Базові істини надаються через кілька каналів:

1. Відрендерена документація

Команда orkestra sync перетворює YAML-реєстри на читабельний markdown:

uv run orkestra sync

Це генерує файли GROUND_TRUTHS.md, які включаються в контекст агента. Відрендерений вивід групує твердження за статусом і категорією:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Пошук через CLI

Агенти з доступом до shell можуть шукати базові істини програмно:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

Функція пошуку оцінює збіги за кількома полями зі зваженою релевантністю:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Композиція контексту

Коли агенти рендеряться з YAML-визначень, їхній контекст може посилатися на реєстри базових істин:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Це гарантує, що відповідні базові істини завантажуються до того, як агент почне роботу.

Категорії базових істин

Поглянувши на наші реєстри, можна побачити, що базові істини групуються в кілька патернів:

Принципи продукту

Обмеження щодо того, чим продукт є, а чим не є:

«Maguyva працює з репозиторіями користувачів лише в режимі читання; єдиний актив, який неможливо відновити — це платний кеш ембеддингів». (GT-MAG-001)

Архітектурні межі

Де живуть обов’язки і чому:

«Межі між pipeline та Maguyva навмисні: pipeline перевикористовуваний, Maguyva утримує специфічну для коду логіку, а CQRS відокремлює операції запису на етапах конвеєра від операцій читання на сервері». (GT-MAG-006)

Правила проти галюцинацій

Явні вимоги, які забезпечують детерміновані контракти інструментів, а не контракти на основі здогадок:

«Нечітке зіставлення символів опційне через find_similar=true. Поведінка за замовчуванням повертає порожні результати для символів, яких не існує; exact_match=true забезпечує суворе зіставлення і вимикає всі нечіткі резервні варіанти». (GT-MAG-015)

Перевірки якості

Стандарти, які потрібно підтримувати:

«Зміни до спільної інфраструктури (post_filters.py, екстрактори зв’язків, спільні обробники) МАЮТЬ бути перевірені для УСІХ підтримуваних мов через генерацію повного маніфесту перед комітом. Валідація однієї мови недостатня для спільного коду». (GT-MAG-036)

Патерни коду

Вимоги до реалізації:

«Використовуйте asyncio.to_thread() для CPU-навантаженої роботи в асинхронних контекстах; застарілий патерн loop.run_in_executor() не слід використовувати в новому коді». (GT-MAG-018)

Життєвий цикл базової істини

Базові істини не статичні. Вони еволюціонують через визначений життєвий цикл:

Попередня (Tentative)

Запропонована істина на етапі оцінки. Твердження зафіксоване, але може змінитися:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Поточна (Current)

Перевірена істина, яку агенти зобов’язані поважати. Докази валідовано:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Застаріла (Deprecated)

Істина, що більше не застосовується. Зберігається для історичної довідки з посиланням на те, що її замінило:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Чому не просто документація?

Документація слугує іншій меті. Вона пояснює. Вона навчає. Вона може бути розпливчастою, може використовувати уточнення на кшталт «зазвичай» чи «як правило».

Базові істини не можуть бути розпливчастими. Це твердження. Вони або застосовуються, або ні.

Розгляньмо різницю:

Документація: «API зазвичай повертає порожні результати, коли символ не знайдено, хоча нечітке зіставлення може бути увімкнене в деяких конфігураціях».

Базова істина: «Поведінка за замовчуванням повертає порожні результати для символів, яких не існує; exact_match=true забезпечує суворе зіставлення і вимикає всі нечіткі резервні варіанти».

Перше корисне для людей, які вивчають систему. Друге придатне до дії для агентів, які ухвалюють рішення.

Настанови для агента: робити й уникати

Деякі базові істини містять явні настанови для агента:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Це усуває неоднозначність. Агент, що це читає, знає не лише те, що є правдою, а й те, які дії ця правда передбачає.

Перевірка та підтримка

Базові істини потребують підтримки. Ми відстежуємо:

last_verified: коли хтось підтвердив, що твердження досі справджується
evidence: файли, що доводять твердження (можна перевірити на існування)
source: звідки походить істина (перевірка через CLI, архітектурний огляд, висновки після інциденту)

Базова істина із застарілими датами перевірки чи неробочими посиланнями на докази — сигнал для розслідування. Або істина все ще дійсна й потребує повторної перевірки, або реальність змінилася й істину потрібно оновити.

Реальні приклади з продакшну

Межа безпеки

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Ця базова істина запобігає класу помилкових «покращень безпеки», які зламали б продукт.

Точність на момент вилучення

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Це прийшло з болючого досвіду. Агенти виправляли мовні пакети, що падали, додаючи фільтри лише на рівні валідатора, які робили тестовий харнес зеленішим на вигляд, тоді як живий екстрактор Maguyva все ще видавав неправильні ребра. Правило змушує повертати виправлення в реальний шлях: конфігурацію YAML, запити чи обробники.

Багаторівневе фільтрування

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Це не дозволяє агентам додавати фільтри в неправильному місці — поширена помилка, що спричиняла регресії точності.

Інтеграція з системою оркестрації

Базові істини — це один шар ширшої системи контексту:

Архітектурні рішення (ADR) — фіксують, чому ми обрали підхід A, а не B
Базові істини — стверджують, що є безумовно правдивим прямо зараз
Доменні патерни — описують, як робити щось правильно
Антипатерни — описують, чого уникати і чому

Агент, що працює в системі, має доступ до всіх чотирьох. Базові істини дають фактичний якір, тоді як рішення пояснюють історію, патерни спрямовують реалізацію, а антипатерни попереджають про пастки.

Вимірювання впливу

Відколи ми впровадили базові істини, ми спостерігаємо:

Менше циклів «виправити галюциновану правку»
Впевненіше ухвалення рішень агентами, коли факти чіткі
Кращі перегляди PR, бо очікування явні
Скорочений час онбордингу для нових агентів (і людей)

Інвестиція в підтримку базових істин окупається зменшеним обсягом налагодження та чіткішими межами системи.

Початок роботи

Щоб додати базову істину до вашої системи:

Створіть ground_truths.yaml у теці ai_assets/reference/ вашого пакета
Визначте метадані та конфігурацію рендерингу
Додайте твердження за схемою
Запустіть uv run orkestra sync, щоб згенерувати документацію
Включіть реєстр у композицію контексту агента

Почніть з фактів, що спричиняють найбільше плутанини, або обмежень, які порушують найчастіше. Це ваші найцінніші базові істини.

Висновок

ШІ-агенти галюцинуватимуть. Така їхня природа. Але ми можемо створювати середовища, де галюцинації обмежені, де певні факти не підлягають обговоренню, де агенти можуть звіряти свої припущення з перевіреною реальністю.

Базові істини — не повне рішення. Вони потребують підтримки. Вони можуть застарівати. Вони додають накладні витрати до процесу розробки.

Але вони дають щось цінне: спільний словник фактів, якому можуть довіряти і люди, і агенти. У світі, де агенти дедалі більше беруть участь у розробці програмного забезпечення, ця спільна основа стає необхідною.

Альтернатива — нескінченні цикли, коли агенти впевнено помиляються, а люди їх виправляють. Базові істини розривають цей цикл, роблячи виправлення явними й стійкими.

Ваші агенти заслуговують знати, що є правдою. Скажіть їм.

Orkestra: оркестрація ШІ-агентів у масштабі

Tue, 06 Jan 2026 00:00:00 GMT

Числа в цьому дописі відображають стан системи на момент публікації (січень 2026). Актуальні цифри дивіться на нашій сторінці команди.

Коли ми почали будувати на Claude Code, ми зіткнулися з проблемою, з якою рано чи пізно стикається кожна команда, що використовує ШІ-асистентів для програмування: жоден окремий агент не може добре робити все.

Ви можете промптом зробити агента спеціалістом з баз даних. Або аудитором безпеки. Або frontend-інженером. Але в момент, коли ви просите його бути всіма трьома одразу, якість страждає. Контекст розбавляється. Інструкції конфліктують. Агент стає генералістом, посереднім у всьому.

Тож ми побудували Orkestra.

Що таке Orkestra?

Orkestra — це система оркестрації агентів для Claude Code та подібних ШІ-інструментів для програмування. Вона координує кількох спеціалізованих агентів, кожен з власною експертизою, під керівництвом єдиного оркестратора, що спрямовує роботу до правильного спеціаліста.

Уявіть це як кадрове агентство для ШІ-агентів. Оркестратор отримує завдання, визначає, який спеціаліст має його виконати, і делегує з правильним контекстом. Коли робота завершена, результати повертаються до оркестратора для синтезу.

Цифри розповідають цю історію:

Компонент	Кількість
Спеціалізовані агенти	46
Перевикористовувані навички	466
Архетипи ідентичності	27
Мисленнєві настанови (mindsets)	11
Стилі спілкування	10
Домени знань	21

Система характеру: D&D для агентів

Основне розуміння, що стоїть за Orkestra, у тому, що поведінка агента виникає з трьох композиційних примітивів:

Identity (ідентичність) визначає, чим є агент. Архітектор проєктує структури систем. Дебагер простежує відмови до кореневих причин. Вартовий (guardian) забезпечує дотримання норм і меж безпеки. У нас є 27 архетипів ідентичності, які можна змішувати.

Mindset (мисленнєва настанова) визначає, як агент мислить. Аналітична настанова базує твердження на доказах і квантифікує невизначеність. Скептична настанова піддає сумніву припущення й шукає докази, що спростовують ці припущення. Дослідницька настанова приймає неоднозначність і пробує кілька підходів.

Style (стиль) визначає, як агент спілкується. Технічний стиль включає точні значення й посилається на конкретні файли. Стислий стиль відсікає зайве й починає з відповіді. Дипломатичний стиль урівноважує чесність і тактовність.

Агент поєднує ці примітиви:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Ця композиція створює агента, що проєктує системи (architect), пов’язує знання між доменами (knowledge-architect), задає стратегічний напрям (strategist), мислить доказами й даними (analytical) та спілкується без зайвого (concise).

Сила у комбінаторному вибуху. 27 ідентичностей помножені на 11 настанов і на 10 стилів дають майже 3000 можливих особистостей агента. Але ви визначаєте лише ті комбінації, які важливі для вашої роботи.

Навички: перевикористовувані модулі можливостей

Навички — це знання та робочі процеси, які агенти можуть викликати. Вони підпорядковуються рівневій системі, заснованій на сфері дії:

Рівень	Назва	Сфера дії	Приклад
K0	Основи	Універсальна методологія	Дисципліна test-first, завершення на основі доказів
K1	Ідентичності	Робочі процеси на основі ролі	Стандарти інтерфейсу CLI, playbook продуктивності
K2	Домени	Знання конкретного домену	Патерни міграції баз даних, валідація автентифікації
K3	Стеки	Специфічне для технології	Розгортання на Cloudflare, операції Supabase
K4	Проєкт	Лише ця кодова база	Специфічні для проєкту робочі процеси й конвенції

Навички завантажуються ліниво. Агент бачить назви й описи навичок під час запуску, але повний зміст навички завантажується лише при спрацюванні тригера. Це тримає контекст компактним, водночас роблячи сотні навичок доступними для виявлення.

Кожна навичка включає:

Чіткі умови спрацювання («Використовуйте під час міграції схем бази даних»)
Покрокові настанови
Дозволені інструменти для робочого процесу
Критерії успіху та шляхи відновлення після відмови

466 навичок у нашому реєстрі покривають усе — від ізоляції git worktree до робочих процесів веб-досліджень до перевірки працездатності після розгортання.

Чому оркестрація важлива

Архітектури з одним агентом швидко впираються в стіни:

Розбавлення контексту. Вікно контексту в 200 тис. токенів звучить великим, доки ви не завантажите схеми бази даних, документацію API, фікстури тестів та доменні знання. Спеціалісти можуть працювати з цільовим контекстом.

Конфлікти інструкцій. Наказ агенту «бути ретельним, але швидким» та «перевіряти все, але не переускладнювати» створює напругу. Спеціалісти вирішують це, маючи чітку сферу дії.

Глибина експертизи. Генераліст трохи знає про все. Спеціаліст, скомпонований з правильною ідентичністю та навичками, глибоко знає свій домен.

Orkestra реалізує пласку оркестрацію: один оркестратор координує кількох спеціалістів. Спеціалісти не можуть породжувати підспеціалістів. Це запобігає вибуху складності, водночас уможливлюючи паралельну роботу.

Оркестратор має доступ до 2,2 мільйона токенів ефективної ємності: власне вікно 200 тис. плюс 10 паралельних субагентів по 200 тис. кожен. Робота, яка виснажила б одного агента, комфортно виконується флотом.

Конвеєр рендерингу

Визначення агентів живуть у YAML. Claude Code читає Markdown. Orkestra перекриває цю прогалину детермінованим конвеєром рендерингу:

YAML Registries → Jinja Templates → .claude/agents/*.md

Оператори редагують джерело YAML. Запускають orkestra sync. Відрендерений Markdown з’являється в .claude/agents/. Claude Code підхоплює зміни.

Це розділення слугує різним аудиторіям:

Джерело YAML містить метадані життєвого циклу, теги, правила валідації та примітки про застарівання для інструментарію
Відрендерений Markdown містить лише те, що потрібно моделі: опис, інструменти, навички та поведінкові настанови

Конвеєр компонує ідентичності, настанови, стилі та навички в один узгоджений промпт. Агент architect-analytical-concise отримує зовсім інший системний промпт, ніж агент debugger-skeptical-technical, навіть якщо вони поділяють якісь базові навички.

Доменні знання: патерн з чотирьох файлів

Кожен домен знань дотримується узгодженої структури:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Ця структура слугує завантаженню контексту агента. Агент, що працює над автентифікацією, завантажує authentication/patterns.md для настанов і authentication/anti-patterns.md, щоб уникнути відомих пасток. Обсяг файлів підібрано для ефективного завантаження контексту: вони достатньо сфокусовані, щоб бути корисними, і достатньо всеосяжні, щоб бути авторитетними.

Ми підтримуємо 21 домен верхнього рівня, включно з аналітикою, автентифікацією, наукою про дані, інфраструктурою, машинним навчанням, продуктивністю, безпекою та іншими. Кожен домен може мати піддомени для тоншої деталізації.

Цінності: операційна система

Усі агенти поділяють базовий шар цінностей, що визначають, як вони працюють:

Простота понад усе. Використовуйте найпростіше рішення, що працює. Додавайте складність лише коли це виправдано.

Виправляйте кореневі причини. Не обходьте збої тимчасовими латками. Якщо конвеєр падає, налагоджуйте конвеєр. Якщо тест падає, виправляйте код або тест.

На основі доказів. Позначайте твердження як «перевірені» (з бенчмарками) чи «оціночні» (з припущеннями). Виявлений патерн не дорівнює підтвердженій проблемі.

Економіка контексту. Інструменти MCP коштують 0,1% контексту. Читання файлів коштує 2% кожне. Застосовуйте доменну експертизу перед дослідженням коду.

Ці цінності поширюються на кожного спеціаліста через конвеєр рендерингу. Агент не може обійти їх через композицію.

CLI: площина керування

Orkestra постачається з CLI для керування екосистемою агентів:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI — джерело істини щодо того, які агенти існують, які навички вони мають і чи здорова система. Він запускає валідацію перед синхронізацією, щоб виявляти проблеми на ранній стадії.

Міркування щодо open source

Ми побудували Orkestra, щоб вирішити власну проблему: координацію ШІ-агентів у масштабі для складної кодової бази. Патерни, які ми виявили, не специфічні для нашого домену.

Система композиції характеру (identity + mindset + style) застосовна до будь-якої команди, що визначає особистості агентів.

Рівнева система навичок (K0–K4) дає ментальну модель для організації перевикористовуваних можливостей за сферою дії.

Патерн конвеєра рендерингу (джерело YAML + шаблони + згенеровані артефакти) розділяє відповідальності між інструментарієм і споживанням моделлю.

Пласка модель оркестрації (один координатор, багато спеціалістів) уникає складності, водночас уможливлюючи паралелізм.

Чи стане Orkestra опенсорсним, залежить від того, чи мають ці патерни цінність для інших, хто будує на Claude Code. Якщо ви впираєтесь у стіни, які ми описали, ця архітектура може допомогти.

Що ми зрозуміли

Побудова Orkestra навчила нас, що оркестрація — це не про те, щоб зробити агентів розумнішими. Це про те, щоб зробити їх сфокусованішими.

Один агент з ідеальними інструкціями все одно вичерпує контекст. Один агент з усіма навичками все одно плутається, яку застосувати. Один агент, що намагається бути всім, дає посередні результати в усьому.

Сорок спеціалістів, кожен чудовий у своєму домені, координовані оркестратором, що знає, коли делегувати: ось як ми постачаємо продукт.

Цифри важать менше за архітектуру. Вам може знадобитися п’ять агентів чи п’ятдесят. Принцип залишається: композиція понад можливість, спеціалізація понад узагальнення, координація понад індивідуальний героїзм.

Orkestra живить агентну екосистему за Maguyva, нашою платформою інтелекту коду. Хочете дізнатися більше? Зв’яжіться з командою.