Блог 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 и его родня — сопоставляет ключевые слова, работает локально и ничего не стоит. Open-source модели эмбеддингов вроде 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 в роли судьи, а также одно правило, которое мы усваиваем снова и снова: зелёный — не значит верный.

Зелёный — не значит верный

У каждого языка есть набор фикстур, и контроль перед релизом оценивает его по пяти измерениям — точность, структурная целостность, полнота, качество и производительность. Язык становится ЗЕЛЁНЫМ только тогда, когда на его фикстурах precision ≥ 0,95, recall ≥ 0,99 и F1 ≥ 0,97, при не менее чем 20 ожидаемых рёбрах для статистической уверенности. Ниже этого — ЖЁЛТЫЙ или КРАСНЫЙ, и такой язык не отправляется в релиз.

Этот контроль необходим, но недостаточен. Фикстуры проверяются на фикстурах, которые написали мы сами. Они кодируют случаи, о которых мы уже подумали. Обработчик может быть безупречен на своих фикстурах и всё равно ломать паттерн, который встречается только в реальном коде — идиому макроса, метод с ограничениями обобщённых типов, языковую особенность, для которой никто не написал фикстуру. ЗЕЛЁНЫЙ означает, что фикстуры проходят. Это не значит, что реальный репозиторий извлекается чисто. Поэтому циклу приходится оставлять фикстуры позади и проверять реальный код.

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

Основной цикл работает по одному языку за раз:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  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), чтобы агенты не мешали друг другу. Оркестратор интегрирует их исправления по одному, каждый раз с проверкой регрессий по полному манифесту: изменение, которое помогает своему языку, но незаметно ломает три других, не проходит. Интеграция проходит проверку и подтверждается прежде, чем что-либо будет отправлено — проверка регрессий определяет, что безопасно, но что отправляется в релиз, по-прежнему решает человек. Затем пул переключается на следующий набор языков, и всё повторяется снова.

Что всё ещё несовершенно

Судья может ошибаться, и у этой ошибки есть направление: агент, работающий со слишком малым контекстом, завышает число проблем. В одной партии восемь языков были помечены с 5–20% ошибок; при проверке реальный баг подтвердился лишь в одном языке — остальные случаи были ошибками судьи из-за незнания собственной семантики языка (одна строка исходника, легитимно порождающая несколько рёбер, привязки параметров, смоделированные как присваивания, языки с одной ссылкой на идентификатор). Именно поэтому мы делаем выборку с двумя случайными затравками и перекрёстно сверяем результаты, и именно поэтому расхождение между судьёй и фикстурами считается самым интересным сигналом, а не окончательным вердиктом — иногда неправа именно фикстура.

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

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

Всё, что Maguyva делает для агента — находит символ, прослеживает зависимость, отвечает на вопрос со ссылкой на код, — опирается на то, что лежащее в основе извлечение верно. На 280 языках «верно» нельзя просто заявить; это нужно непрерывно заслуживать на реальном коде. Этот цикл — способ, которым мы это заслуживаем: автономный цикл выборочной проверки и исправления, который относится к собственным метрикам с подозрением, доказывает каждое изменение и превращает каждое исправление в защиту от следующей регрессии. Это не эффектно. Это работа, которая позволяет нам сказать «мы поддерживаем ваш язык» и иметь это в виду. Зелёный — легко. Верный — заслужено.

Мультимодальный фьюжн-поиск: выбор правильного ретривера для каждого запроса

Wed, 15 Apr 2026 00:00:00 GMT

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

Поисковые запросы бывают разными.

«где определён parseConfig» хочет точный символ — одно точное место, быстро. «как работает аутентификация» хочет смысл — набор связанного кода, который объясняет концепцию. «что сломается, если я изменю эту функцию» хочет граф зависимостей. «найти строку ECONNREFUSED» хочет буквальное совпадение, ничего умного.

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

Четыре модальности

Под капотом есть четыре независимых способа найти код:

семантический — векторный поиск по бинарным эмбеддингам Voyage; находит код по смыслу.
текстовый — триграммное сопоставление; находит литералы, строки ошибок, точные идентификаторы.
структурный — запросы к AST; находит определения, сигнатуры и языковые конструкции.
графовый — граф зависимостей; находит вызывающих, вызываемых и радиус влияния.

Каждый силён в своём классе вопросов. Хитрость в том, чтобы решить, насколько доверять каждому из них для конкретного запроса перед вами.

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

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

начинается с 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)

Каждое намерение несёт профиль весов по четырём модальностям. Вот реальные цифры:

Намерение	семантический	текстовый	структурный (AST)	графовый
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). «что зависит от этого» — почти целиком граф (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×, чтобы популярная функция не могла полностью похоронить более релевантную, но малоизвестную. Наконец, мы понижаем результаты из путей вендоров, сборки и архивов и убираем дубликаты, оставляя лучший фрагмент на файл.

Что всё ещё несовершенно

Классификатор намерений — это стек регулярных выражений, а не обученная модель. Он обрабатывает распространённые формы запросов с помощью эвристик, а неоднозначный запрос переходит к 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-сервером всё в порядке, но агент выбрал не того специалиста, или потратил половину сессии на неожиданную работу в шелле, или незаметно сжёг бюджет в цикле, который со стороны выглядел продуктивным.

Если вы не видите разницы, вы не по-настоящему управляете агентной системой. Вы гадаете.

Поэтому мы построили стек наблюдаемости для собственного рабочего процесса: Claude Code, Codex, события хуков Claude, события notify 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 плюс интерфейс notify, поэтому мы нормализуем менее подробные события завершения хода в ту же схему логов, вместо того чтобы делать вид, будто оба рантайма предоставляют одинаковые рычаги управления.

Нативный OTEL даёт нам базовый поток: логи и трассы от самого рантайма, плюс метрики там, где рантайм их реально передаёт.

Хуки и notify-события дают нам семантический слой: такие вещи, как PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, и классифицированные метаданные, которые нас реально волнуют при отладке поведения агента. Claude Code вносит сюда более богатый поток событий. Codex вносит менее подробный, но всё же полезный нормализованный поток.

Зачем вообще нужны хуки

Наш конвейер хуков обогащает события, прежде чем они попадают в Loki.

Вместо того чтобы просто сказать «инструмент выполнился», мы классифицируем событие по полям вроде:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: какой MCP-бэкенд обработал вызов
bash_cli: семейство команд шелла
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-операциях с интенсивным использованием шелла с высокой долей сбоев инструментов».

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

Почему Alloy находится посередине

Grafana Alloy в этой схеме — не просто пересыльщик. Здесь применяются правила обработки телеметрии.

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

Это важно, потому что сырая телеметрия агентов полна полей с высокой кардинальностью, которые полезны для анализа, но ужасны в роли индексируемых меток:

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

Если индексировать всё подряд, получите взрыв меток и плохой день.

Поэтому Alloy делает для нас три вещи:

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

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

Почему поток хуков обходит Alloy

Поток хуков уже сформирован под Loki.

К тому моменту, когда send_event.py отправляет событие, мы уже решили, какие поля заслуживают статуса метки, а какие принадлежат структурированному телу JSON. Этот поток идёт напрямую в OTLP-шлюз Grafana Cloud, минуя ещё один проход через Alloy.

Так что в системе чёткое разделение труда:

Alloy укрощает сырой нативный поток OTEL.
Обогащение хуками делает семантические события пригодными для запросов.

Это делает архитектуру проще, чем попытка протолкнуть всё через один путь.

Что реально показывает дашборд

Скриншот ниже — с одного из дашбордов наблюдаемости за нашим агентным рабочим процессом. Это не бенчмарк, а цифры — просто срез на момент времени. Суть в форме данных: лента активности, вызовы инструментов, сбои, промпты и разбивки по агентам, встроенным инструментам, использованию MCP, командам шелла и скиллам.

Полезная часть в том, что этот дашборд живёт на том же стеке Grafana, что и остальная телеметрия агентов. Мы можем фильтровать по исходному агенту и семейству инструментов и смотреть по всем рантаймам сразу, не изобретая отдельную историю наблюдаемости для каждой системы.

Один из дашбордов мониторинга нашего агентного рабочего процесса. Этот скриншот — лишь один срез общего стека Grafana, который также получает телеметрию от других наших агентных рантаймов и систем. Кликните по изображению, чтобы увидеть версию в полном разрешении.

Почему трассы важнее, чем кажется на первый взгляд

Логи говорят нам, к какой категории относилась выполненная работа. Трассы говорят нам, как эта работа разворачивалась во времени.

Это различие важно в агентных системах, потому что «медленно» — слишком грубая характеристика, чтобы быть полезной.

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

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

На практике мы используем поток хуков и трассы Tempo вместе.

Логи хуков отвечают: что за событие произошло?
Трассы отвечают: куда ушло время?

Именно сочетание превращает наблюдаемость из дашборда в объяснение.

Где здесь место Codex

Codex — часть того же стека, но он не идентичен Claude Code.

Для Codex мы подключаем два элемента:

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

Это даёт нам единый фильтр вроде agent_tool="codex-cli" внутри одного и того же потока логов.

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

Это не повод избегать темы. Это и есть суть темы. Настоящие системы наблюдаемости собираются из неидеальных сигналов.

Grafana поверх MCP меняет правила игры

Более крупный сдвиг в том, что Grafana — это не только место, куда люди заходят через браузер.

В этом репозитории мы также предоставляем Grafana через MCP. Это значит, что агент может напрямую делать запросы к Loki, Prometheus и Tempo, вместо того чтобы ждать, пока человек сначала вручную изучит дашборды.

Это превращает наблюдаемость в активный источник данных для рабочего процесса.

Агент может спросить:

Какие семейства инструментов чаще всего давали сбой за последний час?
Какой MCP-сервер доминировал в сессии?
Снизили ли недавние изменения число сбоев инструментов, или просто перенесли работу в сценарии с более интенсивным использованием шелла с теми же ошибками?
Какие трассы показывают наибольшую задержку или повторные попытки?

Как только у вас это есть, вы очень близки к циклу самосовершенствования.

От дашборда к контуру обратной связи

Это часть, которую мы находим самой интересной.

Как только стек наблюдаемости становится доступен для запросов со стороны слоя агентов, телеметрия перестаёт быть пассивным средством отчётности и становится управляющим сигналом.

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

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

Именно так вы переходите от «интересного дашборда» к «измеримой системе улучшения».

Цель — не максимизировать одну категорию инструментов. Цель — прийти к правильному сочетанию CLI, встроенных инструментов, MCP-вызовов и скиллов для реально выполняемой работы.

Что это позволяет нам понять

Как только оба рантайма оказываются в одном стеке Grafana, мы можем гораздо быстрее отвечать на операционные вопросы:

Сосредоточены ли сбои в одном семействе инструментов?
Создают ли рабочие процессы с интенсивным использованием шелла предотвратимые ошибки там, где должен быть инструмент более высокого уровня?
Какие MCP-серверы несут на себе основную нагрузку?
Платим ли мы за активность агента, которая не даёт значимого прогресса?
Связаны ли проблемы в сессии с моделью, инструментами или уровнем оркестрации?

Это особенно полезно в мультиагентных рабочих процессах, где фраза «агент был занят» почти ничего не говорит.

Если один специалист постоянно получает задачи и выдаёт высокий процент сбоев — это проблема маршрутизации или формулировки промпта.

Если один MCP-сервер доминирует во всех вызовах, это может быть либо хорошей архитектурой, либо признаком того, что всё остальное — бесполезный балласт.

Если сбои инструментов растут, а стоимость остаётся высокой, у вас операционная проблема, а не проблема качества.

Если работа в шелле постоянно ломается предсказуемым, предотвратимым образом там, где должен быть инструмент более высокого уровня, — это продуктовый сигнал.

Если один скилл постоянно активируется, но не улучшает результаты, — это сигнал о промпте или маршрутизации.

Настоящий урок

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

Телеметрия рантайма говорит вам, что сделала система.

Телеметрия рабочего процесса говорит вам, что, по мнению агента, он делал.

Нам нужны обе.

Если вы храните только трассы и счётчики, вы упускаете семантический слой. Если вы храните только события хуков, вы упускаете задержки, спаны и более широкую картину рантайма.

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

Именно сочетание делает систему достаточно объяснимой, чтобы ей управлять, и достаточно настраиваемой, чтобы её улучшать.

Что всё ещё несовершенно

Шероховатости остаются.

Не каждое событие хука включает желаемые данные о длительности и токенах.
Некоторые из лучших представлений по таймингам по-прежнему берутся из трасс Tempo, а не из логов хуков.
Codex сегодня семантически беднее Claude Code в обогащённом потоке событий.
Скриншот дашборда — это действующая панель мониторинга, а не отполированный маркетинговый артефакт.

Последний пункт — намеренный. Мы предпочитаем показать настоящую приборную панель, а не делать вид, будто агентные системы волшебным образом самоочевидны.

Почему это важно для Maguyva

Maguyva — про то, чтобы дать агентам лучший интеллектуальный анализ кода. Но как только агенты действительно начинают делать полезную работу, немедленно возникает новое требование: нужно видеть, как они себя ведут.

Качество поиска, качество маршрутизации, выбор инструментов и эффективность использования контекста — всё это становится наблюдаемыми проблемами.

Поэтому мы считаем, что об этом стоит писать. Будущий агентный стек — это не только промпты и инструменты. Это промпты, инструменты и слой инструментирования, который говорит вам, работает ли всё это вместе.

Если вы строите серьёзные агентные рабочие процессы, наблюдаемость — не опциональная инфраструктура. Это часть продукта.

Извлечение знаний из истории: как изменения становятся институциональной памятью

Tue, 03 Feb 2026 00:00:00 GMT

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

Каждая инженерная команда сталкивается с одной и той же проблемой: изменения происходят постоянно, а причины этих изменений забываются. Спустя полгода кто-то спрашивает: «почему мы выбрали DuckDB для этапов пайплайна?» — и ответ живёт только в голове того, кто принял это решение, если этот человек ещё вообще рядом.

Мы построили процесс майнинга, который замыкает этот цикл. Изменения проходят через 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)
Область (какой пакет или зона)
Маркеры несовместимых изменений
Затронутые файлы и метрики сложности

Шаг 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 стали архитектурными решениями. 6799 стали записями журнала изменений. Каждый коммит классифицирован.

Шаг 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 должен появиться в журнале изменений в категории «Добавлено».

Для архитектурных решений:

Сначала получите настоящий идентификатор решения:

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

Затем классифицируйте с этим идентификатором:

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
соответствие формату идентификатора решения
отсутствие дублирующихся записей для одного и того же SHA
реальное существование решений, на которые есть ссылки

После классификации мы валидируем снова перед коммитом изменений.

Почему это важно

Построенный нами контур обратной связи решает несколько проблем:

Для новых участников команды: вместо вопроса «почему мы сделали X?» они могут искать в реестре решений. Контекст сохранён.

Для ИИ-агентов: они не работают в вакууме. Они могут запрашивать институциональные знания перед тем, как давать рекомендации. Когда их просят добавить новый этап пайплайна, они могут обнаружить паттерн DuckDB и следовать ему.

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

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

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

Текущее состояние

На сегодняшний день:

15 637 коммитов обработано конвейером
476 архитектурных решений извлечено и задокументировано
6799 записей журнала изменений зафиксировано
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) — категориям, определяющим, какие агенты загружают какие скиллы:

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

Паттерн спящей области применения

Один из наших самых мощных паттернов — скиллы «принято, но не загружено». Мы называем их спящими областями применения (dormant scopes).

Рассмотрим скиллы научных вычислений из репозитория 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 символов с триггерными фразами («Используйте, когда…», «Когда вам нужно…»), чтобы 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, вендорские скиллы симлинкуются в .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	MCP-инструменты Maguyva	Покажи мне код.

Каждый уровень отвечает на естественный следующий вопрос. Вам редко нужно прыгать сразу на уровень 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.

Цель не в том, чтобы раскрыть всё. Цель в том, чтобы раскрыть ровно то, что нужно, ровно тогда, когда это нужно. Это и есть прогрессивное раскрытие, применённое к архитектуре агентов.

Ground Truths: проверенные факты как опора для ИИ-агентов

Tue, 13 Jan 2026 00:00:00 GMT

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

ИИ-агенты удивительно способны. Они умеют рассуждать, синтезировать и генерировать. Но у них есть фундаментальная слабость: они всё выдумывают. Не со злым умыслом, а уверенно. Агент может изобрести несуществующие параметры API, сослаться на конфигурации, которые никогда не определялись, или применить паттерны из обучающих данных, противоречащие вашей реальной архитектуре.

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

Нам было нужно что-то более явное. Что-то, что нельзя было бы проигнорировать или неверно истолковать. Что-то, что связывало бы решения агентов с проверяемой реальностью.

Мы называем это обоснованными истинами (Ground Truths).

Что такое обоснованная истина?

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

Уникальным идентификатором (вроде 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

Агенты с доступом к шеллу могут искать обоснованные истины программно:

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)

Жизненный цикл обоснованной истины

Обоснованные истины не статичны. Они проходят через определённый жизненный цикл:

Предварительная

Предлагаемая истина на стадии оценки. Утверждение записано, но может измениться:

- 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.

Текущая

Проверенная истина, которую агенты обязаны учитывать. Доказательства прошли валидацию:

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

Устаревшая

Истина, которая больше не применяется. Сохраняется для исторической справки со ссылкой на то, что её заменило:

- 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, мы столкнулись с проблемой, с которой рано или поздно сталкивается любая команда, использующая ИИ-помощников для кода: один агент не может делать всё одинаково хорошо.

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

Поэтому мы построили Orkestra.

Что такое Orkestra?

Orkestra — это система оркестрации агентов для Claude Code и похожих ИИ-инструментов для кода. Она координирует несколько специализированных агентов, каждый со своей экспертизой, под управлением единого оркестратора, который направляет работу нужному специалисту.

Представьте её как кадровое агентство для ИИ-агентов. Оркестратор получает задачу, определяет, какой специалист должен её обработать, и делегирует её с нужным контекстом. Когда работа сделана, результаты возвращаются к оркестратору для синтеза.

Цифры говорят сами за себя:

Компонент	Количество
Специализированные агенты	46
Переиспользуемые скиллы	466
Архетипы личности	27
Склады мышления	11
Стили общения	10
Домены знаний	21

Система персонажей: D&D для агентов

Ключевая идея, лежащая в основе Orkestra, в том, что поведение агента возникает из трёх компонуемых примитивов:

Identity (личность) определяет, чем является агент. Архитектор проектирует структуры систем. Отладчик прослеживает сбои до первопричин. Страж следит за соблюдением норм и границ безопасности. У нас 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-интерфейса, плейбук производительности
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 — источник истины о том, какие агенты существуют, какими скиллами они обладают и здорова ли система. Он запускает валидацию перед синхронизацией, чтобы ловить проблемы на раннем этапе.

Соображения об открытом исходном коде

Мы построили Orkestra, чтобы решить собственную проблему: координацию ИИ-агентов в масштабе для сложной кодовой базы. Обнаруженные нами паттерны не специфичны для нашего домена.

Система композиции персонажей (identity + mindset + style) применима к любой команде, определяющей личности агентов.

Система уровней скиллов (K0–K4) даёт ментальную модель для организации переиспользуемых возможностей по области применимости.

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

Плоская модель оркестрации (один координатор, много специалистов) избегает сложности, сохраняя параллелизм.

Станет ли Orkestra проектом с открытым исходным кодом, зависит от того, представляют ли эти паттерны ценность для других команд, разрабатывающих на Claude Code. Если вы упираетесь в стены, которые мы описали, эта архитектура может помочь.

Чему мы научились

Создание Orkestra научило нас, что оркестрация — это не про то, чтобы сделать агентов умнее. Это про то, чтобы сделать их более сфокусированными.

Один агент с идеальными инструкциями всё равно исчерпает контекст. Один агент со всеми скиллами всё равно запутается, какой из них применить. Один агент, пытающийся быть всем сразу, выдаёт посредственные результаты везде.

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

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

Orkestra питает экосистему агентов за Maguyva, нашей платформой интеллектуального анализа кода. Хотите узнать больше? Свяжитесь с командой.